void* pblMapPut

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

Associates the specified value with the specified key in this map.

Documentation

Associates the specified value with the specified key in this map.

If the map previously contained a mapping for the key, the old value is replaced by the specified value. (A map m is said to contain a mapping for a key k if and only if pblMapContainsKey(k) would return true.)

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 add to
key - Key to add a mapping for
keyLength - Length of the key
value - Value of the new mapping
valueLength - Length of the value
valueLengthPtr - Out: Length of the value returned

Returns:

void * retptr != (void*)-1: The previously associated value.
void * retptr == NULL: There was no previously associated value.
void * retptr == (void*)-1: An error, see pbl_errno:
PBL_ERROR_OUT_OF_MEMORY - Out of memory.
PBL_ERROR_OUT_OF_BOUNDS - Maximum capacity of the hash set exceeded.

Alphabetic index