src/cx/map.h@9b767b07602c
src/cx/map.h
Fri, 27 May 2022 13:25:42 +0200
- author
- Mike Becker <universe@uap-core.de>
- date
- Fri, 27 May 2022 13:25:42 +0200
- changeset 558
- 9b767b07602c
- parent 555
- d79fbd028e26
- child 563
- 69a83fad8a35
- permissions
- -rw-r--r--
add convenience function to make keys from strings
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 */
37 #ifndef UCX_MAP_H
38 #define UCX_MAP_H
40 #include "common.h"
41 #include "allocator.h"
42 #include "iterator.h"
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
48 /** Type for the UCX map. */
49 typedef struct cx_map_s CxMap;
51 /** Type for a map entry. */
52 typedef struct cx_map_entry_s CxMapEntry;
54 /** Type for map class definitions. */
55 typedef struct cx_map_class_s cx_map_class;
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 };
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);
78 /**
79 * Removes all elements.
80 */
81 __attribute__((__nonnull__))
82 void (*clear)(struct cx_map_s *map);
84 /**
85 * Add or overwrite an element.
86 */
87 __attribute__((__nonnull__))
88 int (*put)(
89 CxMap *map,
90 CxDataPtr key,
91 void *value
92 );
94 /**
95 * Returns an element.
96 */
97 __attribute__((__nonnull__, __warn_unused_result__))
98 void *(*get)(
99 CxMap const *map,
100 CxDataPtr key
101 );
103 /**
104 * Removes an element.
105 */
106 __attribute__((__nonnull__, __warn_unused_result__))
107 void *(*remove)(
108 CxMap *map,
109 CxDataPtr key
110 );
112 /**
113 * Iterator over the key/value pairs.
114 */
115 __attribute__((__nonnull__, __warn_unused_result__))
116 CxIterator (*iterator)(CxMap *map);
118 /**
119 * Iterator over the keys.
120 */
121 __attribute__((__nonnull__, __warn_unused_result__))
122 CxIterator (*iterator_keys)(CxMap *map);
124 /**
125 * Iterator over the values.
126 */
127 __attribute__((__nonnull__, __warn_unused_result__))
128 CxIterator (*iterator_values)(CxMap *map);
129 };
131 /**
132 * A map entry.
133 */
134 struct cx_map_entry_s {
135 /**
136 * A pointer to the key.
137 */
138 CxDataPtr const *key;
139 /**
140 * A pointer to the value.
141 */
142 void *value;
143 };
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 }
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 }
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 *value
181 ) {
182 return map->cl->put(map, key, value);
183 }
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 static inline void *cxMapGet(
194 CxMap const *map,
195 CxDataPtr key
196 ) {
197 return map->cl->get(map, key);
198 }
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 static inline void *cxMapRemove(
209 CxMap *map,
210 CxDataPtr key
211 ) {
212 return map->cl->remove(map, key);
213 }
215 // TODO: set-like map operations (union, intersect, difference)
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 *map) {
228 return map->cl->iterator_values(map);
229 }
231 /**
232 * Creates a key iterator for a map.
233 *
234 * The elements of the iterator are keys of type CxDataPtr.
235 *
236 * \note An iterator iterates over all elements successively. Therefore the order
237 * highly depends on the map implementation and may change arbitrarily when the contents change.
238 *
239 * @param map the map to create the iterator for
240 * @return an iterator for the currently stored keys
241 */
242 __attribute__((__nonnull__, __warn_unused_result__))
243 static inline CxIterator cxMapIteratorKeys(CxMap *map) {
244 return map->cl->iterator_keys(map);
245 }
247 /**
248 * Creates an iterator for a map.
249 *
250 * The elements of the iterator are key/value pairs of type CxMapEntry.
251 *
252 * \note An iterator iterates over all elements successively. Therefore the order
253 * highly depends on the map implementation and may change arbitrarily when the contents change.
254 *
255 * @param map the map to create the iterator for
256 * @return an iterator for the currently stored entries
257 * @see cxMapIteratorKeys()
258 * @see cxMapIteratorValues()
259 */
260 __attribute__((__nonnull__, __warn_unused_result__))
261 static inline CxIterator cxMapIterator(CxMap *map) {
262 return map->cl->iterator(map);
263 }
265 /**
266 * Convenience function to make a key from a NULL-terminated string.
267 *
268 * @param str the NULL-terminated string
269 * @return the string wrapped to be used as a map key
270 */
271 __attribute__((__nonnull__, __warn_unused_result__))
272 CxDataPtr cxMapKeyStr(char const *str);
274 #ifdef __cplusplus
275 }
276 #endif
278 #endif // UCX_MAP_H
