]>
jfr.im git - solanum.git/blob - include/irc_dictionary.h
2 * charybdis: an advanced ircd.
3 * irc_dictionary.h: Dictionary-based storage.
5 * Copyright (c) 2007 William Pitcock <nenolod -at- sacredspiral.co.uk>
6 * Copyright (c) 2007 Jilles Tjoelker <jilles -at- stack.nl>
8 * Permission to use, copy, modify, and/or distribute this software for any
9 * purpose with or without fee is hereby granted, provided that the above
10 * copyright notice and this permission notice is present in all copies.
12 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
13 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
14 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
15 * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
16 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
17 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
18 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
20 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
21 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
22 * POSSIBILITY OF SUCH DAMAGE.
25 #ifndef __IRC_DICTIONARY_H__
26 #define __IRC_DICTIONARY_H__
28 struct Dictionary
; /* defined in src/dictionary.c */
30 typedef int (*DCF
)(const char *a
, const char *b
);
32 struct DictionaryElement
34 struct DictionaryElement
*left
, *right
, *prev
, *next
;
42 struct DictionaryElement
*cur
, *next
;
46 * this is a convenience macro for inlining iteration of dictionaries.
48 #define DICTIONARY_FOREACH(element, state, dict) for (irc_dictionary_foreach_start((dict), (state)); (element = irc_dictionary_foreach_cur((dict), (state))); irc_dictionary_foreach_next((dict), (state)))
51 * irc_dictionary_create() creates a new dictionary tree.
52 * compare_cb is the comparison function, typically strcmp, strcasecmp or
55 extern struct Dictionary
*irc_dictionary_create(DCF compare_cb
);
58 * irc_dictionary_create_named() creates a new dictionary tree which has a name.
59 * name is the name, compare_cb is the comparator.
61 extern struct Dictionary
*irc_dictionary_create_named(const char *name
, DCF compare_cb
);
64 * irc_dictionary_set_comparator_func() resets the comparator used for lookups and
65 * insertions in the DTree structure.
67 extern void irc_dictionary_set_comparator_func(struct Dictionary
*dict
,
71 * irc_dictionary_get_comparator_func() returns the comparator used for lookups and
72 * insertions in the DTree structure.
74 extern DCF
irc_dictionary_get_comparator_func(struct Dictionary
*dict
);
77 * irc_dictionary_get_linear_index() returns the linear index of an object in the
80 extern int irc_dictionary_get_linear_index(struct Dictionary
*dict
, const char *key
);
83 * irc_dictionary_destroy() destroys all entries in a dtree, and also optionally calls
84 * a defined callback function to destroy any data attached to it.
86 extern void irc_dictionary_destroy(struct Dictionary
*dtree
,
87 void (*destroy_cb
)(struct DictionaryElement
*delem
, void *privdata
),
91 * irc_dictionary_foreach() iterates all entries in a dtree, and also optionally calls
92 * a defined callback function to use any data attached to it.
94 * To shortcircuit iteration, return non-zero from the callback function.
96 extern void irc_dictionary_foreach(struct Dictionary
*dtree
,
97 int (*foreach_cb
)(struct DictionaryElement
*delem
, void *privdata
),
101 * irc_dictionary_search() iterates all entries in a dtree, and also optionally calls
102 * a defined callback function to use any data attached to it.
104 * When the object is found, a non-NULL is returned from the callback, which results
105 * in that object being returned to the user.
107 extern void *irc_dictionary_search(struct Dictionary
*dtree
,
108 void *(*foreach_cb
)(struct DictionaryElement
*delem
, void *privdata
),
112 * irc_dictionary_foreach_start() begins an iteration over all items
113 * keeping state in the given struct. If there is only one iteration
114 * in progress at a time, it is permitted to remove the current element
115 * of the iteration (but not any other element).
117 extern void irc_dictionary_foreach_start(struct Dictionary
*dtree
,
118 struct DictionaryIter
*state
);
121 * irc_dictionary_foreach_cur() returns the current element of the iteration,
122 * or NULL if there are no more elements.
124 extern void *irc_dictionary_foreach_cur(struct Dictionary
*dtree
,
125 struct DictionaryIter
*state
);
128 * irc_dictionary_foreach_next() moves to the next element.
130 extern void irc_dictionary_foreach_next(struct Dictionary
*dtree
,
131 struct DictionaryIter
*state
);
134 * irc_dictionary_add() adds a key->value entry to the dictionary tree.
136 extern struct DictionaryElement
*irc_dictionary_add(struct Dictionary
*dtree
, const char *key
, void *data
);
139 * irc_dictionary_find() returns a struct DictionaryElement container from a dtree for key 'key'.
141 extern struct DictionaryElement
*irc_dictionary_find(struct Dictionary
*dtree
, const char *key
);
144 * irc_dictionary_find() returns data from a dtree for key 'key'.
146 extern void *irc_dictionary_retrieve(struct Dictionary
*dtree
, const char *key
);
149 * irc_dictionary_delete() deletes a key->value entry from the dictionary tree.
151 extern void *irc_dictionary_delete(struct Dictionary
*dtree
, const char *key
);
154 * irc_dictionary_size() returns the number of elements in a dictionary tree.
156 extern unsigned int irc_dictionary_size(struct Dictionary
*dtree
);
158 void irc_dictionary_stats(struct Dictionary
*dict
, void (*cb
)(const char *line
, void *privdata
), void *privdata
);