qbmap.h(3)

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

SYNOPSIS

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

  Macros
#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.

Detailed Description

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, 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, 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);

Macro Definition Documentation

  #define QB_MAP_NOTIFY_DELETED 1

  #define QB_MAP_NOTIFY_FREE 16

  #define QB_MAP_NOTIFY_INSERTED 4

  #define QB_MAP_NOTIFY_RECURSIVE 8

  #define QB_MAP_NOTIFY_REPLACED 2

Typedef Documentation

  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 struct qb_map qb_map_t

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

  typedef int32_t(* qb_map_transverse_fn) (const char *key, void *value, void *user_data)

Function Documentation

  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

  size_t qb_map_count_get (qb_map_t * map)

Get the number of items in the map.

  void qb_map_destroy (qb_map_t * map)

Destroy the map, removes all the items from 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. The function is passed the key and value of each pair, and the given data parameter. The map is traversed in sorted order.

  void* qb_map_get (qb_map_t * 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

  qb_map_iter_t* qb_map_iter_create (qb_map_t * map)

Create an iterator.

  void qb_map_iter_free (qb_map_iter_t * i)

free the iterator

Parameters:
    i the iterator

  const char* qb_map_iter_next (qb_map_iter_t * 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 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.

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 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.

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 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).

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.

  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. If the key already exists in the qb_map_t, it gets replaced by the new key.

  int32_t qb_map_rm (qb_map_t * map, const char * 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'.

  void qb_trie_dump (qb_map_t * m)

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

Author

Generated automatically by Doxygen for libqb from the source code.