DOKK / manpages / debian 10 / libqb-dev / qbmap.h.3.en
qbmap.h(3) libqb qbmap.h(3)

qbmap.h - This provides a map interface to a Patricia trie, hashtable or skiplist.

#include <stdint.h>
#include <unistd.h>


#define QB_MAP_NOTIFY_DELETED 1
#define QB_MAP_NOTIFY_REPLACED 2
#define QB_MAP_NOTIFY_INSERTED 4
#define QB_MAP_NOTIFY_RECURSIVE 8
#define QB_MAP_NOTIFY_FREE 16


typedef struct qb_map qb_map_t
This is an opaque data type representing an instance of a map. typedef struct qb_map_iter qb_map_iter_t
This is an opaque data type representing an iterator instance. typedef void(* qb_map_notify_fn) (uint32_t event, char *key, void *old_value, void *value, void *user_data)
typedef int32_t(* qb_map_transverse_fn) (const char *key, void *value, void *user_data)


qb_map_t * qb_hashtable_create (size_t max_size)
Create an unsorted map based on a hashtable. qb_map_t * qb_skiplist_create (void)
Create a sorted map using a skiplist. qb_map_t * qb_trie_create (void)
Create a sorted map using a Patricia trie or 'Radix tree'. void qb_trie_dump (qb_map_t *m)
print out the nodes in the trie int32_t qb_map_notify_add (qb_map_t *m, const char *key, qb_map_notify_fn fn, int32_t events, void *user_data)
Add a notifier to the map. int32_t qb_map_notify_del (qb_map_t *m, const char *key, qb_map_notify_fn fn, int32_t events)
Delete a notifier from the map. int32_t qb_map_notify_del_2 (qb_map_t *m, const char *key, qb_map_notify_fn fn, int32_t events, void *user_data)
Delete a notifier from the map (including the userdata). void qb_map_put (qb_map_t *map, const char *key, const void *value)
Inserts a new key and value into a qb_map_t. void * qb_map_get (qb_map_t *map, const char *key)
Gets the value corresponding to the given key. int32_t qb_map_rm (qb_map_t *map, const char *key)
Removes a key/value pair from a map. size_t qb_map_count_get (qb_map_t *map)
Get the number of items in the map. void qb_map_foreach (qb_map_t *map, qb_map_transverse_fn func, void *user_data)
Calls the given function for each of the key/value pairs in the map. qb_map_iter_t * qb_map_iter_create (qb_map_t *map)
Create an iterator. qb_map_iter_t * qb_map_pref_iter_create (qb_map_t *map, const char *prefix)
Create a prefix iterator. const char * qb_map_iter_next (qb_map_iter_t *i, void **value)
Get the next item. void qb_map_iter_free (qb_map_iter_t *i)
free the iterator void qb_map_destroy (qb_map_t *map)
Destroy the map, removes all the items from the map.

This provides a map interface to a Patricia trie, hashtable or skiplist.

Ordering

The hashtable is NOT ordered, but ptrie and skiplist are.

Iterating

Below is a simple example of how to iterate over a map. 

const char *p;
void *data;
qb_map_iter_t *it = qb_map_iter_create(m);
for (p = qb_map_iter_next(it, &data); p; p = qb_map_iter_next(it, &data)) {


    printf("%s > %s0, p, (char*) data);
}
qb_map_iter_free(it);

Deletion of items within the iterator is supported. But note do not free the item memory in the iterator. If you need to free the data items then register for a notifier and free the memory there. This is required as the items are reference counted.

qb_map_notify_add(m, NULL, my_map_free_handler,


             QB_MAP_NOTIFY_FREE, NULL);

Notifications

These allow you to get callbacks when values are inserted/removed or replaced.

Note:

hashtable only supports deletion and replacement notificatins. There is also a special global callback for freeing deleted and replaced values (QB_MAP_NOTIFY_FREE).

See also:

qb_map_notify_add() qb_map_notify_del_2()

Prefix matching

The ptrie supports prefixes in the iterator:

it = qb_map_pref_iter_create(m, "aa");
while ((p = qb_map_iter_next(it, &data)) != NULL) {


    printf("%s > %s0, p, (char*)data);
}
qb_map_iter_free(it);

The ptrie also supports prefixes in notifications: (remember to pass QB_MAP_NOTIFY_RECURSIVE into the notify_add.

qb_map_notify_add(m, "root", my_map_notification,


            (QB_MAP_NOTIFY_INSERTED|


             QB_MAP_NOTIFY_DELETED|


             QB_MAP_NOTIFY_REPLACED|


             QB_MAP_NOTIFY_RECURSIVE),


            NULL);

This is an opaque data type representing an iterator instance.

This is an opaque data type representing an instance of a map.

qb_map_t* qb_hashtable_create (size_t max_size)

Create an unsorted map based on a hashtable.

Parameters:

max_size maximum size of the hashtable

Returns:

the map instance

Get the number of items in the map.

Destroy the map, removes all the items from the map.

Calls the given function for each of the key/value pairs in the map. The function is passed the key and value of each pair, and the given data parameter. The map is traversed in sorted order.

Gets the value corresponding to the given key.

Return values:

NULL (if the key does not exist)
a pointer to the value

qb_map_iter_t* qb_map_iter_create (qb_map_t * map)

Create an iterator.

free the iterator

Parameters:

i the iterator

Get the next item.

Parameters:

i the iterator
value (out) the next item's value

Return values:

the next key
NULL - the end of the iteration

Add a notifier to the map.

Parameters:

m the map instance
key the key (or prefix) to attach the notification to.
fn the callback
events the type of events to register for.
user_data a pointer to be passed into the callback

Note:

QB_MAP_NOTIFY_INSERTED is only valid on tries.

you can use key prefixes with trie maps.

Return values:

0 success
-errno failure

Delete a notifier from the map.

Note:

the key,fn and events must match those you added.

Parameters:

m the map instance
key the key (or prefix) to attach the notification to.
fn the callback
events the type of events to register for.

Return values:

0 success
-errno failure

Delete a notifier from the map (including the userdata).

Note:

the key, fn, events and userdata must match those you added.

Parameters:

m the map instance
key the key (or prefix) to attach the notification to.
fn the callback
events the type of events to register for.
user_data a pointer to be passed into the callback

Return values:

0 success
-errno failure

qb_map_iter_t* qb_map_pref_iter_create (qb_map_t * map, const char * prefix)

Create a prefix iterator. This will iterate over all items with the given prefix.

Note:

this is only supported by the trie.

Inserts a new key and value into a qb_map_t. If the key already exists in the qb_map_t, it gets replaced by the new key.

Removes a key/value pair from a map.

qb_map_t* qb_skiplist_create (void)

Create a sorted map using a skiplist.

Returns:

the map instance

qb_map_t* qb_trie_create (void)

Create a sorted map using a Patricia trie or 'Radix tree'.

print out the nodes in the trie (for debug purposes)

Generated automatically by Doxygen for libqb from the source code.

Fri Apr 26 2019 Version 1.0.5