|
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 "collection.h" |
|
42 #include "string.h" |
|
43 #include "hash_key.h" |
|
44 |
|
45 #ifdef __cplusplus |
|
46 extern "C" { |
|
47 #endif |
|
48 |
|
49 /** Type for the UCX map. */ |
|
50 typedef struct cx_map_s CxMap; |
|
51 |
|
52 /** Type for a map entry. */ |
|
53 typedef struct cx_map_entry_s CxMapEntry; |
|
54 |
|
55 /** Type for map class definitions. */ |
|
56 typedef struct cx_map_class_s cx_map_class; |
|
57 |
|
58 /** Structure for the UCX map. */ |
|
59 struct cx_map_s { |
|
60 CX_COLLECTION_MEMBERS |
|
61 /** The map class definition. */ |
|
62 cx_map_class *cl; |
|
63 }; |
|
64 |
|
65 /** |
|
66 * The type of iterator for a map. |
|
67 */ |
|
68 enum cx_map_iterator_type { |
|
69 /** |
|
70 * Iterates over key/value pairs. |
|
71 */ |
|
72 CX_MAP_ITERATOR_PAIRS, |
|
73 /** |
|
74 * Iterates over keys only. |
|
75 */ |
|
76 CX_MAP_ITERATOR_KEYS, |
|
77 /** |
|
78 * Iterates over values only. |
|
79 */ |
|
80 CX_MAP_ITERATOR_VALUES |
|
81 }; |
|
82 |
|
83 /** |
|
84 * The class definition for arbitrary maps. |
|
85 */ |
|
86 struct cx_map_class_s { |
|
87 /** |
|
88 * Deallocates the entire memory. |
|
89 */ |
|
90 __attribute__((__nonnull__)) |
|
91 void (*destructor)(struct cx_map_s *map); |
|
92 |
|
93 /** |
|
94 * Removes all elements. |
|
95 */ |
|
96 __attribute__((__nonnull__)) |
|
97 void (*clear)(struct cx_map_s *map); |
|
98 |
|
99 /** |
|
100 * Add or overwrite an element. |
|
101 */ |
|
102 __attribute__((__nonnull__)) |
|
103 int (*put)( |
|
104 CxMap *map, |
|
105 CxHashKey key, |
|
106 void *value |
|
107 ); |
|
108 |
|
109 /** |
|
110 * Returns an element. |
|
111 */ |
|
112 __attribute__((__nonnull__, __warn_unused_result__)) |
|
113 void *(*get)( |
|
114 CxMap const *map, |
|
115 CxHashKey key |
|
116 ); |
|
117 |
|
118 /** |
|
119 * Removes an element. |
|
120 */ |
|
121 __attribute__((__nonnull__)) |
|
122 void *(*remove)( |
|
123 CxMap *map, |
|
124 CxHashKey key, |
|
125 bool destroy |
|
126 ); |
|
127 |
|
128 /** |
|
129 * Creates an iterator for this map. |
|
130 */ |
|
131 __attribute__((__nonnull__, __warn_unused_result__)) |
|
132 CxIterator (*iterator)(CxMap const *map, enum cx_map_iterator_type type); |
|
133 }; |
|
134 |
|
135 /** |
|
136 * A map entry. |
|
137 */ |
|
138 struct cx_map_entry_s { |
|
139 /** |
|
140 * A pointer to the key. |
|
141 */ |
|
142 CxHashKey const *key; |
|
143 /** |
|
144 * A pointer to the value. |
|
145 */ |
|
146 void *value; |
|
147 }; |
|
148 |
|
149 /** |
|
150 * A shared instance of an empty map. |
|
151 * |
|
152 * Writing to that map is undefined. |
|
153 */ |
|
154 extern CxMap *const cxEmptyMap; |
|
155 |
|
156 /** |
|
157 * Advises the map to store copies of the objects (default mode of operation). |
|
158 * |
|
159 * Retrieving objects from this map will yield pointers to the copies stored |
|
160 * within this list. |
|
161 * |
|
162 * @param map the map |
|
163 * @see cxMapStorePointers() |
|
164 */ |
|
165 __attribute__((__nonnull__)) |
|
166 static inline void cxMapStoreObjects(CxMap *map) { |
|
167 map->store_pointer = false; |
|
168 } |
|
169 |
|
170 /** |
|
171 * Advises the map to only store pointers to the objects. |
|
172 * |
|
173 * Retrieving objects from this list will yield the original pointers stored. |
|
174 * |
|
175 * @note This function forcibly sets the element size to the size of a pointer. |
|
176 * Invoking this function on a non-empty map that already stores copies of |
|
177 * objects is undefined. |
|
178 * |
|
179 * @param map the map |
|
180 * @see cxMapStoreObjects() |
|
181 */ |
|
182 __attribute__((__nonnull__)) |
|
183 static inline void cxMapStorePointers(CxMap *map) { |
|
184 map->store_pointer = true; |
|
185 map->item_size = sizeof(void *); |
|
186 } |
|
187 |
|
188 |
|
189 /** |
|
190 * Deallocates the memory of the specified map. |
|
191 * |
|
192 * @param map the map to be destroyed |
|
193 */ |
|
194 __attribute__((__nonnull__)) |
|
195 static inline void cxMapDestroy(CxMap *map) { |
|
196 map->cl->destructor(map); |
|
197 } |
|
198 |
|
199 |
|
200 /** |
|
201 * Clears a map by removing all elements. |
|
202 * |
|
203 * @param map the map to be cleared |
|
204 */ |
|
205 __attribute__((__nonnull__)) |
|
206 static inline void cxMapClear(CxMap *map) { |
|
207 map->cl->clear(map); |
|
208 } |
|
209 |
|
210 |
|
211 // TODO: set-like map operations (union, intersect, difference) |
|
212 |
|
213 /** |
|
214 * Creates a value iterator for a map. |
|
215 * |
|
216 * \note An iterator iterates over all elements successively. Therefore the order |
|
217 * highly depends on the map implementation and may change arbitrarily when the contents change. |
|
218 * |
|
219 * @param map the map to create the iterator for |
|
220 * @return an iterator for the currently stored values |
|
221 */ |
|
222 __attribute__((__nonnull__, __warn_unused_result__)) |
|
223 static inline CxIterator cxMapIteratorValues(CxMap const *map) { |
|
224 return map->cl->iterator(map, CX_MAP_ITERATOR_VALUES); |
|
225 } |
|
226 |
|
227 /** |
|
228 * Creates a key iterator for a map. |
|
229 * |
|
230 * The elements of the iterator are keys of type CxHashKey. |
|
231 * |
|
232 * \note An iterator iterates over all elements successively. Therefore the order |
|
233 * highly depends on the map implementation and may change arbitrarily when the contents change. |
|
234 * |
|
235 * @param map the map to create the iterator for |
|
236 * @return an iterator for the currently stored keys |
|
237 */ |
|
238 __attribute__((__nonnull__, __warn_unused_result__)) |
|
239 static inline CxIterator cxMapIteratorKeys(CxMap const *map) { |
|
240 return map->cl->iterator(map, CX_MAP_ITERATOR_KEYS); |
|
241 } |
|
242 |
|
243 /** |
|
244 * Creates an iterator for a map. |
|
245 * |
|
246 * The elements of the iterator are key/value pairs of type CxMapEntry. |
|
247 * |
|
248 * \note An iterator iterates over all elements successively. Therefore the order |
|
249 * highly depends on the map implementation and may change arbitrarily when the contents change. |
|
250 * |
|
251 * @param map the map to create the iterator for |
|
252 * @return an iterator for the currently stored entries |
|
253 * @see cxMapIteratorKeys() |
|
254 * @see cxMapIteratorValues() |
|
255 */ |
|
256 __attribute__((__nonnull__, __warn_unused_result__)) |
|
257 static inline CxIterator cxMapIterator(CxMap const *map) { |
|
258 return map->cl->iterator(map, CX_MAP_ITERATOR_PAIRS); |
|
259 } |
|
260 |
|
261 |
|
262 /** |
|
263 * Creates a mutating iterator over the values of a map. |
|
264 * |
|
265 * \note An iterator iterates over all elements successively. Therefore the order |
|
266 * highly depends on the map implementation and may change arbitrarily when the contents change. |
|
267 * |
|
268 * @param map the map to create the iterator for |
|
269 * @return an iterator for the currently stored values |
|
270 */ |
|
271 __attribute__((__nonnull__, __warn_unused_result__)) |
|
272 CxMutIterator cxMapMutIteratorValues(CxMap *map); |
|
273 |
|
274 /** |
|
275 * Creates a mutating iterator over the keys of a map. |
|
276 * |
|
277 * The elements of the iterator are keys of type CxHashKey. |
|
278 * |
|
279 * \note An iterator iterates over all elements successively. Therefore the order |
|
280 * highly depends on the map implementation and may change arbitrarily when the contents change. |
|
281 * |
|
282 * @param map the map to create the iterator for |
|
283 * @return an iterator for the currently stored keys |
|
284 */ |
|
285 __attribute__((__nonnull__, __warn_unused_result__)) |
|
286 CxMutIterator cxMapMutIteratorKeys(CxMap *map); |
|
287 |
|
288 /** |
|
289 * Creates a mutating iterator for a map. |
|
290 * |
|
291 * The elements of the iterator are key/value pairs of type CxMapEntry. |
|
292 * |
|
293 * \note An iterator iterates over all elements successively. Therefore the order |
|
294 * highly depends on the map implementation and may change arbitrarily when the contents change. |
|
295 * |
|
296 * @param map the map to create the iterator for |
|
297 * @return an iterator for the currently stored entries |
|
298 * @see cxMapMutIteratorKeys() |
|
299 * @see cxMapMutIteratorValues() |
|
300 */ |
|
301 __attribute__((__nonnull__, __warn_unused_result__)) |
|
302 CxMutIterator cxMapMutIterator(CxMap *map); |
|
303 |
|
304 #ifdef __cplusplus |
|
305 } // end the extern "C" block here, because we want to start overloading |
|
306 |
|
307 /** |
|
308 * Puts a key/value-pair into the map. |
|
309 * |
|
310 * @param map the map |
|
311 * @param key the key |
|
312 * @param value the value |
|
313 * @return 0 on success, non-zero value on failure |
|
314 */ |
|
315 __attribute__((__nonnull__)) |
|
316 static inline int cxMapPut( |
|
317 CxMap *map, |
|
318 CxHashKey const &key, |
|
319 void *value |
|
320 ) { |
|
321 return map->cl->put(map, key, value); |
|
322 } |
|
323 |
|
324 |
|
325 /** |
|
326 * Puts a key/value-pair into the map. |
|
327 * |
|
328 * @param map the map |
|
329 * @param key the key |
|
330 * @param value the value |
|
331 * @return 0 on success, non-zero value on failure |
|
332 */ |
|
333 __attribute__((__nonnull__)) |
|
334 static inline int cxMapPut( |
|
335 CxMap *map, |
|
336 cxstring const &key, |
|
337 void *value |
|
338 ) { |
|
339 return map->cl->put(map, cx_hash_key_cxstr(key), value); |
|
340 } |
|
341 |
|
342 /** |
|
343 * Puts a key/value-pair into the map. |
|
344 * |
|
345 * @param map the map |
|
346 * @param key the key |
|
347 * @param value the value |
|
348 * @return 0 on success, non-zero value on failure |
|
349 */ |
|
350 __attribute__((__nonnull__)) |
|
351 static inline int cxMapPut( |
|
352 CxMap *map, |
|
353 cxmutstr const &key, |
|
354 void *value |
|
355 ) { |
|
356 return map->cl->put(map, cx_hash_key_cxstr(key), value); |
|
357 } |
|
358 |
|
359 /** |
|
360 * Puts a key/value-pair into the map. |
|
361 * |
|
362 * @param map the map |
|
363 * @param key the key |
|
364 * @param value the value |
|
365 * @return 0 on success, non-zero value on failure |
|
366 */ |
|
367 __attribute__((__nonnull__)) |
|
368 static inline int cxMapPut( |
|
369 CxMap *map, |
|
370 char const *key, |
|
371 void *value |
|
372 ) { |
|
373 return map->cl->put(map, cx_hash_key_str(key), value); |
|
374 } |
|
375 |
|
376 /** |
|
377 * Retrieves a value by using a key. |
|
378 * |
|
379 * @param map the map |
|
380 * @param key the key |
|
381 * @return the value |
|
382 */ |
|
383 __attribute__((__nonnull__, __warn_unused_result__)) |
|
384 static inline void *cxMapGet( |
|
385 CxMap const *map, |
|
386 CxHashKey const &key |
|
387 ) { |
|
388 return map->cl->get(map, key); |
|
389 } |
|
390 |
|
391 /** |
|
392 * Retrieves a value by using a key. |
|
393 * |
|
394 * @param map the map |
|
395 * @param key the key |
|
396 * @return the value |
|
397 */ |
|
398 __attribute__((__nonnull__, __warn_unused_result__)) |
|
399 static inline void *cxMapGet( |
|
400 CxMap const *map, |
|
401 cxstring const &key |
|
402 ) { |
|
403 return map->cl->get(map, cx_hash_key_cxstr(key)); |
|
404 } |
|
405 |
|
406 /** |
|
407 * Retrieves a value by using a key. |
|
408 * |
|
409 * @param map the map |
|
410 * @param key the key |
|
411 * @return the value |
|
412 */ |
|
413 __attribute__((__nonnull__, __warn_unused_result__)) |
|
414 static inline void *cxMapGet( |
|
415 CxMap const *map, |
|
416 cxmutstr const &key |
|
417 ) { |
|
418 return map->cl->get(map, cx_hash_key_cxstr(key)); |
|
419 } |
|
420 |
|
421 /** |
|
422 * Retrieves a value by using a key. |
|
423 * |
|
424 * @param map the map |
|
425 * @param key the key |
|
426 * @return the value |
|
427 */ |
|
428 __attribute__((__nonnull__, __warn_unused_result__)) |
|
429 static inline void *cxMapGet( |
|
430 CxMap const *map, |
|
431 char const *key |
|
432 ) { |
|
433 return map->cl->get(map, cx_hash_key_str(key)); |
|
434 } |
|
435 |
|
436 /** |
|
437 * Removes a key/value-pair from the map by using the key. |
|
438 * |
|
439 * Always invokes the destructor function, if any, on the removed element. |
|
440 * If this map is storing pointers and you just want to retrieve the pointer |
|
441 * without invoking the destructor, use cxMapRemoveAndGet(). |
|
442 * If you just want to detach the element from the map without invoking the |
|
443 * destructor or returning the element, use cxMapDetach(). |
|
444 * |
|
445 * @param map the map |
|
446 * @param key the key |
|
447 * @see cxMapRemoveAndGet() |
|
448 * @see cxMapDetach() |
|
449 */ |
|
450 __attribute__((__nonnull__)) |
|
451 static inline void cxMapRemove( |
|
452 CxMap *map, |
|
453 CxHashKey const &key |
|
454 ) { |
|
455 (void) map->cl->remove(map, key, true); |
|
456 } |
|
457 |
|
458 /** |
|
459 * Removes a key/value-pair from the map by using the key. |
|
460 * |
|
461 * Always invokes the destructor function, if any, on the removed element. |
|
462 * If this map is storing pointers and you just want to retrieve the pointer |
|
463 * without invoking the destructor, use cxMapRemoveAndGet(). |
|
464 * If you just want to detach the element from the map without invoking the |
|
465 * destructor or returning the element, use cxMapDetach(). |
|
466 * |
|
467 * @param map the map |
|
468 * @param key the key |
|
469 * @see cxMapRemoveAndGet() |
|
470 * @see cxMapDetach() |
|
471 */ |
|
472 __attribute__((__nonnull__)) |
|
473 static inline void cxMapRemove( |
|
474 CxMap *map, |
|
475 cxstring const &key |
|
476 ) { |
|
477 (void) map->cl->remove(map, cx_hash_key_cxstr(key), true); |
|
478 } |
|
479 |
|
480 /** |
|
481 * Removes a key/value-pair from the map by using the key. |
|
482 * |
|
483 * Always invokes the destructor function, if any, on the removed element. |
|
484 * If this map is storing pointers and you just want to retrieve the pointer |
|
485 * without invoking the destructor, use cxMapRemoveAndGet(). |
|
486 * If you just want to detach the element from the map without invoking the |
|
487 * destructor or returning the element, use cxMapDetach(). |
|
488 * |
|
489 * @param map the map |
|
490 * @param key the key |
|
491 * @see cxMapRemoveAndGet() |
|
492 * @see cxMapDetach() |
|
493 */ |
|
494 __attribute__((__nonnull__)) |
|
495 static inline void cxMapRemove( |
|
496 CxMap *map, |
|
497 cxmutstr const &key |
|
498 ) { |
|
499 (void) map->cl->remove(map, cx_hash_key_cxstr(key), true); |
|
500 } |
|
501 |
|
502 /** |
|
503 * Removes a key/value-pair from the map by using the key. |
|
504 * |
|
505 * Always invokes the destructor function, if any, on the removed element. |
|
506 * If this map is storing pointers and you just want to retrieve the pointer |
|
507 * without invoking the destructor, use cxMapRemoveAndGet(). |
|
508 * If you just want to detach the element from the map without invoking the |
|
509 * destructor or returning the element, use cxMapDetach(). |
|
510 * |
|
511 * @param map the map |
|
512 * @param key the key |
|
513 * @see cxMapRemoveAndGet() |
|
514 * @see cxMapDetach() |
|
515 */ |
|
516 __attribute__((__nonnull__)) |
|
517 static inline void cxMapRemove( |
|
518 CxMap *map, |
|
519 char const *key |
|
520 ) { |
|
521 (void) map->cl->remove(map, cx_hash_key_str(key), true); |
|
522 } |
|
523 |
|
524 /** |
|
525 * Detaches a key/value-pair from the map by using the key |
|
526 * without invoking the destructor. |
|
527 * |
|
528 * In general, you should only use this function if the map does not own |
|
529 * the data and there is a valid reference to the data somewhere else |
|
530 * in the program. In all other cases it is preferable to use |
|
531 * cxMapRemove() or cxMapRemoveAndGet(). |
|
532 * |
|
533 * @param map the map |
|
534 * @param key the key |
|
535 * @see cxMapRemove() |
|
536 * @see cxMapRemoveAndGet() |
|
537 */ |
|
538 __attribute__((__nonnull__)) |
|
539 static inline void cxMapDetach( |
|
540 CxMap *map, |
|
541 CxHashKey const &key |
|
542 ) { |
|
543 (void) map->cl->remove(map, key, false); |
|
544 } |
|
545 |
|
546 /** |
|
547 * Detaches a key/value-pair from the map by using the key |
|
548 * without invoking the destructor. |
|
549 * |
|
550 * In general, you should only use this function if the map does not own |
|
551 * the data and there is a valid reference to the data somewhere else |
|
552 * in the program. In all other cases it is preferable to use |
|
553 * cxMapRemove() or cxMapRemoveAndGet(). |
|
554 * |
|
555 * @param map the map |
|
556 * @param key the key |
|
557 * @see cxMapRemove() |
|
558 * @see cxMapRemoveAndGet() |
|
559 */ |
|
560 __attribute__((__nonnull__)) |
|
561 static inline void cxMapDetach( |
|
562 CxMap *map, |
|
563 cxstring const &key |
|
564 ) { |
|
565 (void) map->cl->remove(map, cx_hash_key_cxstr(key), false); |
|
566 } |
|
567 |
|
568 /** |
|
569 * Detaches a key/value-pair from the map by using the key |
|
570 * without invoking the destructor. |
|
571 * |
|
572 * In general, you should only use this function if the map does not own |
|
573 * the data and there is a valid reference to the data somewhere else |
|
574 * in the program. In all other cases it is preferable to use |
|
575 * cxMapRemove() or cxMapRemoveAndGet(). |
|
576 * |
|
577 * @param map the map |
|
578 * @param key the key |
|
579 * @see cxMapRemove() |
|
580 * @see cxMapRemoveAndGet() |
|
581 */ |
|
582 __attribute__((__nonnull__)) |
|
583 static inline void cxMapDetach( |
|
584 CxMap *map, |
|
585 cxmutstr const &key |
|
586 ) { |
|
587 (void) map->cl->remove(map, cx_hash_key_cxstr(key), false); |
|
588 } |
|
589 |
|
590 /** |
|
591 * Detaches a key/value-pair from the map by using the key |
|
592 * without invoking the destructor. |
|
593 * |
|
594 * In general, you should only use this function if the map does not own |
|
595 * the data and there is a valid reference to the data somewhere else |
|
596 * in the program. In all other cases it is preferable to use |
|
597 * cxMapRemove() or cxMapRemoveAndGet(). |
|
598 * |
|
599 * @param map the map |
|
600 * @param key the key |
|
601 * @see cxMapRemove() |
|
602 * @see cxMapRemoveAndGet() |
|
603 */ |
|
604 __attribute__((__nonnull__)) |
|
605 static inline void cxMapDetach( |
|
606 CxMap *map, |
|
607 char const *key |
|
608 ) { |
|
609 (void) map->cl->remove(map, cx_hash_key_str(key), false); |
|
610 } |
|
611 |
|
612 /** |
|
613 * Removes a key/value-pair from the map by using the key. |
|
614 * |
|
615 * This function can be used when the map is storing pointers, |
|
616 * in order to retrieve the pointer from the map without invoking |
|
617 * any destructor function. Sometimes you do not want the pointer |
|
618 * to be returned - in that case (instead of suppressing the "unused |
|
619 * result" warning) you can use cxMapDetach(). |
|
620 * |
|
621 * If this map is not storing pointers, this function behaves like |
|
622 * cxMapRemove() and returns \c NULL. |
|
623 * |
|
624 * @param map the map |
|
625 * @param key the key |
|
626 * @return the stored pointer or \c NULL if either the key is not present |
|
627 * in the map or the map is not storing pointers |
|
628 * @see cxMapStorePointers() |
|
629 * @see cxMapDetach() |
|
630 */ |
|
631 __attribute__((__nonnull__, __warn_unused_result__)) |
|
632 static inline void *cxMapRemoveAndGet( |
|
633 CxMap *map, |
|
634 CxHashKey key |
|
635 ) { |
|
636 return map->cl->remove(map, key, !map->store_pointer); |
|
637 } |
|
638 |
|
639 /** |
|
640 * Removes a key/value-pair from the map by using the key. |
|
641 * |
|
642 * This function can be used when the map is storing pointers, |
|
643 * in order to retrieve the pointer from the map without invoking |
|
644 * any destructor function. Sometimes you do not want the pointer |
|
645 * to be returned - in that case (instead of suppressing the "unused |
|
646 * result" warning) you can use cxMapDetach(). |
|
647 * |
|
648 * If this map is not storing pointers, this function behaves like |
|
649 * cxMapRemove() and returns \c NULL. |
|
650 * |
|
651 * @param map the map |
|
652 * @param key the key |
|
653 * @return the stored pointer or \c NULL if either the key is not present |
|
654 * in the map or the map is not storing pointers |
|
655 * @see cxMapStorePointers() |
|
656 * @see cxMapDetach() |
|
657 */ |
|
658 __attribute__((__nonnull__, __warn_unused_result__)) |
|
659 static inline void *cxMapRemoveAndGet( |
|
660 CxMap *map, |
|
661 cxstring key |
|
662 ) { |
|
663 return map->cl->remove(map, cx_hash_key_cxstr(key), !map->store_pointer); |
|
664 } |
|
665 |
|
666 /** |
|
667 * Removes a key/value-pair from the map by using the key. |
|
668 * |
|
669 * This function can be used when the map is storing pointers, |
|
670 * in order to retrieve the pointer from the map without invoking |
|
671 * any destructor function. Sometimes you do not want the pointer |
|
672 * to be returned - in that case (instead of suppressing the "unused |
|
673 * result" warning) you can use cxMapDetach(). |
|
674 * |
|
675 * If this map is not storing pointers, this function behaves like |
|
676 * cxMapRemove() and returns \c NULL. |
|
677 * |
|
678 * @param map the map |
|
679 * @param key the key |
|
680 * @return the stored pointer or \c NULL if either the key is not present |
|
681 * in the map or the map is not storing pointers |
|
682 * @see cxMapStorePointers() |
|
683 * @see cxMapDetach() |
|
684 */ |
|
685 __attribute__((__nonnull__, __warn_unused_result__)) |
|
686 static inline void *cxMapRemoveAndGet( |
|
687 CxMap *map, |
|
688 cxmutstr key |
|
689 ) { |
|
690 return map->cl->remove(map, cx_hash_key_cxstr(key), !map->store_pointer); |
|
691 } |
|
692 |
|
693 /** |
|
694 * Removes a key/value-pair from the map by using the key. |
|
695 * |
|
696 * This function can be used when the map is storing pointers, |
|
697 * in order to retrieve the pointer from the map without invoking |
|
698 * any destructor function. Sometimes you do not want the pointer |
|
699 * to be returned - in that case (instead of suppressing the "unused |
|
700 * result" warning) you can use cxMapDetach(). |
|
701 * |
|
702 * If this map is not storing pointers, this function behaves like |
|
703 * cxMapRemove() and returns \c NULL. |
|
704 * |
|
705 * @param map the map |
|
706 * @param key the key |
|
707 * @return the stored pointer or \c NULL if either the key is not present |
|
708 * in the map or the map is not storing pointers |
|
709 * @see cxMapStorePointers() |
|
710 * @see cxMapDetach() |
|
711 */ |
|
712 __attribute__((__nonnull__, __warn_unused_result__)) |
|
713 static inline void *cxMapRemoveAndGet( |
|
714 CxMap *map, |
|
715 char const *key |
|
716 ) { |
|
717 return map->cl->remove(map, cx_hash_key_str(key), !map->store_pointer); |
|
718 } |
|
719 |
|
720 #else // __cplusplus |
|
721 |
|
722 /** |
|
723 * Puts a key/value-pair into the map. |
|
724 * |
|
725 * @param map the map |
|
726 * @param key the key |
|
727 * @param value the value |
|
728 * @return 0 on success, non-zero value on failure |
|
729 */ |
|
730 __attribute__((__nonnull__)) |
|
731 static inline int cx_map_put( |
|
732 CxMap *map, |
|
733 CxHashKey key, |
|
734 void *value |
|
735 ) { |
|
736 return map->cl->put(map, key, value); |
|
737 } |
|
738 |
|
739 /** |
|
740 * Puts a key/value-pair into the map. |
|
741 * |
|
742 * @param map the map |
|
743 * @param key the key |
|
744 * @param value the value |
|
745 * @return 0 on success, non-zero value on failure |
|
746 */ |
|
747 __attribute__((__nonnull__)) |
|
748 static inline int cx_map_put_cxstr( |
|
749 CxMap *map, |
|
750 cxstring key, |
|
751 void *value |
|
752 ) { |
|
753 return map->cl->put(map, cx_hash_key_cxstr(key), value); |
|
754 } |
|
755 |
|
756 /** |
|
757 * Puts a key/value-pair into the map. |
|
758 * |
|
759 * @param map the map |
|
760 * @param key the key |
|
761 * @param value the value |
|
762 * @return 0 on success, non-zero value on failure |
|
763 */ |
|
764 __attribute__((__nonnull__)) |
|
765 static inline int cx_map_put_mustr( |
|
766 CxMap *map, |
|
767 cxmutstr key, |
|
768 void *value |
|
769 ) { |
|
770 return map->cl->put(map, cx_hash_key_cxstr(key), value); |
|
771 } |
|
772 |
|
773 /** |
|
774 * Puts a key/value-pair into the map. |
|
775 * |
|
776 * @param map the map |
|
777 * @param key the key |
|
778 * @param value the value |
|
779 * @return 0 on success, non-zero value on failure |
|
780 */ |
|
781 __attribute__((__nonnull__)) |
|
782 static inline int cx_map_put_str( |
|
783 CxMap *map, |
|
784 char const *key, |
|
785 void *value |
|
786 ) { |
|
787 return map->cl->put(map, cx_hash_key_str(key), value); |
|
788 } |
|
789 |
|
790 /** |
|
791 * Puts a key/value-pair into the map. |
|
792 * |
|
793 * @param map the map |
|
794 * @param key the key |
|
795 * @param value the value |
|
796 * @return 0 on success, non-zero value on failure |
|
797 */ |
|
798 #define cxMapPut(map, key, value) _Generic((key), \ |
|
799 CxHashKey: cx_map_put, \ |
|
800 cxstring: cx_map_put_cxstr, \ |
|
801 cxmutstr: cx_map_put_mustr, \ |
|
802 char*: cx_map_put_str, \ |
|
803 char const*: cx_map_put_str) \ |
|
804 (map, key, value) |
|
805 |
|
806 /** |
|
807 * Retrieves a value by using a key. |
|
808 * |
|
809 * @param map the map |
|
810 * @param key the key |
|
811 * @return the value |
|
812 */ |
|
813 __attribute__((__nonnull__, __warn_unused_result__)) |
|
814 static inline void *cx_map_get( |
|
815 CxMap const *map, |
|
816 CxHashKey key |
|
817 ) { |
|
818 return map->cl->get(map, key); |
|
819 } |
|
820 |
|
821 /** |
|
822 * Retrieves a value by using a key. |
|
823 * |
|
824 * @param map the map |
|
825 * @param key the key |
|
826 * @return the value |
|
827 */ |
|
828 __attribute__((__nonnull__, __warn_unused_result__)) |
|
829 static inline void *cx_map_get_cxstr( |
|
830 CxMap const *map, |
|
831 cxstring key |
|
832 ) { |
|
833 return map->cl->get(map, cx_hash_key_cxstr(key)); |
|
834 } |
|
835 |
|
836 /** |
|
837 * Retrieves a value by using a key. |
|
838 * |
|
839 * @param map the map |
|
840 * @param key the key |
|
841 * @return the value |
|
842 */ |
|
843 __attribute__((__nonnull__, __warn_unused_result__)) |
|
844 static inline void *cx_map_get_mustr( |
|
845 CxMap const *map, |
|
846 cxmutstr key |
|
847 ) { |
|
848 return map->cl->get(map, cx_hash_key_cxstr(key)); |
|
849 } |
|
850 |
|
851 /** |
|
852 * Retrieves a value by using a key. |
|
853 * |
|
854 * @param map the map |
|
855 * @param key the key |
|
856 * @return the value |
|
857 */ |
|
858 __attribute__((__nonnull__, __warn_unused_result__)) |
|
859 static inline void *cx_map_get_str( |
|
860 CxMap const *map, |
|
861 char const *key |
|
862 ) { |
|
863 return map->cl->get(map, cx_hash_key_str(key)); |
|
864 } |
|
865 |
|
866 /** |
|
867 * Retrieves a value by using a key. |
|
868 * |
|
869 * @param map the map |
|
870 * @param key the key |
|
871 * @return the value |
|
872 */ |
|
873 #define cxMapGet(map, key) _Generic((key), \ |
|
874 CxHashKey: cx_map_get, \ |
|
875 cxstring: cx_map_get_cxstr, \ |
|
876 cxmutstr: cx_map_get_mustr, \ |
|
877 char*: cx_map_get_str, \ |
|
878 char const*: cx_map_get_str) \ |
|
879 (map, key) |
|
880 |
|
881 /** |
|
882 * Removes a key/value-pair from the map by using the key. |
|
883 * |
|
884 * @param map the map |
|
885 * @param key the key |
|
886 */ |
|
887 __attribute__((__nonnull__)) |
|
888 static inline void cx_map_remove( |
|
889 CxMap *map, |
|
890 CxHashKey key |
|
891 ) { |
|
892 (void) map->cl->remove(map, key, true); |
|
893 } |
|
894 |
|
895 /** |
|
896 * Removes a key/value-pair from the map by using the key. |
|
897 * |
|
898 * @param map the map |
|
899 * @param key the key |
|
900 */ |
|
901 __attribute__((__nonnull__)) |
|
902 static inline void cx_map_remove_cxstr( |
|
903 CxMap *map, |
|
904 cxstring key |
|
905 ) { |
|
906 (void) map->cl->remove(map, cx_hash_key_cxstr(key), true); |
|
907 } |
|
908 |
|
909 /** |
|
910 * Removes a key/value-pair from the map by using the key. |
|
911 * |
|
912 * @param map the map |
|
913 * @param key the key |
|
914 */ |
|
915 __attribute__((__nonnull__)) |
|
916 static inline void cx_map_remove_mustr( |
|
917 CxMap *map, |
|
918 cxmutstr key |
|
919 ) { |
|
920 (void) map->cl->remove(map, cx_hash_key_cxstr(key), true); |
|
921 } |
|
922 |
|
923 /** |
|
924 * Removes a key/value-pair from the map by using the key. |
|
925 * |
|
926 * @param map the map |
|
927 * @param key the key |
|
928 */ |
|
929 __attribute__((__nonnull__)) |
|
930 static inline void cx_map_remove_str( |
|
931 CxMap *map, |
|
932 char const *key |
|
933 ) { |
|
934 (void) map->cl->remove(map, cx_hash_key_str(key), true); |
|
935 } |
|
936 |
|
937 /** |
|
938 * Removes a key/value-pair from the map by using the key. |
|
939 * |
|
940 * Always invokes the destructor function, if any, on the removed element. |
|
941 * If this map is storing pointers and you just want to retrieve the pointer |
|
942 * without invoking the destructor, use cxMapRemoveAndGet(). |
|
943 * If you just want to detach the element from the map without invoking the |
|
944 * destructor or returning the element, use cxMapDetach(). |
|
945 * |
|
946 * @param map the map |
|
947 * @param key the key |
|
948 * @see cxMapRemoveAndGet() |
|
949 * @see cxMapDetach() |
|
950 */ |
|
951 #define cxMapRemove(map, key) _Generic((key), \ |
|
952 CxHashKey: cx_map_remove, \ |
|
953 cxstring: cx_map_remove_cxstr, \ |
|
954 cxmutstr: cx_map_remove_mustr, \ |
|
955 char*: cx_map_remove_str, \ |
|
956 char const*: cx_map_remove_str) \ |
|
957 (map, key) |
|
958 |
|
959 /** |
|
960 * Detaches a key/value-pair from the map by using the key |
|
961 * without invoking the destructor. |
|
962 * |
|
963 * @param map the map |
|
964 * @param key the key |
|
965 */ |
|
966 __attribute__((__nonnull__)) |
|
967 static inline void cx_map_detach( |
|
968 CxMap *map, |
|
969 CxHashKey key |
|
970 ) { |
|
971 (void) map->cl->remove(map, key, false); |
|
972 } |
|
973 |
|
974 /** |
|
975 * Detaches a key/value-pair from the map by using the key |
|
976 * without invoking the destructor. |
|
977 * |
|
978 * @param map the map |
|
979 * @param key the key |
|
980 */ |
|
981 __attribute__((__nonnull__)) |
|
982 static inline void cx_map_detach_cxstr( |
|
983 CxMap *map, |
|
984 cxstring key |
|
985 ) { |
|
986 (void) map->cl->remove(map, cx_hash_key_cxstr(key), false); |
|
987 } |
|
988 |
|
989 /** |
|
990 * Detaches a key/value-pair from the map by using the key |
|
991 * without invoking the destructor. |
|
992 * |
|
993 * @param map the map |
|
994 * @param key the key |
|
995 */ |
|
996 __attribute__((__nonnull__)) |
|
997 static inline void cx_map_detach_mustr( |
|
998 CxMap *map, |
|
999 cxmutstr key |
|
1000 ) { |
|
1001 (void) map->cl->remove(map, cx_hash_key_cxstr(key), false); |
|
1002 } |
|
1003 |
|
1004 /** |
|
1005 * Detaches a key/value-pair from the map by using the key |
|
1006 * without invoking the destructor. |
|
1007 * |
|
1008 * @param map the map |
|
1009 * @param key the key |
|
1010 */ |
|
1011 __attribute__((__nonnull__)) |
|
1012 static inline void cx_map_detach_str( |
|
1013 CxMap *map, |
|
1014 char const *key |
|
1015 ) { |
|
1016 (void) map->cl->remove(map, cx_hash_key_str(key), false); |
|
1017 } |
|
1018 |
|
1019 /** |
|
1020 * Detaches a key/value-pair from the map by using the key |
|
1021 * without invoking the destructor. |
|
1022 * |
|
1023 * In general, you should only use this function if the map does not own |
|
1024 * the data and there is a valid reference to the data somewhere else |
|
1025 * in the program. In all other cases it is preferable to use |
|
1026 * cxMapRemove() or cxMapRemoveAndGet(). |
|
1027 * |
|
1028 * @param map the map |
|
1029 * @param key the key |
|
1030 * @see cxMapRemove() |
|
1031 * @see cxMapRemoveAndGet() |
|
1032 */ |
|
1033 #define cxMapDetach(map, key) _Generic((key), \ |
|
1034 CxHashKey: cx_map_detach, \ |
|
1035 cxstring: cx_map_detach_cxstr, \ |
|
1036 cxmutstr: cx_map_detach_mustr, \ |
|
1037 char*: cx_map_detach_str, \ |
|
1038 char const*: cx_map_detach_str) \ |
|
1039 (map, key) |
|
1040 |
|
1041 /** |
|
1042 * Removes a key/value-pair from the map by using the key. |
|
1043 * |
|
1044 * @param map the map |
|
1045 * @param key the key |
|
1046 * @return the stored pointer or \c NULL if either the key is not present |
|
1047 * in the map or the map is not storing pointers |
|
1048 */ |
|
1049 __attribute__((__nonnull__, __warn_unused_result__)) |
|
1050 static inline void *cx_map_remove_and_get( |
|
1051 CxMap *map, |
|
1052 CxHashKey key |
|
1053 ) { |
|
1054 return map->cl->remove(map, key, !map->store_pointer); |
|
1055 } |
|
1056 |
|
1057 /** |
|
1058 * Removes a key/value-pair from the map by using the key. |
|
1059 * |
|
1060 * @param map the map |
|
1061 * @param key the key |
|
1062 * @return the stored pointer or \c NULL if either the key is not present |
|
1063 * in the map or the map is not storing pointers |
|
1064 */ |
|
1065 __attribute__((__nonnull__, __warn_unused_result__)) |
|
1066 static inline void *cx_map_remove_and_get_cxstr( |
|
1067 CxMap *map, |
|
1068 cxstring key |
|
1069 ) { |
|
1070 return map->cl->remove(map, cx_hash_key_cxstr(key), !map->store_pointer); |
|
1071 } |
|
1072 |
|
1073 /** |
|
1074 * Removes a key/value-pair from the map by using the key. |
|
1075 * |
|
1076 * @param map the map |
|
1077 * @param key the key |
|
1078 * @return the stored pointer or \c NULL if either the key is not present |
|
1079 * in the map or the map is not storing pointers |
|
1080 */ |
|
1081 __attribute__((__nonnull__, __warn_unused_result__)) |
|
1082 static inline void *cx_map_remove_and_get_mustr( |
|
1083 CxMap *map, |
|
1084 cxmutstr key |
|
1085 ) { |
|
1086 return map->cl->remove(map, cx_hash_key_cxstr(key), !map->store_pointer); |
|
1087 } |
|
1088 |
|
1089 /** |
|
1090 * Removes a key/value-pair from the map by using the key. |
|
1091 * |
|
1092 * @param map the map |
|
1093 * @param key the key |
|
1094 * @return the stored pointer or \c NULL if either the key is not present |
|
1095 * in the map or the map is not storing pointers |
|
1096 */ |
|
1097 __attribute__((__nonnull__, __warn_unused_result__)) |
|
1098 static inline void *cx_map_remove_and_get_str( |
|
1099 CxMap *map, |
|
1100 char const *key |
|
1101 ) { |
|
1102 return map->cl->remove(map, cx_hash_key_str(key), !map->store_pointer); |
|
1103 } |
|
1104 |
|
1105 /** |
|
1106 * Removes a key/value-pair from the map by using the key. |
|
1107 * |
|
1108 * This function can be used when the map is storing pointers, |
|
1109 * in order to retrieve the pointer from the map without invoking |
|
1110 * any destructor function. Sometimes you do not want the pointer |
|
1111 * to be returned - in that case (instead of suppressing the "unused |
|
1112 * result" warning) you can use cxMapDetach(). |
|
1113 * |
|
1114 * If this map is not storing pointers, this function behaves like |
|
1115 * cxMapRemove() and returns \c NULL. |
|
1116 * |
|
1117 * @param map the map |
|
1118 * @param key the key |
|
1119 * @return the stored pointer or \c NULL if either the key is not present |
|
1120 * in the map or the map is not storing pointers |
|
1121 * @see cxMapStorePointers() |
|
1122 * @see cxMapDetach() |
|
1123 */ |
|
1124 #define cxMapRemoveAndGet(map, key) _Generic((key), \ |
|
1125 CxHashKey: cx_map_remove_and_get, \ |
|
1126 cxstring: cx_map_remove_and_get_cxstr, \ |
|
1127 cxmutstr: cx_map_remove_and_get_mustr, \ |
|
1128 char*: cx_map_remove_and_get_str, \ |
|
1129 char const*: cx_map_remove_and_get_str) \ |
|
1130 (map, key) |
|
1131 |
|
1132 #endif // __cplusplus |
|
1133 |
|
1134 #endif // UCX_MAP_H |