---

6.5.2 Operations on Maps ¶

Basic operations on mapping objects correspond to methods of C++ 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_is_map_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 key size, the same value size, and 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 the pointers rather than memory blocks addressed by them. If memory blocks of key-value pair objects contain 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 error code on failure. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

One of the following conditions is true:

• qsmm_map_create or qsmm_map_create_sz created the mapping object src, whereas qsmm_map_multi_create or qsmm_map_multi_create_sz created the mapping object dst;
• qsmm_map_multi_create or qsmm_map_multi_create_sz created the mapping object src, whereas qsmm_map_create or qsmm_map_create_sz created the mapping object dst;
• mapping objects src and dst have different key size or value size;
• mapping objects src and dst have different pointers to the key comparison function or its user parameter.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

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 the pair. The argument valp specifies the value of the pair.

If keys and/or values in key-value pair objects are untyped pointers, the function inserts a key-value pair object with an untyped pointer keyp and/or valp. If memory blocks of key-value pair objects contain 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 memory blocks of key-value pair objects contain memory blocks of values, and valp is NULL, the function initializes 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, it cannot contain duplicate keys. A key comparison function specified when creating the mapping object determines the uniqueness of keys. When inserting 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, it can contain multiple key-value pairs with the same key. If the mapping object already has a key specified by keyp, an inserted key-value pair goes after all key-value pairs with this key.

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

The function qsmm_map_insert corresponds to the method insert of STL map and multimap templates.

If qsmm_map_multi_create or qsmm_map_multi_create_sz created the mapping object, or it did not have a key specified by keyp, qsmm_map_insert returns a positive value. If qsmm_map_create or qsmm_map_create_sz created the mapping object, it already contained a key-value pair with a key specified by keyp, and qsmm_map_insert overwrote the key-value pair with a key and value specified by keyp and valp respectively, this function returns 0. On out of memory error, the function returns negative error code QSMM_ERR_NOMEM.

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 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, qsmm_map_find finds the first key-value pair that has a key equal to keyp. A key 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. The type of the iterator must agree with the type of the mapping object.

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. The type of the iterator must agree with the type of the mapping object.

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. The type of the iterator must agree with the type of the mapping object.

Function: void qsmm_map_iter_begin (qsmm_map_t mm, qsmm_iter_t result) ¶

This function retrieves the location of the first key-value pair in a mapping object mm. After function completion, an iterator result addresses that key-value pair. If the mapping object does not contain key-value pairs, the iterator addresses a location commonly designated as a location just after the last key-value pair in the mapping object. The type of the iterator must agree with the type of the mapping object. The function corresponds to the method begin of STL map and multimap templates.

Function: void qsmm_map_iter_end (qsmm_map_t mm, qsmm_iter_t result) ¶

This function makes an iterator result address a location just after the last key-value pair in a mapping object mm. The type of the iterator must agree with the type of the mapping object. The function corresponds to the method end of STL map and multimap templates.

Function: void qsmm_map_iter_rbegin (qsmm_map_t mm, qsmm_iter_t result) ¶

This function sets an iterator result to be a reverse iterator addressing the last key-value pair (in ascending order of keys) in a mapping object mm. If the mapping object does not contain key-value pairs, the iterator addresses a location commonly designated as a location just before the first key-value pair in the mapping object. The type of the iterator must agree with the type of the mapping object. The function corresponds to the method rbegin of STL map and multimap templates.

Function: void qsmm_map_iter_rend (qsmm_map_t mm, qsmm_iter_t result) ¶

This function sets an iterator result to be a reverse iterator addressing a location just before the first key-value pair in a mapping object mm. The type of the iterator must agree with the type of the mapping object. The function corresponds to the method rend of STL map and multimap templates.

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 the key-value pair. The function corresponds to the method erase of STL map and multimap templates.