---

6.5.1 Creating Maps and Iterators ¶

A map handle refers to a mapping object.

Data type: qsmm_map_t ¶

This is a type for a map handle referring to a mapping object supporting the functionality of C++ STL map or multimap template. A map handle is a pointer, so variables of this type can be NULL. The functions qsmm_map_create, qsmm_map_create_sz, qsmm_map_multi_create, and qsmm_map_multi_create_sz allocate a new map handle. The function qsmm_map_destroy frees an existing map handle. You can pass an allocated map handle to API functions taking an argument of qsmm_map_t type until freeing the handle.

There are two ways of dealing with keys and values in key-value pairs of a mapping object:

1. Keys and/or values stored in key-value pair objects are untyped pointers—you should allocate and deallocate memory blocks addressed by the untyped pointers. When the keys and/or values are integer numbers, you can convert them to the standard intptr_t type and store them as pointers without the need to perform memory allocation and deallocation.
2. Memory blocks of key-value pair objects include the content of keys and/or values thereby removing overhead caused by allocating and deallocating memory blocks for keys and/or values. You have to specify the size of each key and/or value when creating the mapping object.

Use the following functions to create a mapping object.

Function: qsmm_map_t qsmm_map_create (qsmm_compar_func_t key_compar_func, void *paramp) ¶

Function: qsmm_map_t qsmm_map_create_sz (size_t key_sz, size_t val_sz, qsmm_compar_func_t key_compar_func, void *paramp) ¶

Function: qsmm_map_t qsmm_map_multi_create (qsmm_compar_func_t key_compar_func, void *paramp) ¶

Function: qsmm_map_t qsmm_map_multi_create_sz (size_t key_sz, size_t val_sz, qsmm_compar_func_t key_compar_func, void *paramp) ¶

These functions create a mapping object. The functions qsmm_map_create and qsmm_map_create_sz create a mapping object supporting the functionality of C++ STL map template, that is, a mapping object that cannot contain duplicate keys in key-value pairs. The functions qsmm_map_multi_create and qsmm_map_multi_create_sz create a mapping object supporting the functionality of C++ STL multimap template, that is, a mapping object that can contain duplicate keys in key-value pairs.

The argument key_compar_func specifies a comparison function for the keys of the mapping object. The argument paramp specifies user parameter of the comparison function.

The functions qsmm_map_create and qsmm_map_multi_create create a mapping object with untyped pointers for its keys and values. The functions qsmm_map_create_sz and qsmm_map_multi_create_sz create a mapping object containing keys with size key_sz not equal to 0 and values with size val_sz. If key_sz is (size_t) -1, the keys are untyped pointers; otherwise, a positive key_sz specifies the size of each key in bytes. If val_sz is (size_t) -1, the values are untyped pointers; otherwise, val_sz specifies the size of each value in bytes. If val_sz is 0, the mapping object cannot store values corresponding to keys, that is, the mapping object is actually a set object, and set elements are the keys of the mapping object.

The call qsmm_map_create(&compar,paramp) is equivalent to the call qsmm_map_create_sz(-1,-1,&compar,paramp). The call qsmm_map_multi_create(&compar,paramp) is equivalent to the call qsmm_map_multi_create_sz(-1,-1,&compar,paramp).

On success, the functions return a non-NULL map handle. If there was not enough memory to create a mapping object, the functions return NULL.

Use the following function to destroy a mapping object.

Function: void qsmm_map_destroy (qsmm_map_t mm) ¶

This function destroys a mapping object specified by a handle mm. You must not use the handle after destroying the mapping object. If mm is NULL, the function has no effect. If keys and/or values in key-value pairs of a mapping object contain untyped pointers to allocated objects, you must free them before destroying the mapping object. If memory blocks of key-value pairs of a mapping object contain memory blocks of keys and/or values that require special uninitialization, you must uninitialize them before destroying the mapping object.

When creating a mapping object, you supply a function for comparing the keys of the mapping object and supply a user parameter for the function. The mapping object contains key-value pairs sorted in ascending order of keys. A description of a type for a pointer to the comparison function is below.

Data type: qsmm_compar_func_t ¶

This is a type for the pointer to a key comparison function. The following declaration corresponds to this type:

typedef int
(*qsmm_compar_func_t)(
    const void *o1p,
    const void *o2p,
    void *paramp
);

The key comparison function shall compare two keys addressed by the arguments o1p and o2p and return a positive value if the first key is greater than the second key, a negative value if the first key is less than the second key, or 0 if the keys are equal. The argument paramp is a user parameter specified when creating a mapping object with the key comparison function.

Use the following functions to obtain the pointer to a key comparison function and obtain its user parameter both specified when creating a mapping object.

Function: qsmm_compar_func_t qsmm_map_key_compar_func (qsmm_map_t mm) ¶

This function returns the pointer to a key comparison function specified when creating a mapping object mm.

Function: void * qsmm_map_key_compar_param (qsmm_map_t mm) ¶

This function returns user parameter of a key comparison function specified when creating a mapping object mm.

Use the following functions to obtain the size of each key and value specified when creating a mapping object.

Function: size_t qsmm_get_map_key_sz (qsmm_map_t mm) ¶

This function returns the size of a key in each key-value pair of a mapping object mm. If a returned value is (size_t) -1, the keys are untyped pointers. Otherwise, a positive returned value is the number of bytes occupied by every key in the memory block of a key-value pair object. The function does not return 0.

Function: size_t qsmm_get_map_val_sz (qsmm_map_t mm) ¶

This function returns the size of a value in each key-value pair of a mapping object mm. If a returned value is (size_t) -1, the values are untyped pointers. Otherwise, a returned value is the number of bytes occupied by every value in the memory block of a key-value pair object. If a returned value is 0, the mapping object cannot store values corresponding to keys, that is, the mapping object is actually a set object, and set elements are the keys of the mapping object.

Map iterators provide access to key-value pairs of mapping objects. An iterator handle refers to a map iterator.

Data type: qsmm_iter_t ¶

This is a type for an iterator handle. It is a pointer, so variables of this type can be NULL.

The functions qsmm_map_iter_create and qsmm_map_multi_iter_create allocate a new iterator handle. An iterator handle allocated by qsmm_map_iter_create is for using with mapping objects created by the functions qsmm_map_create and qsmm_map_create_sz. An iterator handle allocated by qsmm_map_multi_iter_create is for using with mapping objects created by the functions qsmm_map_multi_create and qsmm_map_multi_create_sz.

The function qsmm_iter_destroy frees an existing iterator handle. You can pass an allocated iterator handle to API functions taking an argument of qsmm_iter_t type until freeing the handle.

Use the following functions to create and destroy a map iterator.

Function: qsmm_iter_t qsmm_map_iter_create () ¶

This function creates an iterator for using with mapping objects supporting the functionality of C++ STL map template. On success, the function returns a non-NULL iterator handle. If there was not enough memory to create an iterator, the function returns NULL.

Function: qsmm_iter_t qsmm_map_multi_iter_create () ¶

This function creates an iterator for using with mapping objects supporting the functionality of C++ STL multimap template. On success, the function returns a non-NULL iterator handle. If there was not enough memory to create an iterator, the function returns NULL.

Function: void qsmm_iter_destroy (qsmm_iter_t iter) ¶

This function destroys a map iterator specified by a handle iter. You must not use the handle after destroying the iterator. If iter is NULL, the function has no effect.