Next: Operations on Maps, Up: The Implementation of Functionality of STL map Template [Contents][Index]
A map handle refers to a mapping object.
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:
intptr_t
type and store them as pointers without the need to perform memory allocation and deallocation.
Use the following functions to create and destroy a mapping object.
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
.
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.
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.
This function returns the pointer to a key comparison function specified when creating a mapping object 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.
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.
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.
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.
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
.
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
.
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.