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 STL map or multimap template. The 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 the 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 those 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. The memory blocks of key-value pair objects include the contents of keys and/or values 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 and destroy 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 (int key_sz, int 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 (int key_sz, int 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 STL map template, that is, a mapping object that may not 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 STL multimap template, that is, a mapping object that may contain duplicate keys in key-value pairs. However, as distinct from the STL multimap template, a mapping object created by qsmm_map_multi_create or qsmm_map_multi_create_sz does not provide storing key-value pairs with the same key in the order of their insertion into the mapping object.

The argument key_compar_func specifies a comparison function for the keys of this mapping object. The argument paramp specifies the user parameter of this 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 negative, the keys are untyped pointers. If key_sz is positive, each key has size key_sz bytes. If val_sz is negative, the values are untyped pointers. If val_sz is positive, each value has size val_sz 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 this 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.

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 map handle after destroying the mapping object. If mm is NULL, the function has no effect. If keys and/or values in the key-value pairs of this mapping object contain untyped pointers to allocated objects, you must free them before destroying the mapping object. If the memory blocks of key-value pairs of this mapping object contain the 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 provide a function for comparing the keys of this mapping object and a user parameter for this function. The mapping object contains key-value pairs sorted in ascending order of keys. A description of a type for the 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 this key comparison function.

Use the following functions to obtain the pointer to a key comparison function and the user parameter of this comparison function 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 the 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: int qsmm_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 positive, it is the number of bytes occupied by the key in the memory block of a key-value pair object. If a returned value is negative, the keys are untyped pointers. The function does not return 0.

Function: int qsmm_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 positive, it is the number of bytes occupied by the value in the memory block of a key-value pair object. If a returned value is negative, the values are untyped pointers. 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 this 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_map_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 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 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_map_iter_destroy (qsmm_iter_t iter)

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