qbmap.h (3)

#include <stdint.h>

#include <unistd.h>

Defines

#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

Typedefs

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)

Functions

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 > %s\n', 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 > %s\n', 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);

#define \fBQB_MAP_NOTIFY_DELETED\fP 1

#define \fBQB_MAP_NOTIFY_FREE\fP 16

#define \fBQB_MAP_NOTIFY_INSERTED\fP 4

#define \fBQB_MAP_NOTIFY_RECURSIVE\fP 8

#define \fBQB_MAP_NOTIFY_REPLACED\fP 2

typedef struct qb_map_iter \fBqb_map_iter_t\fP

This is an opaque data type representing an iterator instance.

typedef void(* \fBqb_map_notify_fn\fP)(uint32_t event, char *key, void *old_value, void *value, void *user_data)

typedef struct qb_map \fBqb_map_t\fP

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

typedef int32_t(* \fBqb_map_transverse_fn\fP)(const char *key, void *value, void *user_data)

\fBqb_map_t\fP* \fBqb_hashtable_create\fP (size_tmax_size)

Create an unsorted map based on a hashtable. Parameters:

max_size maximum size of the hashtable

Returns:

the map instance

size_t \fBqb_map_count_get\fP (\fBqb_map_t\fP *map)

Get the number of items in the map.

void \fBqb_map_destroy\fP (\fBqb_map_t\fP *map)

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

void \fBqb_map_foreach\fP (\fBqb_map_t\fP *map, \fBqb_map_transverse_fn\fPfunc, void *user_data)

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.

void* \fBqb_map_get\fP (\fBqb_map_t\fP *map, const char *key)

Gets the value corresponding to the given key. Return values:

NULL (if the key does not exist)

a pointer to the value

\fBqb_map_iter_t\fP* \fBqb_map_iter_create\fP (\fBqb_map_t\fP *map)

Create an iterator.

void \fBqb_map_iter_free\fP (\fBqb_map_iter_t\fP *i)

free the iterator Parameters:

i the iterator

const char* \fBqb_map_iter_next\fP (\fBqb_map_iter_t\fP *i, void **value)

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

int32_t \fBqb_map_notify_add\fP (\fBqb_map_t\fP *m, const char *key, \fBqb_map_notify_fn\fPfn, int32_tevents, void *user_data)

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

int32_t \fBqb_map_notify_del\fP (\fBqb_map_t\fP *m, const char *key, \fBqb_map_notify_fn\fPfn, int32_tevents)

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

int32_t \fBqb_map_notify_del_2\fP (\fBqb_map_t\fP *m, const char *key, \fBqb_map_notify_fn\fPfn, int32_tevents, void *user_data)

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

\fBqb_map_iter_t\fP* \fBqb_map_pref_iter_create\fP (\fBqb_map_t\fP *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.

void \fBqb_map_put\fP (\fBqb_map_t\fP *map, const char *key, const void *value)

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.

int32_t \fBqb_map_rm\fP (\fBqb_map_t\fP *map, const char *key)

Removes a key/value pair from a map.

\fBqb_map_t\fP* \fBqb_skiplist_create\fP (void)

Create a sorted map using a skiplist. Returns:

the map instance

\fBqb_map_t\fP* \fBqb_trie_create\fP (void)

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

void \fBqb_trie_dump\fP (\fBqb_map_t\fP *m)

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

Generated automatically by Doxygen for libqb from the source code.