.TH "qbmap.h" 3 "Thu Dec 21 2017" "Version 1.0.3" "libqb" \" -*- nroff -*-
.ad l
.nh
.SH NAME
qbmap.h \-
.PP
This provides a map interface to a Patricia trie, hashtable or skiplist\&.
.SH SYNOPSIS
.br
.PP
\fC#include <stdint\&.h>\fP
.br
\fC#include <unistd\&.h>\fP
.br
.SS "Macros"
.in +1c
.ti -1c
.RI "#define \fBQB_MAP_NOTIFY_DELETED\fP 1"
.br
.ti -1c
.RI "#define \fBQB_MAP_NOTIFY_REPLACED\fP 2"
.br
.ti -1c
.RI "#define \fBQB_MAP_NOTIFY_INSERTED\fP 4"
.br
.ti -1c
.RI "#define \fBQB_MAP_NOTIFY_RECURSIVE\fP 8"
.br
.ti -1c
.RI "#define \fBQB_MAP_NOTIFY_FREE\fP 16"
.br
.in -1c
.SS "Typedefs"
.in +1c
.ti -1c
.RI "typedef struct qb_map \fBqb_map_t\fP"
.br
.RI "\fIThis is an opaque data type representing an instance of a map\&. \fP"
.ti -1c
.RI "typedef struct qb_map_iter \fBqb_map_iter_t\fP"
.br
.RI "\fIThis is an opaque data type representing an iterator instance\&. \fP"
.ti -1c
.RI "typedef void(* \fBqb_map_notify_fn\fP )(uint32_t event, char *key, void *old_value, void *value, void *user_data)"
.br
.ti -1c
.RI "typedef int32_t(* \fBqb_map_transverse_fn\fP )(const char *key, void *value, void *user_data)"
.br
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "\fBqb_map_t\fP * \fBqb_hashtable_create\fP (size_t max_size)"
.br
.RI "\fICreate an unsorted map based on a hashtable\&. \fP"
.ti -1c
.RI "\fBqb_map_t\fP * \fBqb_skiplist_create\fP (void)"
.br
.RI "\fICreate a sorted map using a skiplist\&. \fP"
.ti -1c
.RI "\fBqb_map_t\fP * \fBqb_trie_create\fP (void)"
.br
.RI "\fICreate a sorted map using a Patricia trie or 'Radix tree'\&. \fP"
.ti -1c
.RI "void \fBqb_trie_dump\fP (\fBqb_map_t\fP *m)"
.br
.RI "\fIprint out the nodes in the trie \fP"
.ti -1c
.RI "int32_t \fBqb_map_notify_add\fP (\fBqb_map_t\fP *m, const char *key, \fBqb_map_notify_fn\fP fn, int32_t events, void *user_data)"
.br
.RI "\fIAdd a notifier to the map\&. \fP"
.ti -1c
.RI "int32_t \fBqb_map_notify_del\fP (\fBqb_map_t\fP *m, const char *key, \fBqb_map_notify_fn\fP fn, int32_t events)"
.br
.RI "\fIDelete a notifier from the map\&. \fP"
.ti -1c
.RI "int32_t \fBqb_map_notify_del_2\fP (\fBqb_map_t\fP *m, const char *key, \fBqb_map_notify_fn\fP fn, int32_t events, void *user_data)"
.br
.RI "\fIDelete a notifier from the map (including the userdata)\&. \fP"
.ti -1c
.RI "void \fBqb_map_put\fP (\fBqb_map_t\fP *map, const char *key, const void *value)"
.br
.RI "\fIInserts a new key and value into a qb_map_t\&. \fP"
.ti -1c
.RI "void * \fBqb_map_get\fP (\fBqb_map_t\fP *map, const char *key)"
.br
.RI "\fIGets the value corresponding to the given key\&. \fP"
.ti -1c
.RI "int32_t \fBqb_map_rm\fP (\fBqb_map_t\fP *map, const char *key)"
.br
.RI "\fIRemoves a key/value pair from a map\&. \fP"
.ti -1c
.RI "size_t \fBqb_map_count_get\fP (\fBqb_map_t\fP *map)"
.br
.RI "\fIGet the number of items in the map\&. \fP"
.ti -1c
.RI "void \fBqb_map_foreach\fP (\fBqb_map_t\fP *map, \fBqb_map_transverse_fn\fP func, void *user_data)"
.br
.RI "\fICalls the given function for each of the key/value pairs in the map\&. \fP"
.ti -1c
.RI "\fBqb_map_iter_t\fP * \fBqb_map_iter_create\fP (\fBqb_map_t\fP *map)"
.br
.RI "\fICreate an iterator\&. \fP"
.ti -1c
.RI "\fBqb_map_iter_t\fP * \fBqb_map_pref_iter_create\fP (\fBqb_map_t\fP *map, const char *prefix)"
.br
.RI "\fICreate a prefix iterator\&. \fP"
.ti -1c
.RI "const char * \fBqb_map_iter_next\fP (\fBqb_map_iter_t\fP *i, void **value)"
.br
.RI "\fIGet the next item\&. \fP"
.ti -1c
.RI "void \fBqb_map_iter_free\fP (\fBqb_map_iter_t\fP *i)"
.br
.RI "\fIfree the iterator \fP"
.ti -1c
.RI "void \fBqb_map_destroy\fP (\fBqb_map_t\fP *map)"
.br
.RI "\fIDestroy the map, removes all the items from the map\&. \fP"
.in -1c
.SH "Detailed Description"
.PP
This provides a map interface to a Patricia trie, hashtable or skiplist\&.
.PP
\fBOrdering\fP
.RS 4
The hashtable is NOT ordered, but ptrie and skiplist are\&.
.RE
.PP
\fBIterating\fP
.RS 4
Below is a simple example of how to iterate over a map\&.
.PP
.nf
* 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);
*
.fi
.PP
.RE
.PP
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\&.
.PP
.nf
* qb_map_notify_add(m, NULL, my_map_free_handler,
* QB_MAP_NOTIFY_FREE, NULL);
*
.fi
.PP
.PP
\fBNotifications\fP
.RS 4
These allow you to get callbacks when values are inserted/removed or replaced\&.
.RE
.PP
\fBNote:\fP
.RS 4
hashtable only supports deletion and replacement notificatins\&. There is also a special global callback for freeing deleted and replaced values (QB_MAP_NOTIFY_FREE)\&.
.RE
.PP
\fBSee Also:\fP
.RS 4
\fBqb_map_notify_add()\fP \fBqb_map_notify_del_2()\fP
.RE
.PP
\fBPrefix matching\fP
.RS 4
The ptrie supports prefixes in the iterator:
.RE
.PP
.PP
.nf
* 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);
*
.fi
.PP
.PP
The ptrie also supports prefixes in notifications: (remember to pass QB_MAP_NOTIFY_RECURSIVE into the notify_add\&.
.PP
.nf
* 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);
*
*
.fi
.PP
.SH "Macro Definition Documentation"
.PP
.SS "#define QB_MAP_NOTIFY_DELETED 1"
.SS "#define QB_MAP_NOTIFY_FREE 16"
.SS "#define QB_MAP_NOTIFY_INSERTED 4"
.SS "#define QB_MAP_NOTIFY_RECURSIVE 8"
.SS "#define QB_MAP_NOTIFY_REPLACED 2"
.SH "Typedef Documentation"
.PP
.SS "typedef struct qb_map_iter \fBqb_map_iter_t\fP"
.PP
This is an opaque data type representing an iterator instance\&.
.SS "typedef void(* qb_map_notify_fn)(uint32_t event, char *key, void *old_value, void *value, void *user_data)"
.SS "typedef struct qb_map \fBqb_map_t\fP"
.PP
This is an opaque data type representing an instance of a map\&.
.SS "typedef int32_t(* qb_map_transverse_fn)(const char *key, void *value, void *user_data)"
.SH "Function Documentation"
.PP
.SS "\fBqb_map_t\fP* qb_hashtable_create (size_tmax_size)"
.PP
Create an unsorted map based on a hashtable\&.
.PP
\fBParameters:\fP
.RS 4
\fImax_size\fP maximum size of the hashtable
.RE
.PP
\fBReturns:\fP
.RS 4
the map instance
.RE
.PP
.SS "size_t qb_map_count_get (\fBqb_map_t\fP *map)"
.PP
Get the number of items in the map\&.
.SS "void qb_map_destroy (\fBqb_map_t\fP *map)"
.PP
Destroy the map, removes all the items from the map\&.
.SS "void qb_map_foreach (\fBqb_map_t\fP *map, \fBqb_map_transverse_fn\fPfunc, void *user_data)"
.PP
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\&.
.SS "void* qb_map_get (\fBqb_map_t\fP *map, const char *key)"
.PP
Gets the value corresponding to the given key\&.
.PP
\fBReturn values:\fP
.RS 4
\fINULL\fP (if the key does not exist)
.br
\fIa\fP pointer to the value
.RE
.PP
.SS "\fBqb_map_iter_t\fP* qb_map_iter_create (\fBqb_map_t\fP *map)"
.PP
Create an iterator\&.
.SS "void qb_map_iter_free (\fBqb_map_iter_t\fP *i)"
.PP
free the iterator
.PP
\fBParameters:\fP
.RS 4
\fIi\fP the iterator
.RE
.PP
.SS "const char* qb_map_iter_next (\fBqb_map_iter_t\fP *i, void **value)"
.PP
Get the next item\&.
.PP
\fBParameters:\fP
.RS 4
\fIi\fP the iterator
.br
\fIvalue\fP (out) the next item's value
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIthe\fP next key
.br
\fINULL\fP - the end of the iteration
.RE
.PP
.SS "int32_t qb_map_notify_add (\fBqb_map_t\fP *m, const char *key, \fBqb_map_notify_fn\fPfn, int32_tevents, void *user_data)"
.PP
Add a notifier to the map\&.
.PP
\fBParameters:\fP
.RS 4
\fIm\fP the map instance
.br
\fIkey\fP the key (or prefix) to attach the notification to\&.
.br
\fIfn\fP the callback
.br
\fIevents\fP the type of events to register for\&.
.br
\fIuser_data\fP a pointer to be passed into the callback
.RE
.PP
\fBNote:\fP
.RS 4
QB_MAP_NOTIFY_INSERTED is only valid on tries\&.
.PP
you can use key prefixes with trie maps\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP success
.br
\fI-errno\fP failure
.RE
.PP
.SS "int32_t qb_map_notify_del (\fBqb_map_t\fP *m, const char *key, \fBqb_map_notify_fn\fPfn, int32_tevents)"
.PP
Delete a notifier from the map\&.
.PP
\fBNote:\fP
.RS 4
the key,fn and events must match those you added\&.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIm\fP the map instance
.br
\fIkey\fP the key (or prefix) to attach the notification to\&.
.br
\fIfn\fP the callback
.br
\fIevents\fP the type of events to register for\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP success
.br
\fI-errno\fP failure
.RE
.PP
.SS "int32_t qb_map_notify_del_2 (\fBqb_map_t\fP *m, const char *key, \fBqb_map_notify_fn\fPfn, int32_tevents, void *user_data)"
.PP
Delete a notifier from the map (including the userdata)\&.
.PP
\fBNote:\fP
.RS 4
the key, fn, events and userdata must match those you added\&.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIm\fP the map instance
.br
\fIkey\fP the key (or prefix) to attach the notification to\&.
.br
\fIfn\fP the callback
.br
\fIevents\fP the type of events to register for\&.
.br
\fIuser_data\fP a pointer to be passed into the callback
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP success
.br
\fI-errno\fP failure
.RE
.PP
.SS "\fBqb_map_iter_t\fP* qb_map_pref_iter_create (\fBqb_map_t\fP *map, const char *prefix)"
.PP
Create a prefix iterator\&. This will iterate over all items with the given prefix\&.
.PP
\fBNote:\fP
.RS 4
this is only supported by the trie\&.
.RE
.PP
.SS "void qb_map_put (\fBqb_map_t\fP *map, const char *key, const void *value)"
.PP
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\&.
.SS "int32_t qb_map_rm (\fBqb_map_t\fP *map, const char *key)"
.PP
Removes a key/value pair from a map\&.
.SS "\fBqb_map_t\fP* qb_skiplist_create (void)"
.PP
Create a sorted map using a skiplist\&.
.PP
\fBReturns:\fP
.RS 4
the map instance
.RE
.PP
.SS "\fBqb_map_t\fP* qb_trie_create (void)"
.PP
Create a sorted map using a Patricia trie or 'Radix tree'\&.
.SS "void qb_trie_dump (\fBqb_map_t\fP *m)"
.PP
print out the nodes in the trie (for debug purposes)
.SH "Author"
.PP
Generated automatically by Doxygen for libqb from the source code\&.