Mercurial > hg > ucx / file comparison

comparison: src/cx/map.h

src/cx/map.h

changeset 549
d7f0b5a9a985
child 550
89b2a83728b1
equal deleted inserted replaced
548:459bca1cdf8d 549:d7f0b5a9a985
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28 /**
29 * \file map.h
30 * \brief Interface for map implementations.
31 * \author Mike Becker
32 * \author Olaf Wintermann
33 * \version 3.0
34 * \copyright 2-Clause BSD License
35 */
36
37 #ifndef UCX_MAP_H
38 #define UCX_MAP_H
39
40 #include "common.h"
41 #include "allocator.h"
42 #include "iterator.h"
43
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47
48 /** Type for the UCX map. */
49 typedef struct cx_map_s CxMap;
50
51 /** Type for a map entry. */
52 typedef struct cx_map_entry_s CxMapEntry;
53
54 /** Type for map class definitions. */
55 typedef struct cx_map_class_s cx_map_class;
56
57 /** Structure for the UCX map. */
58 struct cx_map_s {
59 /** The map class definition. */
60 cx_map_class *cl;
61 /** An allocator that is used for the map elements. */
62 CxAllocator *allocator;
63 /** The number of elements currently stored. */
64 size_t size;
65 // TODO: elemsize + a flag if values shall be copied to the map
66 };
67
68 /**
69 * The class definition for arbitrary maps.
70 */
71 struct cx_map_class_s {
72 /**
73 * Deallocates the entire memory.
74 */
75 __attribute__((__nonnull__))
76 void (*destructor)(struct cx_map_s *map);
77
78 /**
79 * Removes all elements.
80 */
81 __attribute__((__nonnull__))
82 void (*clear)(struct cx_map_s *map);
83
84 /**
85 * Add or overwrite an element.
86 */
87 __attribute__((__nonnull__))
88 int (*put)(
89 CxMap *map,
90 CxDataPtr key,
91 void const *value
92 );
93
94 /**
95 * Returns an element.
96 */
97 __attribute__((__nonnull__, __warn_unused_result__))
98 void *(*get)(
99 CxMap const *map,
100 CxDataPtr key
101 );
102
103 /**
104 * Removes an element.
105 */
106 __attribute__((__nonnull__, __warn_unused_result__))
107 void *(*remove)(
108 CxMap const *map,
109 CxDataPtr key
110 );
111
112 /**
113 * Iterator over the key/value pairs.
114 */
115 __attribute__((__nonnull__, __warn_unused_result__))
116 CxIterator (*iterator)(CxMap const *map);
117
118 /**
119 * Iterator over the keys.
120 */
121 __attribute__((__nonnull__, __warn_unused_result__))
122 CxIterator (*iterator_keys)(CxMap const *map);
123
124 /**
125 * Iterator over the values.
126 */
127 __attribute__((__nonnull__, __warn_unused_result__))
128 CxIterator (*iterator_values)(CxMap const *map);
129 };
130
131 /**
132 * A map entry.
133 */
134 struct cx_map_entry_s {
135 /**
136 * The key.
137 */
138 CxDataPtr key;
139 /**
140 * The value.
141 */
142 void const *value;
143 };
144
145
146 /**
147 * Deallocates the memory of the specified map.
148 *
149 * @param map the map to be destroyed
150 */
151 __attribute__((__nonnull__))
152 static inline void cxMapDestroy(CxMap *map) {
153 // TODO: likely to add auto-free feature for contents in the future
154 map->cl->destructor(map);
155 }
156
157
158 /**
159 * Clears a map by removing all elements.
160 *
161 * @param map the map to be cleared
162 */
163 __attribute__((__nonnull__))
164 static inline void cxMapClear(CxMap *map) {
165 map->cl->clear(map);
166 }
167
168 /**
169 * Puts a key/value-pair into the map.
170 *
171 * @param map the map
172 * @param key the key
173 * @param value the value
174 * @return 0 on success, non-zero value on failure
175 */
176 __attribute__((__nonnull__))
177 static inline int cxMapPut(
178 CxMap *map,
179 CxDataPtr key,
180 void const *value
181 ) {
182 return map->cl->put(map, key, value);
183 }
184
185 /**
186 * Retrieves a value by using a key.
187 *
188 * @param map the map
189 * @param key the key
190 * @return the value
191 */
192 __attribute__((__nonnull__, __warn_unused_result__))
193 void *cxMapGet(
194 CxMap const *map,
195 CxDataPtr key
196 ) {
197 return map->cl->get(map, key);
198 }
199
200 /**
201 * Removes a key/value-pair from the map by using the key.
202 *
203 * @param map the map
204 * @param key the key
205 * @return the removed value
206 */
207 __attribute__((__nonnull__, __warn_unused_result__))
208 void *cxMapRemove(
209 CxMap *map,
210 CxDataPtr key
211 ) {
212 return map->cl->remove(map, key);
213 }
214
215 // TODO: set-like map operations (union, intersect, difference)
216
217 /**
218 * Creates a value iterator for a map.
219 *
220 * \note An iterator iterates over all elements successively. Therefore the order
221 * highly depends on the map implementation and may change arbitrarily when the contents change.
222 *
223 * @param map the map to create the iterator for
224 * @return an iterator for the currently stored values
225 */
226 __attribute__((__nonnull__, __warn_unused_result__))
227 static inline CxIterator cxMapIteratorValues(CxMap const *map) {
228 return map->cl->iterator_values(map);
229 }
230
231 /**
232 * Creates a key iterator for a map.
233 *
234 * \note An iterator iterates over all elements successively. Therefore the order
235 * highly depends on the map implementation and may change arbitrarily when the contents change.
236 *
237 * @param map the map to create the iterator for
238 * @return an iterator for the currently stored keys
239 */
240 __attribute__((__nonnull__, __warn_unused_result__))
241 static inline CxIterator cxMapIteratorKeys(CxMap const *map) {
242 return map->cl->iterator_keys(map);
243 }
244
245 /**
246 * Creates an iterator for a map.
247 *
248 * The values of the iterator are dynamically created key/value pairs of type CxMapEntry.
249 *
250 * \note An iterator iterates over all elements successively. Therefore the order
251 * highly depends on the map implementation and may change arbitrarily when the contents change.
252 *
253 * @param map the map to create the iterator for
254 * @return an iterator for the currently stored keys
255 * @see cxMapIteratorKeys()
256 * @see cxMapIteratorValues()
257 */
258 __attribute__((__nonnull__, __warn_unused_result__))
259 static inline CxIterator cxMapIterator(CxMap const *map) {
260 return map->cl->iterator(map);
261 }
262
263
264 #ifdef __cplusplus
265 }
266 #endif
267
268 #endif // UCX_MAP_H

Mercurial Repository: ucx

mercurial