1 /* Abstract ordered set data type.
2 Copyright (C) 2006 Free Software Foundation, Inc.
3 Written by Bruno Haible <bruno@clisp.org>, 2006.
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation; either version 2, or (at your option)
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with this program; if not, write to the Free Software Foundation,
17 Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */
30 /* gl_oset is an abstract ordered set data type. It can contain any number
31 of objects ('void *' or 'const void *' pointers) in the order of a given
32 comparator function. Duplicates (in the sense of the comparator) are
35 There are several implementations of this ordered set datatype, optimized
36 for different operations or for memory. You can start using the simplest
37 ordered set implementation, GL_ARRAY_OSET, and switch to a different
38 implementation later, when you realize which operations are performed
39 the most frequently. The API of the different implementations is exactly
40 the same; when switching to a different implementation, you only have to
41 change the gl_oset_create call.
43 The implementations are:
44 GL_ARRAY_OSET a growable array
45 GL_AVLTREE_OSET a binary tree (AVL tree)
46 GL_RBTREE_OSET a binary tree (red-black tree)
48 The memory consumption is asymptotically the same: O(1) for every object
49 in the set. When looking more closely at the average memory consumed
50 for an object, GL_ARRAY_OSET is the most compact representation, and
51 GL_AVLTREE_OSET, GL_RBTREE_OSET need more memory.
53 The guaranteed average performance of the operations is, for a set of
58 gl_oset_size O(1) O(1)
59 gl_oset_add O(n) O(log n)
60 gl_oset_remove O(n) O(log n)
61 gl_oset_search O(log n) O(log n)
62 gl_oset_iterator O(1) O(log n)
63 gl_oset_iterator_next O(1) O(log n)
66 /* -------------------------- gl_oset_t Data Type -------------------------- */
68 /* Type of function used to compare two elements. Same as for qsort().
69 NULL denotes pointer comparison. */
70 typedef int (*gl_setelement_compar_fn) (const void *elt1, const void *elt2);
73 /* Type representing an entire ordered set. */
74 typedef struct gl_oset_impl * gl_oset_t;
76 struct gl_oset_implementation;
77 /* Type representing a ordered set datatype implementation. */
78 typedef const struct gl_oset_implementation * gl_oset_implementation_t;
80 /* Create an empty set.
81 IMPLEMENTATION is one of GL_ARRAY_OSET, GL_AVLTREE_OSET, GL_RBTREE_OSET.
82 COMPAR_FN is an element comparison function or NULL. */
83 extern gl_oset_t gl_oset_create_empty (gl_oset_implementation_t implementation,
84 gl_setelement_compar_fn compar_fn);
86 /* Return the current number of elements in an ordered set. */
87 extern size_t gl_oset_size (gl_oset_t set);
89 /* Search whether an element is already in the ordered set.
90 Return true if found, or false if not present in the set. */
91 extern bool gl_oset_search (gl_oset_t set, const void *elt);
93 /* Add an element to an ordered set.
94 Return true if it was not already in the set and added. */
95 extern bool gl_oset_add (gl_oset_t set, const void *elt);
97 /* Remove an element from an ordered set.
98 Return true if it was found and removed. */
99 extern bool gl_oset_remove (gl_oset_t set, const void *elt);
101 /* Free an entire ordered set.
102 (But this call does not free the elements of the set.) */
103 extern void gl_oset_free (gl_oset_t set);
105 /* --------------------- gl_oset_iterator_t Data Type --------------------- */
107 /* Functions for iterating through an ordered set. */
109 /* Type of an iterator that traverses an ordered set.
110 This is a fixed-size struct, so that creation of an iterator doesn't need
111 memory allocation on the heap. */
114 /* For fast dispatch of gl_oset_iterator_next. */
115 const struct gl_oset_implementation *vtable;
116 /* For detecting whether the last returned element was removed. */
119 /* Other, implementation-private fields. */
122 } gl_oset_iterator_t;
124 /* Create an iterator traversing an ordered set.
125 The set's contents must not be modified while the iterator is in use,
126 except for removing the last returned element. */
127 extern gl_oset_iterator_t gl_oset_iterator (gl_oset_t set);
129 /* If there is a next element, store the next element in *ELTP, advance the
130 iterator and return true. Otherwise, return false. */
131 extern bool gl_oset_iterator_next (gl_oset_iterator_t *iterator,
134 /* Free an iterator. */
135 extern void gl_oset_iterator_free (gl_oset_iterator_t *iterator);
137 /* ------------------------ Implementation Details ------------------------ */
139 struct gl_oset_implementation
141 // gl_oset_t functions.
142 gl_oset_t (*create_empty) (gl_oset_implementation_t implementation,
143 gl_setelement_compar_fn compar_fn);
144 size_t (*size) (gl_oset_t set);
145 bool (*search) (gl_oset_t set, const void *elt);
146 bool (*add) (gl_oset_t set, const void *elt);
147 bool (*remove) (gl_oset_t set, const void *elt);
148 void (*oset_free) (gl_oset_t set);
149 // gl_oset_iterator_t functions.
150 gl_oset_iterator_t (*iterator) (gl_oset_t set);
151 bool (*iterator_next) (gl_oset_iterator_t *iterator, const void **eltp);
152 void (*iterator_free) (gl_oset_iterator_t *iterator);
155 struct gl_oset_impl_base
157 const struct gl_oset_implementation *vtable;
158 gl_setelement_compar_fn compar_fn;
163 /* Define all functions of this file as inline accesses to the
164 struct gl_oset_implementation.
165 Use #define to avoid a warning because of extern vs. static. */
167 # define gl_oset_create_empty gl_oset_create_empty_inline
168 static inline gl_oset_t
169 gl_oset_create_empty (gl_oset_implementation_t implementation,
170 gl_setelement_compar_fn compar_fn)
172 return implementation->create_empty (implementation, compar_fn);
175 # define gl_oset_size gl_oset_size_inline
177 gl_oset_size (gl_oset_t set)
179 return ((const struct gl_oset_impl_base *) set)->vtable->size (set);
182 # define gl_oset_search gl_oset_search_inline
184 gl_oset_search (gl_oset_t set, const void *elt)
186 return ((const struct gl_oset_impl_base *) set)->vtable->search (set, elt);
189 # define gl_oset_add gl_oset_add_inline
191 gl_oset_add (gl_oset_t set, const void *elt)
193 return ((const struct gl_oset_impl_base *) set)->vtable->add (set, elt);
196 # define gl_oset_remove gl_oset_remove_inline
198 gl_oset_remove (gl_oset_t set, const void *elt)
200 return ((const struct gl_oset_impl_base *) set)->vtable->remove (set, elt);
203 # define gl_oset_free gl_oset_free_inline
205 gl_oset_free (gl_oset_t set)
207 ((const struct gl_oset_impl_base *) set)->vtable->oset_free (set);
210 # define gl_oset_iterator gl_oset_iterator_inline
211 static inline gl_oset_iterator_t
212 gl_oset_iterator (gl_oset_t set)
214 return ((const struct gl_oset_impl_base *) set)->vtable->iterator (set);
217 # define gl_oset_iterator_next gl_oset_iterator_next_inline
219 gl_oset_iterator_next (gl_oset_iterator_t *iterator, const void **eltp)
221 return iterator->vtable->iterator_next (iterator, eltp);
224 # define gl_oset_iterator_free gl_oset_iterator_free_inline
226 gl_oset_iterator_free (gl_oset_iterator_t *iterator)
228 iterator->vtable->iterator_free (iterator);
237 #endif /* _GL_OSET_H */