]>
jfr.im git - solanum.git/blob - librb/include/rb_dictionary.h
2 * charybdis: an advanced ircd.
3 * rb_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 __RB_DICTIONARY_H__
26 #define __RB_DICTIONARY_H__
28 #include "librb-config.h"
30 struct Dictionary
; /* defined in src/dictionary.c */
32 typedef int (*DCF
)(/* const void *a, const void *b */);
34 struct DictionaryElement
36 struct DictionaryElement
*left
, *right
, *prev
, *next
;
44 struct DictionaryElement
*cur
, *next
;
48 * this is a convenience macro for inlining iteration of dictionaries.
50 #define DICTIONARY_FOREACH(element, state, dict) for (rb_dictionary_foreach_start((dict), (state)); (element = rb_dictionary_foreach_cur((dict), (state))); rb_dictionary_foreach_next((dict), (state)))
53 * rb_dictionary_create_named() creates a new dictionary tree which has a name.
54 * name is the name, compare_cb is the comparator.
56 extern struct Dictionary
*rb_dictionary_create(const char *name
, DCF compare_cb
);
59 * rb_dictionary_set_comparator_func() resets the comparator used for lookups and
60 * insertions in the DTree structure.
62 extern void rb_dictionary_set_comparator_func(struct Dictionary
*dict
,
66 * rb_dictionary_get_comparator_func() returns the comparator used for lookups and
67 * insertions in the DTree structure.
69 extern DCF
rb_dictionary_get_comparator_func(struct Dictionary
*dict
);
72 * rb_dictionary_get_linear_index() returns the linear index of an object in the
75 extern int rb_dictionary_get_linear_index(struct Dictionary
*dict
, const void *key
);
78 * rb_dictionary_destroy() destroys all entries in a dtree, and also optionally calls
79 * a defined callback function to destroy any data attached to it.
81 extern void rb_dictionary_destroy(struct Dictionary
*dtree
,
82 void (*destroy_cb
)(struct DictionaryElement
*delem
, void *privdata
),
86 * rb_dictionary_foreach() iterates all entries in a dtree, and also optionally calls
87 * a defined callback function to use any data attached to it.
89 * To shortcircuit iteration, return non-zero from the callback function.
91 extern void rb_dictionary_foreach(struct Dictionary
*dtree
,
92 int (*foreach_cb
)(struct DictionaryElement
*delem
, void *privdata
),
96 * rb_dictionary_search() iterates all entries in a dtree, and also optionally calls
97 * a defined callback function to use any data attached to it.
99 * When the object is found, a non-NULL is returned from the callback, which results
100 * in that object being returned to the user.
102 extern void *rb_dictionary_search(struct Dictionary
*dtree
,
103 void *(*foreach_cb
)(struct DictionaryElement
*delem
, void *privdata
),
107 * rb_dictionary_foreach_start() begins an iteration over all items
108 * keeping state in the given struct. If there is only one iteration
109 * in progress at a time, it is permitted to remove the current element
110 * of the iteration (but not any other element).
112 extern void rb_dictionary_foreach_start(struct Dictionary
*dtree
,
113 struct DictionaryIter
*state
);
116 * rb_dictionary_foreach_cur() returns the current element of the iteration,
117 * or NULL if there are no more elements.
119 extern void *rb_dictionary_foreach_cur(struct Dictionary
*dtree
,
120 struct DictionaryIter
*state
);
123 * rb_dictionary_foreach_next() moves to the next element.
125 extern void rb_dictionary_foreach_next(struct Dictionary
*dtree
,
126 struct DictionaryIter
*state
);
129 * rb_dictionary_add() adds a key->value entry to the dictionary tree.
131 extern struct DictionaryElement
*rb_dictionary_add(struct Dictionary
*dtree
, const void *key
, void *data
);
134 * rb_dictionary_find() returns a struct DictionaryElement container from a dtree for key 'key'.
136 extern struct DictionaryElement
*rb_dictionary_find(struct Dictionary
*dtree
, const void *key
);
139 * rb_dictionary_find() returns data from a dtree for key 'key'.
141 extern void *rb_dictionary_retrieve(struct Dictionary
*dtree
, const void *key
);
144 * rb_dictionary_delete() deletes a key->value entry from the dictionary tree.
146 extern void *rb_dictionary_delete(struct Dictionary
*dtree
, const void *key
);
149 * rb_dictionary_size() returns the number of elements in a dictionary tree.
151 extern unsigned int rb_dictionary_size(struct Dictionary
*dtree
);
153 void rb_dictionary_stats(struct Dictionary
*dict
, void (*cb
)(const char *line
, void *privdata
), void *privdata
);
154 void rb_dictionary_stats_walk(void (*cb
)(const char *line
, void *privdata
), void *privdata
);
158 #define RB_POINTER_TO_INT(x) ((int32_t) (long) (x))
159 #define RB_INT_TO_POINTER(x) ((void *) (long) (int32_t) (x))
161 #define RB_POINTER_TO_UINT(x) ((uint32_t) (unsigned long) (x))
162 #define RB_UINT_TO_POINTER(x) ((void *) (unsigned long) (uint32_t) (x))
166 #define RB_POINTER_TO_INT(x) ((int32_t) (unsigned long long) (x))
167 #define RB_INT_TO_POINTER(x) ((void *) (unsigned long long) (int32_t) (x))
169 #define RB_POINTER_TO_UINT(x) ((uint32_t) (unsigned long long) (x))
170 #define RB_UINT_TO_POINTER(x) ((void *) (unsigned long long) (uint32_t) (x))
174 static inline int rb_int32cmp(const void *a
, const void *b
)
176 return RB_POINTER_TO_INT(b
) - RB_POINTER_TO_INT(a
);
179 static inline int rb_uint32cmp(const void *a
, const void *b
)
181 return RB_POINTER_TO_UINT(b
) - RB_POINTER_TO_UINT(a
);