Provided by: libqb-dev_1.0.1-1ubuntu1_amd64 bug

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

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.