1 @node Container data types
2 @section Container data types
4 @c Copyright (C) 2019--2020 Free Software Foundation, Inc.
6 @c Permission is granted to copy, distribute and/or modify this document
7 @c under the terms of the GNU Free Documentation License, Version 1.3 or
8 @c any later version published by the Free Software Foundation; with no
9 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
10 @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
12 @c Written by Bruno Haible.
14 @c This macro expands to \log in TeX mode, but just 'log' in HTML and info
22 @c This macro expands to \mathopsup in TeX mode, to a superscript in HTML
23 @c mode, and to ^ without braces in info mode.
25 @macro mathopsup {EXP}
30 @macro mathopsup {EXP}
35 Gnulib provides several generic container data types. They can be used
36 to organize collections of application-defined objects.
38 @multitable @columnfractions .15 .5 .1 .1 .15
42 @tab Main include file
43 @tab Include file for operations with out-of-memory checking
45 @tab Can contain any number of objects in any given order.
46 Duplicates are allowed, but can optionally be forbidden.
48 @tab @code{"gl_list.h"}
49 @tab @code{"gl_xlist.h"}
51 @tab Can contain any number of objects; the order does not matter.
52 Duplicates (in the sense of the comparator) are forbidden.
54 @tab @code{"gl_set.h"}
55 @tab @code{"gl_xset.h"}
57 @tab Can contain any number of objects in the order of a given comparator
59 Duplicates (in the sense of the comparator) are forbidden.
61 @tab @code{"gl_oset.h"}
62 @tab @code{"gl_xoset.h"}
64 @tab Can contain any number of (key, value) pairs, where keys and values
66 there are no (key, value1) and (key, value2) pairs with the same key
67 (in the sense of a given comparator function).
69 @tab @code{"gl_map.h"}
70 @tab @code{"gl_xmap.h"}
72 @tab Can contain any number of (key, value) pairs, where keys and values
74 the (key, value) pairs are ordered by the key, in the order of a given
76 there are no (key, value1) and (key, value2) pairs with the same key
77 (in the sense of the comparator function).
79 @tab @code{"gl_omap.h"}
80 @tab @code{"gl_xomap.h"}
83 Operations without out-of-memory checking (suitable for use in libraries) are
84 declared in the ``main include file''. Whereas operations with out-of-memory
85 checking (suitable only in programs) are declared in the ``include file for
86 operations with out-of-memory checking''.
88 For each of the data types, several implementations are available, with
89 different performance profiles with respect to the available operations.
90 This enables you to start with the simplest implementation (ARRAY) initially,
91 and switch to a more suitable implementation after profiling your application.
92 The implementation of each container instance is specified in a single place
93 only: in the invocation of the function @code{gl_*_create_empty} that creates
96 The implementations and the guaranteed average performance for the operations
97 for the ``sequential list'' data type are:
99 @multitable @columnfractions 0.2 0.1 0.1 0.1 0.1 0.1 0.1 0.1 0.1
105 @tab LINKEDHASH with duplicates
106 @tab LINKEDHASH without duplicates
107 @tab TREEHASH with duplicates
108 @tab TREEHASH without duplicates
109 @item @code{gl_list_size}
118 @item @code{gl_list_node_value}
127 @item @code{gl_list_node_set_value}
134 @tab @math{O((@log n)@mathopsup{2})}
136 @item @code{gl_list_next_node}
140 @tab @math{O(@log n)}
143 @tab @math{O(@log n)}
144 @tab @math{O(@log n)}
145 @item @code{gl_list_previous_node}
149 @tab @math{O(@log n)}
152 @tab @math{O(@log n)}
153 @tab @math{O(@log n)}
154 @item @code{gl_list_get_at}
158 @tab @math{O(@log n)}
161 @tab @math{O(@log n)}
162 @tab @math{O(@log n)}
163 @item @code{gl_list_get_first}
167 @tab @math{O(@log n)}
170 @tab @math{O(@log n)}
171 @tab @math{O(@log n)}
172 @item @code{gl_list_get_last}
176 @tab @math{O(@log n)}
179 @tab @math{O(@log n)}
180 @tab @math{O(@log n)}
181 @item @code{gl_list_set_at}
185 @tab @math{O(@log n)}
188 @tab @math{O((@log n)@mathopsup{2})}
189 @tab @math{O(@log n)}
190 @item @code{gl_list_set_first}
194 @tab @math{O(@log n)}
197 @tab @math{O((@log n)@mathopsup{2})}
198 @tab @math{O(@log n)}
199 @item @code{gl_list_set_last}
203 @tab @math{O(@log n)}
206 @tab @math{O((@log n)@mathopsup{2})}
207 @tab @math{O(@log n)}
208 @item @code{gl_list_search}
215 @tab @math{O(@log n)}
217 @item @code{gl_list_search_from}
224 @tab @math{O((@log n)@mathopsup{2})}
225 @tab @math{O(@log n)}
226 @item @code{gl_list_search_from_to}
233 @tab @math{O((@log n)@mathopsup{2})}
234 @tab @math{O(@log n)}
235 @item @code{gl_list_indexof}
242 @tab @math{O(@log n)}
243 @tab @math{O(@log n)}
244 @item @code{gl_list_indexof_from}
251 @tab @math{O((@log n)@mathopsup{2})}
252 @tab @math{O(@log n)}
253 @item @code{gl_list_indexof_from_to}
260 @tab @math{O((@log n)@mathopsup{2})}
261 @tab @math{O(@log n)}
262 @item @code{gl_list_add_first}
266 @tab @math{O(@log n)}
269 @tab @math{O((@log n)@mathopsup{2})}
270 @tab @math{O(@log n)}
271 @item @code{gl_list_add_last}
275 @tab @math{O(@log n)}
278 @tab @math{O((@log n)@mathopsup{2})}
279 @tab @math{O(@log n)}
280 @item @code{gl_list_add_before}
284 @tab @math{O(@log n)}
287 @tab @math{O((@log n)@mathopsup{2})}
288 @tab @math{O(@log n)}
289 @item @code{gl_list_add_after}
293 @tab @math{O(@log n)}
296 @tab @math{O((@log n)@mathopsup{2})}
297 @tab @math{O(@log n)}
298 @item @code{gl_list_add_at}
302 @tab @math{O(@log n)}
305 @tab @math{O((@log n)@mathopsup{2})}
306 @tab @math{O(@log n)}
307 @item @code{gl_list_remove_node}
311 @tab @math{O(@log n)}
314 @tab @math{O((@log n)@mathopsup{2})}
315 @tab @math{O(@log n)}
316 @item @code{gl_list_remove_at}
320 @tab @math{O(@log n)}
323 @tab @math{O((@log n)@mathopsup{2})}
324 @tab @math{O(@log n)}
325 @item @code{gl_list_remove_first}
329 @tab @math{O(@log n)}
332 @tab @math{O((@log n)@mathopsup{2})}
333 @tab @math{O(@log n)}
334 @item @code{gl_list_remove_last}
338 @tab @math{O(@log n)}
341 @tab @math{O((@log n)@mathopsup{2})}
342 @tab @math{O(@log n)}
343 @item @code{gl_list_remove}
350 @tab @math{O((@log n)@mathopsup{2})}
351 @tab @math{O(@log n)}
352 @item @code{gl_list_iterator}
356 @tab @math{O(@log n)}
359 @tab @math{O(@log n)}
360 @tab @math{O(@log n)}
361 @item @code{gl_list_iterator_from_to}
365 @tab @math{O(@log n)}
368 @tab @math{O(@log n)}
369 @tab @math{O(@log n)}
370 @item @code{gl_list_iterator_next}
374 @tab @math{O(@log n)}
377 @tab @math{O(@log n)}
378 @tab @math{O(@log n)}
379 @item @code{gl_sortedlist_search}
380 @tab @math{O(@log n)}
381 @tab @math{O(@log n)}
383 @tab @math{O(@log n)}
386 @tab @math{O(@log n)}
387 @tab @math{O(@log n)}
388 @item @code{gl_sortedlist_search_from}
389 @tab @math{O(@log n)}
390 @tab @math{O(@log n)}
392 @tab @math{O(@log n)}
395 @tab @math{O(@log n)}
396 @tab @math{O(@log n)}
397 @item @code{gl_sortedlist_indexof}
398 @tab @math{O(@log n)}
399 @tab @math{O(@log n)}
401 @tab @math{O(@log n)}
404 @tab @math{O(@log n)}
405 @tab @math{O(@log n)}
406 @item @code{gl_sortedlist_indexof_from}
407 @tab @math{O(@log n)}
408 @tab @math{O(@log n)}
410 @tab @math{O(@log n)}
413 @tab @math{O(@log n)}
414 @tab @math{O(@log n)}
415 @item @code{gl_sortedlist_add}
419 @tab @math{O(@log n)}
422 @tab @math{O((@log n)@mathopsup{2})}
423 @tab @math{O(@log n)}
424 @item @code{gl_sortedlist_remove}
428 @tab @math{O(@log n)}
431 @tab @math{O((@log n)@mathopsup{2})}
432 @tab @math{O(@log n)}
435 The implementations and the guaranteed average performance for the operations
436 for the ``set'' data type are:
438 @multitable @columnfractions 0.4 0.2 0.4
441 @tab LINKEDHASH, HASH
442 @item @code{gl_set_size}
445 @item @code{gl_set_add}
448 @item @code{gl_set_remove}
451 @item @code{gl_set_search}
454 @item @code{gl_set_iterator}
457 @item @code{gl_set_iterator_next}
462 The implementations and the guaranteed average performance for the operations
463 for the ``ordered set'' data type are:
465 @multitable @columnfractions 0.5 0.25 0.25
469 @item @code{gl_oset_size}
472 @item @code{gl_oset_add}
474 @tab @math{O(@log n)}
475 @item @code{gl_oset_remove}
477 @tab @math{O(@log n)}
478 @item @code{gl_oset_search}
479 @tab @math{O(@log n)}
480 @tab @math{O(@log n)}
481 @item @code{gl_oset_search_atleast}
482 @tab @math{O(@log n)}
483 @tab @math{O(@log n)}
484 @item @code{gl_oset_iterator}
486 @tab @math{O(@log n)}
487 @item @code{gl_oset_iterator_next}
489 @tab @math{O(@log n)}
492 The implementations and the guaranteed average performance for the operations
493 for the ``map'' data type are:
495 @multitable @columnfractions 0.4 0.2 0.4
498 @tab LINKEDHASH, HASH
499 @item @code{gl_map_size}
502 @item @code{gl_map_get}
505 @item @code{gl_map_put}
508 @item @code{gl_map_remove}
511 @item @code{gl_map_search}
514 @item @code{gl_map_iterator}
517 @item @code{gl_map_iterator_next}
522 The implementations and the guaranteed average performance for the operations
523 for the ``ordered map'' data type are:
525 @multitable @columnfractions 0.5 0.25 0.25
529 @item @code{gl_omap_size}
532 @item @code{gl_omap_get}
533 @tab @math{O(@log n)}
534 @tab @math{O(@log n)}
535 @item @code{gl_omap_put}
537 @tab @math{O(@log n)}
538 @item @code{gl_omap_remove}
540 @tab @math{O(@log n)}
541 @item @code{gl_omap_search}
542 @tab @math{O(@log n)}
543 @tab @math{O(@log n)}
544 @item @code{gl_omap_search_atleast}
545 @tab @math{O(@log n)}
546 @tab @math{O(@log n)}
547 @item @code{gl_omap_iterator}
549 @tab @math{O(@log n)}
550 @item @code{gl_omap_iterator_next}
552 @tab @math{O(@log n)}
555 For C++, Gnulib provides a C++ template class for each of these container data types.
557 @multitable @columnfractions .30 .20 .25 .25
562 @item Sequential list
565 @tab @code{"gl_list.hh"}
569 @tab @code{"gl_set.hh"}
573 @tab @code{"gl_oset.hh"}
577 @tab @code{"gl_map.hh"}
581 @tab @code{"gl_omap.hh"}