src/cx/collection.h

Fri, 23 May 2025 12:44:24 +0200

author
Mike Becker <universe@uap-core.de>
date
Fri, 23 May 2025 12:44:24 +0200
changeset 1327
ed75dc1db503
parent 1171
155bc3b0dcb3
permissions
-rw-r--r--

make test-compile depend on both static and shared

the shared lib is not needed for the tests,
but when run with coverage, gcov will be confused
when outdated line information is available from
a previous shared build

677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1 /*
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
3 *
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
4 * Copyright 2023 Mike Becker, Olaf Wintermann All rights reserved.
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
5 *
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
6 * Redistribution and use in source and binary forms, with or without
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
7 * modification, are permitted provided that the following conditions are met:
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
8 *
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
9 * 1. Redistributions of source code must retain the above copyright
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
10 * notice, this list of conditions and the following disclaimer.
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
11 *
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
12 * 2. Redistributions in binary form must reproduce the above copyright
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
13 * notice, this list of conditions and the following disclaimer in the
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
14 * documentation and/or other materials provided with the distribution.
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
15 *
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
26 * POSSIBILITY OF SUCH DAMAGE.
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
27 */
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
28 /**
1091
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
29 * @file collection.h
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
30 * @brief Common definitions for various collection implementations.
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
31 * @author Mike Becker
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
32 * @author Olaf Wintermann
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
33 * @copyright 2-Clause BSD License
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
34 */
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
35
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
36 #ifndef UCX_COLLECTION_H
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
37 #define UCX_COLLECTION_H
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
38
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
39 #include "allocator.h"
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
40 #include "iterator.h"
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
41 #include "compare.h"
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
42
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
43 #ifdef __cplusplus
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
44 extern "C" {
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
45 #endif
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
46
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
47 /**
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
48 * Special constant used for creating collections that are storing pointers.
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
49 */
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
50 #define CX_STORE_POINTERS 0
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
51
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
52 /**
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
53 * Base attributes of a collection.
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
54 */
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
55 struct cx_collection_s {
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
56 /**
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
57 * The allocator to use.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
58 */
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 857
diff changeset
59 const CxAllocator *allocator;
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
60 /**
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
61 * The comparator function for the elements.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
62 */
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
63 cx_compare_func cmpfunc;
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
64 /**
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
65 * The size of each element.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
66 */
855
35bcb3216c0d fix inconsistent use of item_size and elem_size
Mike Becker <universe@uap-core.de>
parents: 854
diff changeset
67 size_t elem_size;
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
68 /**
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
69 * The number of currently stored elements.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
70 */
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
71 size_t size;
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
72 /**
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
73 * An optional simple destructor for the collection's elements.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
74 *
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
75 * @attention Read the documentation of the particular collection implementation
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
76 * whether this destructor shall only destroy the contents or also free the memory.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
77 */
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
78 cx_destructor_func simple_destructor;
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
79 /**
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
80 * An optional advanced destructor for the collection's elements.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
81 *
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
82 * @attention Read the documentation of the particular collection implementation
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
83 * whether this destructor shall only destroy the contents or also free the memory.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
84 */
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
85 cx_destructor_func2 advanced_destructor;
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
86 /**
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
87 * The pointer to additional data that is passed to the advanced destructor.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
88 */
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
89 void *destructor_data;
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
90 /**
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
91 * Indicates if this list is supposed to store pointers
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
92 * instead of copies of the actual objects.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
93 */
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
94 bool store_pointer;
1163
68ff0839bc6a optimize cx_arl_find_remove for sorted arrays - fixes #547
Mike Becker <universe@uap-core.de>
parents: 1091
diff changeset
95 /**
68ff0839bc6a optimize cx_arl_find_remove for sorted arrays - fixes #547
Mike Becker <universe@uap-core.de>
parents: 1091
diff changeset
96 * Indicates if this collection is guaranteed to be sorted.
68ff0839bc6a optimize cx_arl_find_remove for sorted arrays - fixes #547
Mike Becker <universe@uap-core.de>
parents: 1091
diff changeset
97 * Note that the elements can still be sorted, even when the collection is not aware of that.
68ff0839bc6a optimize cx_arl_find_remove for sorted arrays - fixes #547
Mike Becker <universe@uap-core.de>
parents: 1091
diff changeset
98 */
68ff0839bc6a optimize cx_arl_find_remove for sorted arrays - fixes #547
Mike Becker <universe@uap-core.de>
parents: 1091
diff changeset
99 bool sorted;
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 786
diff changeset
100 };
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
101
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
102 /**
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
103 * Use this macro to declare common members for a collection structure.
1091
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
104 *
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
105 * @par Example Use
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
106 * @code
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
107 * struct MyCustomSet {
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
108 * CX_COLLECTION_BASE;
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
109 * MySetElements *data;
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
110 * }
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
111 * @endcode
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
112 */
856
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
113 #define CX_COLLECTION_BASE struct cx_collection_s collection
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
114
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
115 /**
1171
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
116 * Returns the number of elements currently stored.
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
117 *
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
118 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
119 * @return (@c size_t) the number of currently stored elements
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
120 */
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
121 #define cxCollectionSize(c) ((c)->collection.size)
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
122
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
123 /**
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
124 * Returns the size of one element.
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
125 *
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
126 * If #cxCollectionStoresPointers() returns true, this is the size of a pointer.
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
127 *
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
128 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
129 * @return (@c size_t) the size of one element in bytes
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
130 */
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
131 #define cxCollectionElementSize(c) ((c)->collection.elem_size)
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
132
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
133 /**
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
134 * Indicates whether this collection only stores pointers instead of the actual data.
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
135 *
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
136 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
137 * @retval true if this collection stores only pointers to data
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
138 * @retval false if this collection stores the actual element's data
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
139 */
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
140 #define cxCollectionStoresPointers(c) ((c)->collection.store_pointer)
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
141
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
142 /**
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
143 * Indicates whether the collection can guarantee that the stored elements are currently sorted.
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
144 *
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
145 * This may return false even when the elements are sorted.
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
146 * It is totally up to the implementation of the collection whether it keeps track of the order of its elements.
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
147 *
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
148 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
149 * @retval true if the elements are currently sorted wrt. the collection's compare function
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
150 * @retval false if the order of elements is unknown
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
151 */
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
152 #define cxCollectionSorted(c) ((c)->collection.sorted)
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
153
155bc3b0dcb3 adds documentation for destructor functions and collections
Mike Becker <universe@uap-core.de>
parents: 1163
diff changeset
154 /**
857
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
155 * Sets a simple destructor function for this collection.
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
156 *
1091
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
157 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
857
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
158 * @param destr the destructor function
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
159 */
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
160 #define cxDefineDestructor(c, destr) \
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
161 (c)->collection.simple_destructor = (cx_destructor_func) destr
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
162
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
163 /**
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
164 * Sets a simple destructor function for this collection.
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
165 *
1091
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
166 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
857
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
167 * @param destr the destructor function
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
168 */
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
169 #define cxDefineAdvancedDestructor(c, destr, data) \
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
170 (c)->collection.advanced_destructor = (cx_destructor_func2) destr; \
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
171 (c)->collection.destructor_data = data
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
172
4d12e34bb130 add missing convenience functions
Mike Becker <universe@uap-core.de>
parents: 856
diff changeset
173 /**
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
174 * Invokes the simple destructor function for a specific element.
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
175 *
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
176 * Usually only used by collection implementations. There should be no need
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
177 * to invoke this macro manually.
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
178 *
1091
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
179 * When the collection stores pointers, those pointers are directly passed
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
180 * to the destructor. Otherwise, a pointer to the element is passed.
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
181 *
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
182 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
183 * @param e the element (the type is @c void* or @c void** depending on context)
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
184 */
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
185 #define cx_invoke_simple_destructor(c, e) \
856
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
186 (c)->collection.simple_destructor((c)->collection.store_pointer ? (*((void **) (e))) : (e))
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
187
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
188 /**
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
189 * Invokes the advanced destructor function for a specific element.
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
190 *
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
191 * Usually only used by collection implementations. There should be no need
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
192 * to invoke this macro manually.
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
193 *
1091
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
194 * When the collection stores pointers, those pointers are directly passed
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
195 * to the destructor. Otherwise, a pointer to the element is passed.
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
196 *
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
197 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
198 * @param e the element (the type is @c void* or @c void** depending on context)
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
199 */
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
200 #define cx_invoke_advanced_destructor(c, e) \
856
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
201 (c)->collection.advanced_destructor((c)->collection.destructor_data, \
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
202 (c)->collection.store_pointer ? (*((void **) (e))) : (e))
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
203
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
204
712
cff828e156a9 add missing docs for cx_invoke_destructor()
Mike Becker <universe@uap-core.de>
parents: 681
diff changeset
205 /**
cff828e156a9 add missing docs for cx_invoke_destructor()
Mike Becker <universe@uap-core.de>
parents: 681
diff changeset
206 * Invokes all available destructor functions for a specific element.
cff828e156a9 add missing docs for cx_invoke_destructor()
Mike Becker <universe@uap-core.de>
parents: 681
diff changeset
207 *
cff828e156a9 add missing docs for cx_invoke_destructor()
Mike Becker <universe@uap-core.de>
parents: 681
diff changeset
208 * Usually only used by collection implementations. There should be no need
cff828e156a9 add missing docs for cx_invoke_destructor()
Mike Becker <universe@uap-core.de>
parents: 681
diff changeset
209 * to invoke this macro manually.
cff828e156a9 add missing docs for cx_invoke_destructor()
Mike Becker <universe@uap-core.de>
parents: 681
diff changeset
210 *
1091
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
211 * When the collection stores pointers, those pointers are directly passed
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
212 * to the destructor. Otherwise, a pointer to the element is passed.
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
213 *
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
214 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
04a114799d9d refine docs for collection.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
215 * @param e the element (the type is @c void* or @c void** depending on context)
712
cff828e156a9 add missing docs for cx_invoke_destructor()
Mike Becker <universe@uap-core.de>
parents: 681
diff changeset
216 */
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
217 #define cx_invoke_destructor(c, e) \
856
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
218 if ((c)->collection.simple_destructor) cx_invoke_simple_destructor(c,e); \
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
219 if ((c)->collection.advanced_destructor) cx_invoke_advanced_destructor(c,e)
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
220
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
221 #ifdef __cplusplus
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
222 } // extern "C"
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
223 #endif
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
224
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents:
diff changeset
225 #endif // UCX_COLLECTION_H

mercurial