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


6.5.2 Operations on Maps

In this section, basic operations on mapping objects are described. Every operation corresponds to a method 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 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 mapping object mm does not contain key-value pairs, or zero if it does. Negative values are never returned. The function 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 mapping object src to mapping object dst. All key-value pairs, which were in mapping object dst before the copying, are discarded. Mapping objects src and dst must be both created using either the functions qsmm_map_create and qsmm_map_create_sz or the functions qsmm_map_multi_create and qsmm_map_multi_create_sz, 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, then only those pointers will be copied or discarded, memory blocks the pointers may point to will not be affected. If memory blocks of key-value pair objects contain memory blocks of keys and/or values, then the contents of those memory blocks will be copied or discarded.

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 mapping object mm. Argument keyp specifies a key of the pair. Argument valp specifies a value of the pair.

If keys and/or values stored in key-value pair objects are untyped pointers, then the function will insert untyped pointer keyp and/or valp in the mapping object. If memory blocks of key-value pair objects contain memory blocks of keys and/or values, then a memory block addressed by keyp and/or valp will be copied to the key-value pair object being inserted. If memory blocks of key-value pair objects contain memory blocks of values and valp is NULL, then the memory block of value in the key-value pair object being inserted will be initialized with zero bytes.

If mapping object mm is created using the function qsmm_map_create or qsmm_map_create_sz, then it cannot contain duplicate keys. Uniqueness of keys is determined using a comparison function specified when creating the mapping object. When adding a new key-value pair with a key, which is 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 manually allocated memory blocks. If mapping object mm is created using the function qsmm_map_multi_create or qsmm_map_multi_create_sz, then it can contain multiple key-value pairs with the same key.

If result_loc is not 0, then after successful function completion, iterator result_loc will point to a new key-value pair inserted in mapping object mm. The type of iterator result_loc must agree with the type of mapping object mm. Calling the function with non-zero result_loc is useful when memory blocks of key-value pair objects contain memory blocks of values and valp is 0. In this case, a pointer to the memory block of value preinitialized with zero bytes can be obtained by call qsmm_map_iter_val(result_loc) 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 mapping object mm. Memory blocks, pointers to which might be held in key-value pairs, are not affected. 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 mapping object mm a key-value pair that has a key equal to keyp. If the mapping object is created using the function qsmm_map_multi_create or qsmm_map_multi_create_sz, then the function will find in the mapping object the first key-value pair that has a key equal to keyp. The equality of keys is tested using a comparison function specified when creating the mapping object. The function qsmm_map_find corresponds to the method find of STL map and multimap templates.

After function completion, iterator result refers to a key-value pair found. If a key-value pair is not found, then iterator result will refer to a place just after the last key-value pair in the mapping object. The type of iterator result must agree with the type of mapping object mm.

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

This function finds in 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, iterator result refers to a key-value pair found. If a key-value pair is not found, then iterator result will refer to a place just after the last key-value pair in the mapping object. The type of iterator result must agree with the type of mapping object mm.

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

This function finds in 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, iterator result refers to a key-value pair found. If a key-value pair is not found, then iterator result will refer to a place just after the last key-value pair in the mapping object. The type of iterator result must agree with the type of mapping object mm.

Function: void qsmm_map_erase (qsmm_map_t mm, qsmm_iter_t where)

This function removes from mapping object mm a key-value pair addressed by iterator where. Memory blocks, pointers to which might be contained in the key-value pair, are not affected. The function corresponds to the method erase of STL map and multimap templates.

Note: when removing a key-value pair from a mapping object, the key of the pair must be uninitialized and/or destroyed after calling the function qsmm_map_erase, not before. It is because in the current implementation the function qsmm_map_erase may call a key comparison function for the key of a key-value pair being removed, and that key must be a valid object.


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