src/cx/map.h

Thu, 16 Oct 2025 19:57:47 +0200

author
Mike Becker <universe@uap-core.de>
date
Thu, 16 Oct 2025 19:57:47 +0200
changeset 1426
3a89b31f0724
parent 1424
563033aa998c
child 1429
6e0c3a8a914a
permissions
-rw-r--r--

clean up header files and adds support for comparing arbitrary strings with string.h functions

549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1 /*
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
3 *
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
5 *
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
6 * Redistribution and use in source and binary forms, with or without
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
7 * modification, are permitted provided that the following conditions are met:
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
8 *
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
9 * 1. Redistributions of source code must retain the above copyright
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
10 * notice, this list of conditions and the following disclaimer.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
11 *
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
12 * 2. Redistributions in binary form must reproduce the above copyright
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
13 * notice, this list of conditions and the following disclaimer in the
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
14 * documentation and/or other materials provided with the distribution.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
15 *
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
d7f0b5a9a985 #189 declare basic map functions
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
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
26 * POSSIBILITY OF SUCH DAMAGE.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
27 */
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
28 /**
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
29 * @file map.h
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
30 * @brief Interface for map implementations.
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
31 * @author Mike Becker
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
32 * @author Olaf Wintermann
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
33 * @copyright 2-Clause BSD License
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
34 */
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
35
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
36 #ifndef UCX_MAP_H
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
37 #define UCX_MAP_H
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
38
681
502105523db7 fix common.h include problems - fixes #255
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
39 #include "common.h"
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents: 669
diff changeset
40 #include "collection.h"
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
41 #include "string.h"
563
69a83fad8a35 improve hash key handling
Mike Becker <universe@uap-core.de>
parents: 558
diff changeset
42 #include "hash_key.h"
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
43
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
44 #ifdef __cplusplus
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
45 extern "C" {
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
46 #endif
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
47
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
48 /** Type for the UCX map. */
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
49 typedef struct cx_map_s CxMap;
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
50
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
51 /** Type for a map entry. */
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
52 typedef struct cx_map_entry_s CxMapEntry;
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
53
1115
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
54 /** Type for a map iterator. */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
55 typedef struct cx_map_iterator_s CxMapIterator;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
56
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
57 /** Type for map class definitions. */
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
58 typedef struct cx_map_class_s cx_map_class;
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
59
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
60 /** Structure for the UCX map. */
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
61 struct cx_map_s {
854
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
62 /**
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
63 * Base attributes.
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
64 */
fe0d69d72bcd fix members inherited by macro or include are not documented
Mike Becker <universe@uap-core.de>
parents: 853
diff changeset
65 CX_COLLECTION_BASE;
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
66 /** The map class definition. */
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
67 cx_map_class *cl;
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
68 };
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
69
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
70 /**
1115
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
71 * A map entry.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
72 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
73 struct cx_map_entry_s {
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
74 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
75 * A pointer to the key.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
76 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
77 const CxHashKey *key;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
78 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
79 * A pointer to the value.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
80 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
81 void *value;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
82 };
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
83
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
84 /**
709
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
85 * The type of iterator for a map.
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
86 */
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
87 enum cx_map_iterator_type {
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
88 /**
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
89 * Iterates over key/value pairs.
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
90 */
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
91 CX_MAP_ITERATOR_PAIRS,
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
92 /**
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
93 * Iterates over keys only.
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
94 */
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
95 CX_MAP_ITERATOR_KEYS,
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
96 /**
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
97 * Iterates over values only.
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
98 */
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
99 CX_MAP_ITERATOR_VALUES
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
100 };
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
101
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
102 /**
1115
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
103 * Internal iterator struct - use CxMapIterator.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
104 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
105 struct cx_map_iterator_s {
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
106 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
107 * Inherited common data for all iterators.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
108 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
109 CX_ITERATOR_BASE;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
110
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
111 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
112 * Handle for the source map.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
113 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
114 union {
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
115 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
116 * Access for mutating iterators.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
117 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
118 CxMap *m;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
119 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
120 * Access for normal iterators.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
121 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
122 const CxMap *c;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
123 } map;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
124
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
125 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
126 * Handle for the current element.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
127 *
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
128 * @attention Depends on the map implementation, do not assume a type (better: do not use!).
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
129 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
130 void *elem;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
131
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
132 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
133 * Reserved memory for a map entry.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
134 *
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
135 * If a map implementation uses an incompatible layout, the iterator needs something
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
136 * to point to during iteration which @em is compatible.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
137 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
138 CxMapEntry entry;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
139
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
140 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
141 * Field for storing the current slot number.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
142 *
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
143 * (Used internally)
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
144 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
145 size_t slot;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
146
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
147 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
148 * Counts the elements successfully.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
149 * It usually does not denote a stable index within the map as it would be for arrays.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
150 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
151 size_t index;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
152
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
153 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
154 * The size of a value stored in this map.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
155 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
156 size_t elem_size;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
157
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
158 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
159 * May contain the total number of elements, if known.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
160 * Set to @c SIZE_MAX when the total number is unknown during iteration.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
161 *
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
162 * @remark The UCX implementations of #CxMap always know the number of elements they store.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
163 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
164 size_t elem_count;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
165
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
166 /**
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
167 * The type of this iterator.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
168 */
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
169 enum cx_map_iterator_type type;
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
170 };
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
171
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
172 /**
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
173 * The class definition for arbitrary maps.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
174 */
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
175 struct cx_map_class_s {
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
176 /**
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
177 * Deallocates the entire memory.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
178 */
993
b642eca4b956 make names of destroy and free functions consistent - fixes #484
Mike Becker <universe@uap-core.de>
parents: 992
diff changeset
179 void (*deallocate)(struct cx_map_s *map);
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
180
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
181 /**
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
182 * Removes all elements.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
183 */
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
184 void (*clear)(struct cx_map_s *map);
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
185
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
186 /**
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
187 * Add or overwrite an element.
1341
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
188 * If the @p value is @c NULL, the implementation
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
189 * shall only allocate memory instead of adding an existing value to the map.
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
190 * Returns a pointer to the allocated memory or @c NULL if allocation fails.
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
191 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
192 void *(*put)(CxMap *map, CxHashKey key, void *value);
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
193
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
194 /**
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
195 * Returns an element.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
196 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
197 void *(*get)(const CxMap *map, CxHashKey key);
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
198
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
199 /**
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
200 * Removes an element.
994
3603bdf4a78b remove map detach function - fixes #487
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
201 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
202 * Implementations SHALL check if @p targetbuf is set and copy the elements
994
3603bdf4a78b remove map detach function - fixes #487
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
203 * to the buffer without invoking any destructor.
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
204 * When @p targetbuf is not set, the destructors SHALL be invoked.
994
3603bdf4a78b remove map detach function - fixes #487
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
205 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
206 * The function SHALL return zero when the @p key was found and
994
3603bdf4a78b remove map detach function - fixes #487
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
207 * non-zero, otherwise.
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
208 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
209 int (*remove)(CxMap *map, CxHashKey key, void *targetbuf);
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
210
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
211 /**
709
1e8ba59e7911 simplify map class structure
Mike Becker <universe@uap-core.de>
parents: 706
diff changeset
212 * Creates an iterator for this map.
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
213 */
1115
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
214 CxMapIterator (*iterator)(const CxMap *map, enum cx_map_iterator_type type);
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
215 };
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
216
714
34565d898f1f add missing docs for cxEmptyMap
Mike Becker <universe@uap-core.de>
parents: 710
diff changeset
217 /**
34565d898f1f add missing docs for cxEmptyMap
Mike Becker <universe@uap-core.de>
parents: 710
diff changeset
218 * A shared instance of an empty map.
34565d898f1f add missing docs for cxEmptyMap
Mike Becker <universe@uap-core.de>
parents: 710
diff changeset
219 *
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 984
diff changeset
220 * Writing to that map is not allowed.
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
221 *
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1411
diff changeset
222 * You can use this as a placeholder for initializing CxMap pointers
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
223 * for which you do not want to reserve memory right from the beginning.
714
34565d898f1f add missing docs for cxEmptyMap
Mike Becker <universe@uap-core.de>
parents: 710
diff changeset
224 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
225 CX_EXPORT extern CxMap *const cxEmptyMap;
706
8c6edaccaef1 add empty map implementation - fixes #259
Mike Becker <universe@uap-core.de>
parents: 694
diff changeset
226
658
56c62780582e make hashmap store objects instead of pointers by default - fixes #239
Mike Becker <universe@uap-core.de>
parents: 630
diff changeset
227 /**
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
228 * Deallocates the memory of the specified map.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
229 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
230 * Also calls the content destructor functions for each element, if specified.
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
231 *
993
b642eca4b956 make names of destroy and free functions consistent - fixes #484
Mike Becker <universe@uap-core.de>
parents: 992
diff changeset
232 * @param map the map to be freed
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
233 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
234 CX_EXPORT void cxMapFree(CxMap *map);
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
235
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
236
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
237 /**
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
238 * Clears a map by removing all elements.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
239 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
240 * Also calls the content destructor functions for each element, if specified.
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
241 *
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
242 * @param map the map to be cleared
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
243 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 984
diff changeset
244 cx_attr_nonnull
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
245 CX_EXPORT void cxMapClear(CxMap *map);
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
246
856
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
247 /**
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
248 * Returns the number of elements in this map.
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
249 *
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
250 * @param map the map
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
251 * @return the number of stored elements
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
252 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 984
diff changeset
253 cx_attr_nonnull
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
254 CX_EXPORT size_t cxMapSize(const CxMap *map);
856
6bbbf219251d fix name of collection base member (to avoid base.base)
Mike Becker <universe@uap-core.de>
parents: 855
diff changeset
255
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
256 /**
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
257 * Creates a value iterator for a map.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
258 *
1115
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
259 * When the map is storing pointers, those pointers are returned.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
260 * Otherwise, the iterator iterates over pointers to the memory within the map where the
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
261 * respective elements are stored.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
262 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
263 * @note An iterator iterates over all elements successively. Therefore, the order
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
264 * highly depends on the map implementation and may change arbitrarily when the contents change.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
265 *
1344
8afaeb395b3c add support for NULL in map iterators
Mike Becker <universe@uap-core.de>
parents: 1341
diff changeset
266 * @param map the map to create the iterator for (can be @c NULL)
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
267 * @return an iterator for the currently stored values
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
268 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 984
diff changeset
269 cx_attr_nodiscard
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
270 CX_EXPORT CxMapIterator cxMapIteratorValues(const CxMap *map);
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
271
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
272 /**
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
273 * Creates a key iterator for a map.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
274 *
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1411
diff changeset
275 * The elements of the iterator are keys of type CxHashKey, and the pointer returned
1115
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
276 * during iterator shall be treated as @c const @c CxHashKey* .
555
d79fbd028e26 fix documentation for map iterators
Mike Becker <universe@uap-core.de>
parents: 553
diff changeset
277 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
278 * @note An iterator iterates over all elements successively. Therefore, the order
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
279 * highly depends on the map implementation and may change arbitrarily when the contents change.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
280 *
1344
8afaeb395b3c add support for NULL in map iterators
Mike Becker <universe@uap-core.de>
parents: 1341
diff changeset
281 * @param map the map to create the iterator for (can be @c NULL)
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
282 * @return an iterator for the currently stored keys
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
283 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 984
diff changeset
284 cx_attr_nodiscard
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
285 CX_EXPORT CxMapIterator cxMapIteratorKeys(const CxMap *map);
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
286
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
287 /**
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
288 * Creates an iterator for a map.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
289 *
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1411
diff changeset
290 * The elements of the iterator are key/value pairs of type CxMapEntry, and the pointer returned
1115
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
291 * during iterator shall be treated as @c const @c CxMapEntry* .
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
292 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
293 * @note An iterator iterates over all elements successively. Therefore, the order
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
294 * highly depends on the map implementation and may change arbitrarily when the contents change.
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
295 *
1344
8afaeb395b3c add support for NULL in map iterators
Mike Becker <universe@uap-core.de>
parents: 1341
diff changeset
296 * @param map the map to create the iterator for (can be @c NULL)
555
d79fbd028e26 fix documentation for map iterators
Mike Becker <universe@uap-core.de>
parents: 553
diff changeset
297 * @return an iterator for the currently stored entries
549
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
298 * @see cxMapIteratorKeys()
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
299 * @see cxMapIteratorValues()
d7f0b5a9a985 #189 declare basic map functions
Mike Becker <universe@uap-core.de>
parents:
diff changeset
300 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 984
diff changeset
301 cx_attr_nodiscard
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
302 CX_EXPORT CxMapIterator cxMapIterator(const CxMap *map);
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
303
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
304 /**
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
305 * Creates a mutating iterator over the values of a map.
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
306 *
1115
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
307 * When the map is storing pointers, those pointers are returned.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
308 * Otherwise, the iterator iterates over pointers to the memory within the map where the
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
309 * respective elements are stored.
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
310 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
311 * @note An iterator iterates over all elements successively. Therefore, the order
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
312 * highly depends on the map implementation and may change arbitrarily when the contents change.
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
313 *
1344
8afaeb395b3c add support for NULL in map iterators
Mike Becker <universe@uap-core.de>
parents: 1341
diff changeset
314 * @param map the map to create the iterator for (can be @c NULL)
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
315 * @return an iterator for the currently stored values
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
316 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 984
diff changeset
317 cx_attr_nodiscard
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
318 CX_EXPORT CxMapIterator cxMapMutIteratorValues(CxMap *map);
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
319
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
320 /**
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
321 * Creates a mutating iterator over the keys of a map.
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
322 *
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1411
diff changeset
323 * The elements of the iterator are keys of type CxHashKey, and the pointer returned
1115
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
324 * during iterator shall be treated as @c const @c CxHashKey* .
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
325 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
326 * @note An iterator iterates over all elements successively. Therefore, the order
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
327 * highly depends on the map implementation and may change arbitrarily when the contents change.
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
328 *
1344
8afaeb395b3c add support for NULL in map iterators
Mike Becker <universe@uap-core.de>
parents: 1341
diff changeset
329 * @param map the map to create the iterator for (can be @c NULL)
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
330 * @return an iterator for the currently stored keys
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
331 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 984
diff changeset
332 cx_attr_nodiscard
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
333 CX_EXPORT CxMapIterator cxMapMutIteratorKeys(CxMap *map);
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
334
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
335 /**
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
336 * Creates a mutating iterator for a map.
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
337 *
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1411
diff changeset
338 * The elements of the iterator are key/value pairs of type CxMapEntry, and the pointer returned
1115
6db21dee4929 create specialized map iterators - fixes #550
Mike Becker <universe@uap-core.de>
parents: 1114
diff changeset
339 * during iterator shall be treated as @c const @c CxMapEntry* .
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
340 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
341 * @note An iterator iterates over all elements successively. Therefore, the order
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
342 * highly depends on the map implementation and may change arbitrarily when the contents change.
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
343 *
1344
8afaeb395b3c add support for NULL in map iterators
Mike Becker <universe@uap-core.de>
parents: 1341
diff changeset
344 * @param map the map to create the iterator for (can be @c NULL)
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
345 * @return an iterator for the currently stored entries
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
346 * @see cxMapMutIteratorKeys()
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
347 * @see cxMapMutIteratorValues()
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
348 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 984
diff changeset
349 cx_attr_nodiscard
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
350 CX_EXPORT CxMapIterator cxMapMutIterator(CxMap *map);
630
ac5e7f789048 separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents: 564
diff changeset
351
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
352 /**
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
353 * Puts a key/value-pair into the map.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
354 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
355 * A possible existing value will be overwritten.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
356 * If destructor functions are specified, they are called for
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
357 * the overwritten element.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
358 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
359 * If this map is storing pointers, the @p value pointer is written
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
360 * to the map. Otherwise, the memory is copied from @p value with
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
361 * memcpy().
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
362 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
363 * The @p key is always copied.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
364 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
365 * @param map the map
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
366 * @param key the key
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
367 * @param value the value
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
368 * @retval zero success
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
369 * @retval non-zero value on memory allocation failure
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
370 * @see cxMapPut()
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
371 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 984
diff changeset
372 cx_attr_nonnull
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
373 CX_EXPORT int cx_map_put(CxMap *map, CxHashKey key, void *value);
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
374
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
375 /**
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
376 * Puts a key/value-pair into the map.
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
377 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
378 * A possible existing value will be overwritten.
1114
ad5eeb256242 fix that overwriting a map element did not call any destructor function
Mike Becker <universe@uap-core.de>
parents: 1111
diff changeset
379 * If destructor functions are specified, they are called for
ad5eeb256242 fix that overwriting a map element did not call any destructor function
Mike Becker <universe@uap-core.de>
parents: 1111
diff changeset
380 * the overwritten element.
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
381 *
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
382 * If this map is storing pointers, the @p value pointer is written
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
383 * to the map. Otherwise, the memory is copied from @p value with
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
384 * memcpy().
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
385 *
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
386 * The @p key is always copied.
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
387 *
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
388 * @param map (@c CxMap*) the map
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
389 * @param key (any supported key type) the key
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
390 * @param value (@c void*) the value
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
391 * @retval zero success
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
392 * @retval non-zero value on memory allocation failure
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
393 * @see CX_HASH_KEY()
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
394 */
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
395 #define cxMapPut(map, key, value) cx_map_put(map, CX_HASH_KEY(key), value)
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
396
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
397 /**
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
398 * Allocates memory for a value in the map associated with the specified key.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
399 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
400 * A possible existing value will be overwritten.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
401 * If destructor functions are specified, they are called for
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
402 * the overwritten element.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
403 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
404 * If the map is storing pointers, this function returns a @c void** pointer,
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
405 * meaning a pointer to that pointer.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
406 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
407 * The @p key is always copied.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
408 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
409 * @param map the map
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
410 * @param key the key
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
411 * @return the pointer to the allocated memory or @c NULL if allocation fails
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
412 * @retval zero success
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
413 * @retval non-zero value on memory allocation failure
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
414 * @see cxMapEmplace()
1341
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
415 */
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
416 cx_attr_nonnull
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
417 CX_EXPORT void *cx_map_emplace(CxMap *map, CxHashKey key);
1341
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
418
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
419 /**
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
420 * Allocates memory for a value in the map associated with the specified key.
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
421 *
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
422 * A possible existing value will be overwritten.
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
423 * If destructor functions are specified, they are called for
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
424 * the overwritten element.
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
425 *
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
426 * If the map is storing pointers, this function returns a @c void** pointer,
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
427 * meaning a pointer to that pointer.
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
428 *
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
429 * The @p key is always copied.
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
430 *
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
431 * @param map (@c CxMap*) the map
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
432 * @param key (any supported key type) the key
1341
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
433 * @return the pointer to the allocated memory or @c NULL if allocation fails
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
434 * @retval zero success
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
435 * @retval non-zero value on memory allocation failure
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
436 * @see CX_HASH_KEY()
1341
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
437 */
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
438 #define cxMapEmplace(map, key) cx_map_emplace(map, CX_HASH_KEY(key))
1341
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
439
dc88d2ece7e4 add cxMapEmplace()
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
440 /**
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
441 * Retrieves a value by using a key.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
442 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
443 * If this map is storing pointers, the stored pointer is returned.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
444 * Otherwise, a pointer to the element within the map's memory
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
445 * is returned (which is valid as long as the element stays in the map).
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
446 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
447 * @param map the map
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
448 * @param key the key
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
449 * @return the value
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
450 * @see cxMapGet()
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
451 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
452 cx_attr_nonnull cx_attr_nodiscard
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
453 CX_EXPORT void *cx_map_get(const CxMap *map, CxHashKey key);
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
454
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
455 /**
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
456 * Retrieves a value by using a key.
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
457 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
458 * If this map is storing pointers, the stored pointer is returned.
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
459 * Otherwise, a pointer to the element within the map's memory
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
460 * is returned (which is valid as long as the element stays in the map).
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
461 *
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
462 * @param map (@c CxMap*) the map
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
463 * @param key (any supported key type) the key
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
464 * @return (@c void*) the value
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
465 * @see CX_HASH_KEY()
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
466 */
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
467 #define cxMapGet(map, key) cx_map_get(map, CX_HASH_KEY(key))
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
468
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
469 /**
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
470 * Removes a key/value-pair from the map by using the key.
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
471 *
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1411
diff changeset
472 * Invokes the destructor functions, if any, on the removed element if and only if the
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
473 * @p targetbuf is @c NULL.
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
474 *
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
475 * @param map the map
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
476 * @param key the key
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
477 * @param targetbuf the optional buffer where the removed element shall be copied to
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
478 * @retval zero success
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
479 * @retval non-zero the key was not found
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
480 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
481 * @see cxMapRemove()
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
482 * @see cxMapRemoveAndGet()
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
483 */
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
484 cx_attr_nonnull_arg(1)
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
485 CX_EXPORT int cx_map_remove(CxMap *map, CxHashKey key, void *targetbuf);
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
486
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
487 /**
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
488 * Removes a key/value-pair from the map by using the key.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
489 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
490 * Always invokes the destructor functions, if any, on the removed element.
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
491 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
492 * @param map (@c CxMap*) the map
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
493 * @param key (any supported key type) the key
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
494 * @retval zero success
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
495 * @retval non-zero the key was not found
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
496 *
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
497 * @see cxMapRemoveAndGet()
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
498 * @see CX_HASH_KEY()
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
499 */
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
500 #define cxMapRemove(map, key) cx_map_remove(map, CX_HASH_KEY(key), NULL)
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
501
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
502 /**
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
503 * Removes a key/value-pair from the map by using the key.
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
504 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
505 * This function will copy the contents of the removed element
1114
ad5eeb256242 fix that overwriting a map element did not call any destructor function
Mike Becker <universe@uap-core.de>
parents: 1111
diff changeset
506 * to the target buffer, which must be guaranteed to be large enough
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
507 * to hold the element (the map's element size).
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
508 * The destructor functions, if any, will @em not be called.
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
509 *
994
3603bdf4a78b remove map detach function - fixes #487
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
510 * If this map is storing pointers, the element is the pointer itself
3603bdf4a78b remove map detach function - fixes #487
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
511 * and not the object it points to.
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
512 *
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
513 * @param map (@c CxMap*) the map
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
514 * @param key (any supported key type) the key
1102
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
515 * @param targetbuf (@c void*) the buffer where the element shall be copied to
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
516 * @retval zero success
db5e355e5349 refine docs for map.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 994
diff changeset
517 * @retval non-zero the key was not found
1111
78eeeb950883 remove API for changing the store_pointer property after list creation
Mike Becker <universe@uap-core.de>
parents: 1109
diff changeset
518 *
994
3603bdf4a78b remove map detach function - fixes #487
Mike Becker <universe@uap-core.de>
parents: 993
diff changeset
519 * @see cxMapRemove()
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
520 * @see CX_HASH_KEY()
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
521 */
1408
aaa440cd4125 change map.h to use new CX_HASH_KEY macro
Mike Becker <universe@uap-core.de>
parents: 1344
diff changeset
522 #define cxMapRemoveAndGet(map, key, targetbuf) cx_map_remove(map, CX_HASH_KEY(key), targetbuf)
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
523
1411
838796848e12 fixes regression: missing closing brace in map.h in c++ builds
Mike Becker <universe@uap-core.de>
parents: 1408
diff changeset
524 #ifdef __cplusplus
838796848e12 fixes regression: missing closing brace in map.h in c++ builds
Mike Becker <universe@uap-core.de>
parents: 1408
diff changeset
525 } // extern "C"
838796848e12 fixes regression: missing closing brace in map.h in c++ builds
Mike Becker <universe@uap-core.de>
parents: 1408
diff changeset
526 #endif
838796848e12 fixes regression: missing closing brace in map.h in c++ builds
Mike Becker <universe@uap-core.de>
parents: 1408
diff changeset
527
691
65baf7f45ac8 bring a generic interface to CxMap
Mike Becker <universe@uap-core.de>
parents: 689
diff changeset
528 #endif // UCX_MAP_H

mercurial