Next: , Previous: , Up: The Implementation of Functionality of STL map Template   [Contents][Index]


6.5.2 Operations on Maps

Basic operations on mapping objects correspond to methods of STL map and multimap templates.

Function: size_t qsmm_map_size (qsmm_map_t mm)

This function returns the number of key-value pairs contained in a mapping object mm. The function corresponds to the method size of STL map and multimap templates.

Function: int qsmm_map_is_empty (qsmm_map_t mm)

This function returns a positive value if a mapping object mm does not contain key-value pairs, or zero if it does. The function never returns negative values. It corresponds to the method empty of STL map and multimap templates.

Function: int qsmm_map_assign (qsmm_map_t dst, qsmm_map_t src)

This function copies all key-value pairs of a mapping object src to a mapping object dst. The function discards all key-value pairs contained in the mapping object dst before the copying. Either the functions qsmm_map_create and qsmm_map_create_sz or the functions qsmm_map_multi_create and qsmm_map_multi_create_sz must have created the mapping objects src and dst. Both mapping objects must have the same pointer to the key comparison function and its user parameter.

If keys and/or values stored in key-value pair objects are untyped pointers, the function copies or discards those pointers rather than memory blocks addressed by them. If the memory blocks of key-value pair objects contain the memory blocks of keys and/or values, the function copies or discards them.

The function qsmm_map_assign corresponds to operator= of STL map and multimap templates. The function returns a non-negative value on success or a negative value on out of memory error.

Function: int qsmm_map_insert (qsmm_map_t mm, void *keyp, void *valp, qsmm_iter_t result_loc)

This function inserts a key-value pair in a mapping object mm. The argument keyp specifies the key of this pair. The argument valp specifies the value of this pair.

If keys and/or values stored in key-value pair objects are untyped pointers, the function inserts an untyped pointer keyp and/or valp in the mapping object. If the memory blocks of key-value pair objects contain the memory blocks of keys and/or values, the function copies a memory block addressed by keyp and/or valp to an inserted key-value pair object. If the memory blocks of key-value pair objects contain the memory blocks of values, and valp is NULL, the function initializes the memory block of a value in the key-value pair object with zero bytes.

If the function qsmm_map_create or qsmm_map_create_sz created the mapping object, then it cannot contain duplicate keys. A comparison function specified when creating the mapping object determines the uniqueness of keys. When adding a new key-value pair with a key already contained in the mapping object, the new key-value pair replaces an old key-value pair. Replacing the old pair may cause a memory leak if the pair contains pointers to allocated memory blocks. If the function qsmm_map_multi_create or qsmm_map_multi_create_sz created the mapping object, then it can contain multiple key-value pairs with the same key.

If result_loc is not NULL, after successful function completion, an iterator result_loc addresses a new key-value pair inserted in the mapping object. The type of this iterator must agree with the type of the mapping object. Calling the function with a non-NULL result_loc is useful when the memory blocks of key-value pair objects contain the memory blocks of values, and valp is NULL. In this case, the call qsmm_map_iter_val(result_loc) returns a pointer to the memory block of a value preinitialized with zero bytes for setting the value.

This function corresponds to the method insert of STL map and multimap templates. The function returns a non-negative value on success or a negative value on out of memory error.

Function: void qsmm_map_clear (qsmm_map_t mm)

This function removes all key-value pairs from a mapping object mm. The function does not deallocate memory blocks addressed by pointers in the keys and/or values of key-value pairs. The function corresponds to the method clear of STL map and multimap templates.

Function: void qsmm_map_find (qsmm_map_t mm, const void *keyp, qsmm_iter_t result)

This function finds in a mapping object mm a key-value pair that has a key equal to keyp. If the function qsmm_map_multi_create or qsmm_map_multi_create_sz created the mapping object, the function qsmm_map_find finds in the mapping object the first key-value pair that has a key equal to keyp. A comparison function specified when creating the mapping object tests the equality of keys. The function qsmm_map_find corresponds to the method find of STL map and multimap templates.

After function completion, an iterator result addresses a key-value pair found. If the key-value pair not found, the iterator addresses a location just after the last key-value pair in the mapping object. An iterator type must agree with a mapping object type.

Function: void qsmm_map_lower_bound (qsmm_map_t mm, const void *keyp, qsmm_iter_t result)

This function finds in a mapping object mm the first key-value pair that has a key greater than or equal to keyp. The function corresponds to the method lower_bound of STL map and multimap templates.

After function completion, an iterator result addresses a key-value pair found. If the key-value pair not found, the iterator addresses a location just after the last key-value pair in the mapping object. An iterator type must agree with a mapping object type.

Function: void qsmm_map_upper_bound (qsmm_map_t mm, const void *keyp, qsmm_iter_t result)

This function finds in a mapping object mm the first key-value pair that has a key greater than keyp. The function corresponds to the method upper_bound of STL map and multimap templates.

After function completion, an iterator result addresses a key-value pair found. If the key-value pair not found, the iterator addresses a location just after the last key-value pair in the mapping object. An iterator type must agree with a mapping object type.

Function: void qsmm_map_erase (qsmm_map_t mm, qsmm_iter_t where)

This function removes from a mapping object mm a key-value pair addressed by an iterator where. The function does not deallocate memory blocks addressed by pointers in the key and/or value of this key-value pair. The function corresponds to the method erase of STL map and multimap templates.

Note: when removing a key-value pair from a mapping object, you must uninitialize and/or destroy the key of this pair after calling the function qsmm_map_erase rather than before calling it, because, in the current implementation, qsmm_map_erase may call a key comparison function for the key of this key-value pair, and that key must be a valid object.


Next: , Previous: , Up: The Implementation of Functionality of STL map Template   [Contents][Index]