]>
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 void *a, const void *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_named() creates a new dictionary tree which has a name.
52 * name is the name, compare_cb is the comparator.
54 extern struct Dictionary
*irc_dictionary_create(const char *name
, DCF compare_cb
);
57 * irc_dictionary_set_comparator_func() resets the comparator used for lookups and
58 * insertions in the DTree structure.
60 extern void irc_dictionary_set_comparator_func(struct Dictionary
*dict
,
64 * irc_dictionary_get_comparator_func() returns the comparator used for lookups and
65 * insertions in the DTree structure.
67 extern DCF
irc_dictionary_get_comparator_func(struct Dictionary
*dict
);
70 * irc_dictionary_get_linear_index() returns the linear index of an object in the
73 extern int irc_dictionary_get_linear_index(struct Dictionary
*dict
, const void *key
);
76 * irc_dictionary_destroy() destroys all entries in a dtree, and also optionally calls
77 * a defined callback function to destroy any data attached to it.
79 extern void irc_dictionary_destroy(struct Dictionary
*dtree
,
80 void (*destroy_cb
)(struct DictionaryElement
*delem
, void *privdata
),
84 * irc_dictionary_foreach() iterates all entries in a dtree, and also optionally calls
85 * a defined callback function to use any data attached to it.
87 * To shortcircuit iteration, return non-zero from the callback function.
89 extern void irc_dictionary_foreach(struct Dictionary
*dtree
,
90 int (*foreach_cb
)(struct DictionaryElement
*delem
, void *privdata
),
94 * irc_dictionary_search() iterates all entries in a dtree, and also optionally calls
95 * a defined callback function to use any data attached to it.
97 * When the object is found, a non-NULL is returned from the callback, which results
98 * in that object being returned to the user.
100 extern void *irc_dictionary_search(struct Dictionary
*dtree
,
101 void *(*foreach_cb
)(struct DictionaryElement
*delem
, void *privdata
),
105 * irc_dictionary_foreach_start() begins an iteration over all items
106 * keeping state in the given struct. If there is only one iteration
107 * in progress at a time, it is permitted to remove the current element
108 * of the iteration (but not any other element).
110 extern void irc_dictionary_foreach_start(struct Dictionary
*dtree
,
111 struct DictionaryIter
*state
);
114 * irc_dictionary_foreach_cur() returns the current element of the iteration,
115 * or NULL if there are no more elements.
117 extern void *irc_dictionary_foreach_cur(struct Dictionary
*dtree
,
118 struct DictionaryIter
*state
);
121 * irc_dictionary_foreach_next() moves to the next element.
123 extern void irc_dictionary_foreach_next(struct Dictionary
*dtree
,
124 struct DictionaryIter
*state
);
127 * irc_dictionary_add() adds a key->value entry to the dictionary tree.
129 extern struct DictionaryElement
*irc_dictionary_add(struct Dictionary
*dtree
, const void *key
, void *data
);
132 * irc_dictionary_find() returns a struct DictionaryElement container from a dtree for key 'key'.
134 extern struct DictionaryElement
*irc_dictionary_find(struct Dictionary
*dtree
, const void *key
);
137 * irc_dictionary_find() returns data from a dtree for key 'key'.
139 extern void *irc_dictionary_retrieve(struct Dictionary
*dtree
, const void *key
);
142 * irc_dictionary_delete() deletes a key->value entry from the dictionary tree.
144 extern void *irc_dictionary_delete(struct Dictionary
*dtree
, const void *key
);
147 * irc_dictionary_size() returns the number of elements in a dictionary tree.
149 extern unsigned int irc_dictionary_size(struct Dictionary
*dtree
);
151 void irc_dictionary_stats(struct Dictionary
*dict
, void (*cb
)(const char *line
, void *privdata
), void *privdata
);
152 void irc_dictionary_stats_walk(void (*cb
)(const char *line
, void *privdata
), void *privdata
);
154 #define IRC_POINTER_TO_INT(x) ((int32_t) (long) (x))
155 #define IRC_INT_TO_POINTER(x) ((void *) (long) (int32_t) (x))
157 #define IRC_POINTER_TO_UINT(x) ((uint32_t) (unsigned long) (x))
158 #define IRC_UINT_TO_POINTER(x) ((void *) (unsigned long) (uint32_t) (x))
160 static inline int irc_int32cmp(const void *a
, const void *b
)
162 return IRC_POINTER_TO_INT(b
) - IRC_POINTER_TO_INT(a
);
165 static inline int irc_uint32cmp(const void *a
, const void *b
)
167 return IRC_POINTER_TO_UINT(b
) - IRC_POINTER_TO_UINT(a
);