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


6.5.1 Creating Maps and Iterators

A mapping object is referred to by a map handle.

Data type: qsmm_map_t

This is a type for a map handle, which corresponds to a mapping object that implements the functionality of STL map or multimap template. It is a pointer, so variables of this type can have the NULL value. A new map handle is allocated by the functions qsmm_map_create, qsmm_map_create_sz, qsmm_map_multi_create, and qsmm_map_multi_create_sz. The function qsmm_map_destroy frees an existing map handle. After allocating a map handle, it can be passed to API functions that take an argument of type qsmm_map_t until the handle is freed.

There are the following 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. In this case, the developer should code allocation and deallocation of memory blocks addressed by the untyped pointers explicitly. However, when keys and/or values are integer numbers, they can be converted to the standard intptr_t type and stored as pointers, which does not require manual memory allocation and deallocation.
  2. Contents of keys and/or values are stored at the end of memory blocks of key-value pair objects. The size of key-value pair object is extended by the size of key and/or value memory block. The size of each key and/or value memory block has to be specified when creating the mapping object. Thus, there is no need to perform manual allocation and deallocation of memory blocks for keys and/or values. At the same time, no additional memory blocks are allocated and deallocated by the mapping object itself—memory blocks of keys and/or values are simply parts of memory blocks of key-value pair objects. This method of dealing with keys and/or values speeds up program operation and removes memory overhead caused by storing additional memory management structures.

To create and destroy a mapping object, the following functions can be used.

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 that implements the functionality of the STL map template, i.e. 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 that implements the functionality of the STL multimap template, i.e. 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 the function qsmm_map_multi_create or qsmm_map_multi_create_sz does not provide storing key-value pairs with the same key in order, in which they were added to the mapping object.

Argument key_compar_func specifies a comparison function for keys of the mapping object. Argument paramp specifies a user parameter of that comparison function.

The functions qsmm_map_create and qsmm_map_multi_create create a mapping object, which keys and values are untyped pointers. The functions qsmm_map_create_sz and qsmm_map_multi_create_sz create a mapping object, which keys have size specified by key_sz, and which values have size specified by val_sz. When key_sz is negative, the keys are untyped pointers. When key_sz is positive, each key has size key_sz bytes. The value of key_sz equal to 0 is disallowed. When val_sz is negative, the values are untyped pointers. When val_sz is positive, each value has size val_sz bytes. When val_sz is 0, the mapping object cannot store values, which correspond to keys, i.e. the mapping object is actually a set object, and set elements are the keys of the mapping object.

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

On success, the functions return a non-zero map handle. If there is not enough memory to create the mapping object, then the functions will return 0.

Function: void qsmm_map_destroy (qsmm_map_t mm)

This function destroys a mapping object specified by handle mm. After mapping object destruction, the map handle must not be used. If mm is NULL, then the function will have no effect. If keys and/or values in key-value pairs of the mapping object contain untyped pointers to manually created objects, then those objects will not be automatically destroyed by this function and must be destroyed manually before destroying the mapping object. If memory blocks of key-value pairs of the mapping object contain memory blocks of keys and/or values, which require special uninitialization, then that uninitialization must be performed manually before destroying the mapping object.

When creating a mapping object, the developer must provide a function for comparing keys of the mapping object and a user parameter of that function. All key-value pairs in a mapping object are sorted is ascending order of keys. The type of a pointer to the comparison function is described below.

Data type: qsmm_compar_func_t

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

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

A key comparison function should compare two keys addressed by arguments o1p and o2p and return a value greater than 0 if the first key is greater than the second key, a value less than 0 if the first key is less than the second key, or 0 if the keys are equal. A user parameter is passed via argument paramp.

The pointer to a key comparison function and the user parameter of that function specified when creating a mapping object can be obtained using the following functions.

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 mapping object mm.

Function: void * qsmm_map_key_compar_param (qsmm_map_t mm)

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

The size of keys and values specified when creating a mapping object can be obtained using the following functions.

Function: int qsmm_map_key_sz (qsmm_map_t mm)

This function returns the size of a key in each key-value pair of mapping object mm. A positive result indicates the size in bytes of the memory block of key in the memory block of key-value pair object. A negative result indicates that the keys are untyped pointers. The function shall 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 mapping object mm. A positive result indicates the size in bytes of the memory block of value in the memory block of key-value pair object. A negative result indicates that the values are untyped pointers. Zero result means that the mapping object cannot store values, which correspond to keys, i.e. the mapping object is actually a set object, and set elements are the keys of the mapping object.

To access key-value pairs of mapping objects, map iterators are used. A map iterator is referred to by an iterator handle.

Data type: qsmm_iter_t

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

A new iterator handle is allocated by the functions qsmm_map_iter_create and qsmm_map_multi_iter_create. An iterator handle allocated by the function qsmm_map_iter_create should be used with mapping objects, which handles were allocated by the functions qsmm_map_create and qsmm_map_create_sz. An iterator handle allocated by the function qsmm_map_multi_iter_create should be used with mapping objects, which handles were allocated by the functions qsmm_map_multi_create and qsmm_map_multi_create_sz.

The function qsmm_map_iter_destroy frees an existing iterator handle. After allocating an iterator handle, it can be passed to API functions that take an argument of type qsmm_iter_t until the handle is freed.

To create and destroy a map iterator, the following functions can be used.

Function: qsmm_iter_t qsmm_map_iter_create ()

This function creates an iterator to be used with mapping objects that implement the functionality of the STL map template. On success, the function returns a non-zero iterator handle. If there is not enough memory to create the iterator, then the function will return 0.

Function: qsmm_iter_t qsmm_map_multi_iter_create ()

This function creates an iterator to be used with mapping objects that implement the functionality of the STL multimap template. On success, the function returns a non-zero iterator handle. If there is not enough memory to create the iterator, then the function will return 0.

Function: void qsmm_map_iter_destroy (qsmm_iter_t iter)

This function destroys a map iterator specified by handle iter. After map iterator destruction, the iterator handle must not be used. If iter is NULL, then the function will have no effect.


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