Next: Operations on Iterators, Previous: Creating Maps and Iterators, Up: The Implementation of Functionality of STL map Template [Contents][Index]
Basic operations on mapping objects correspond to methods of STL map
and multimap
templates.
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.
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.
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.
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.
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.
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.
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.
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.
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.