/**
* Returns an iterator over the elements in this collection in proper sequence.
*
* The iterator starts the iteration at the beginning of the collection.
*
* <B>Note</B>: The memory allocated by this method for the iterator returned needs to be released
* by calling pblIteratorFree() once the iterator is no longer needed.
*
* The iterators returned by the this method are fail-fast:
* if the collection is structurally modified at any time after the iterator is created,
* in any way except through the Iterator's own remove or add methods,
* the iterator will return a PBL_ERROR_CONCURRENT_MODIFICATION error.
*
* Thus, in the face of concurrent modification,
* the iterator fails quickly and cleanly,
* rather than risking arbitrary, non-deterministic
* behavior at an undetermined time in the future.
*
* This method has a time complexity of O(1).
*
* @return void * retptr != NULL: The iterator.
* @return void * retptr == NULL: An error, see pbl_errno:
*
* <BR>PBL_ERROR_OUT_OF_MEMORY - Out of memory.
* <BR>PBL_ERROR_PARAM_COLLECTION - The collection cannot be iterated.
*/
PblIterator * pblIteratorNew(
PblCollection * collection /** The collection to create the iterator for */
)
{
PblIterator * iterator;
if( !PBL_COLLECTION_IS_COLLECTION( collection ) )
{
pbl_errno = PBL_ERROR_PARAM_COLLECTION;
return NULL;
}
iterator = pbl_malloc( "pblIteratorNew", sizeof(PblIterator) );
if( !iterator )
{
return NULL;
}
if( pblIteratorInit( collection, iterator ) < 0 )
{
PBL_FREE( iterator );
return NULL;
}
return (PblIterator *)iterator;
}
/**
* Aggregates a collection by calling the aggregation function on every element
* of the collection while running through the collection with an iterator.
*
* The application context supplied is passed to the aggregation function
* for each element.
*
* If the aggregation function for an element returns a value > 0,
* the aggregation is terminated immediately and the return value of
* the aggregation function is given back to the caller.
*
* Otherwise the aggregation is continued to the next element
* of the collection until the iterator reaches its end.
*
* This method has a time complexity of O(N),
* with N being the size of the collection.
*
* @return int rc > 0: The aggregation was terminated with the return code of the aggregation function.
* @return int rc == 0: The aggregation succeeded, all elements where aggregated.
* @return int rc < 0: An error, see pbl_errno:
*
* <BR>PBL_ERROR_PARAM_COLLECTION - The collection cannot be iterated.
* <BR>PBL_ERROR_CONCURRENT_MODIFICATION - The collection was modified concurrently.
*/
int pblCollectionAggregate(
PblCollection * collection, /** The collection to aggregate. */
void * context, /** The application context to pass to the aggregation function. */
int ( *aggregation ) /** The aggregation function called on every collection element. */
(
void * context, /** The application context passed. */
int index, /** The index of the element passed. */
void * element /** The collection element to aggregate. */
)
)
{
PblIterator iteratorBuffer;
PblIterator * iterator = (PblIterator *)&iteratorBuffer;
int rc = 0;
int hasNext;
int index = 0;
void * element;
/*
* Get the iterator for this collection
*/
if( pblIteratorInit( collection, &iteratorBuffer ) < 0 )
{
return -1;
}
while( ( hasNext = pblIteratorHasNext( iterator ) ) > 0 )
{
element = pblIteratorNext( iterator );
if( element == (void*)-1 )
{
// Concurrent modification
//
return -1;
}
/*
* Call the aggregation function on the element
*/
rc = ( *( aggregation ) )( context, index++, element );
if( rc > 0 )
{
return rc;
}
}
if( hasNext < 0 )
{
// Concurrent modification
//
return -1;
}
return 0;
}
/**
* Returns true if this map contains a mapping for the specified value.
*
* This method has a time complexity of O(N).
*
* @return int rc > 0: The map contains a mapping for the specified value.
* @return int rc == 0: The map did not contain a mapping for the value.
* @return int rc < 0: An error, see pbl_errno:
*
* <BR>PBL_ERROR_CONCURRENT_MODIFICATION - The underlying collection was modified concurrently.
*/
int pblMapContainsValue( /* */
PblMap * map, /** The map to check */
void * value, /** Value whose presence in this map is to be tested */
size_t valueLength /** Length of the value */
)
{
int hasNext;
void * element;
PblMapEntry * entry;
PblIterator iterator;
pblIteratorInit( map->entrySet, &iterator );
while( ( hasNext = pblIteratorHasNext( &iterator ) ) > 0 )
{
element = pblIteratorNext( &iterator );
if( element == (void*)-1 )
{
// Concurrent modification
//
return -1;
}
entry = (PblMapEntry *)element;
if( !entry )
{
continue;
}
if( entry->valueLength != valueLength )
{
continue;
}
if( 0 == valueLength )
{
return 1;
}
if( 0 == memcmp( value, entry->buffer + entry->keyLength, valueLength ) )
{
return 1;
}
}
return 0;
}
/**
* Copies all of the mappings from the specified source map to this map.
* These mappings will replace any mappings that this map had for any
* of the keys currently in the specified map.
*
* For hash maps this method has a time complexity of O(M).
* For tree maps this method has a time complexity of O(M * Log N).
* With M being the number of elements in the source map and
* N being the number of elements in the target map.
*
* @return int rc == 0: Ok.
* @return int rc < 0: An error, see pbl_errno:
*
* <BR>PBL_ERROR_CONCURRENT_MODIFICATION - The source map was modified concurrently.
* <BR>PBL_ERROR_OUT_OF_MEMORY - Out of memory.
*/
int pblMapPutAll( /* */
PblMap * map, /** The map to copy the entries to */
PblMap * sourceMap /** The map to copy the entries from */
)
{
int hasNext;
void * element;
PblMapEntry * entry;
PblIterator iterator;
pblIteratorInit( sourceMap->entrySet, &iterator );
while( ( hasNext = pblIteratorHasNext( &iterator ) ) > 0 )
{
element = pblIteratorNext( &iterator );
if( element == (void*)-1 )
{
// Concurrent modification
//
return -1;
}
entry = (PblMapEntry *)element;
if( !entry )
{
continue;
}
if( pblMapAdd( map, entry->buffer, entry->keyLength, entry->buffer
+ entry->keyLength, entry->valueLength ) < 0 )
{
return -1;
}
}
return 0;
}
