void* pblMapRemove

( PblMap* map, void* key,
  size_t keyLength,
  size_t* valueLengthPtr )

Removes the mapping for this key from this map if it is present.

Documentation

Removes the mapping for this key from this map if it is present.

More formally, if this map contains a mapping from a key k to a value v such that (key==null ? k==null : memcmp( key, k, keyLength ) == 0, that mapping is removed. (The map can contain at most one such mapping.)

Returns the previous value associated with key, NULL if there was no mapping for key or (void*)-1 in case of an error.

Note: If a valid pointer to a value is returned, the value returned is malloced on the heap. It is the caller's responsibility to free that memory once it is no longer needed.

For hash maps this method has a time complexity of O(1). For tree maps this method has a time complexity of O(Log N).

Parameters:

map - The map to remove from
key - Key whose association is removed
keyLength - Length of the key
valueLengthPtr - Out: Length of the value returned

Returns:

void * retptr != (void*)-1: The previously associated value.
void * retptr == (void*)-1: An error, see pbl_errno:
PBL_ERROR_OUT_OF_MEMORY - Out of memory.

Alphabetic index