Mercurial > hg > ucx / file comparison

comparison: src/cx/map.h

src/cx/map.h

changeset 1115
6db21dee4929
parent 1114
ad5eeb256242
equal deleted inserted replaced
1114:ad5eeb256242 1115:6db21dee4929
49 typedef struct cx_map_s CxMap; 49 typedef struct cx_map_s CxMap;
50 50
51 /** Type for a map entry. */ 51 /** Type for a map entry. */
52 typedef struct cx_map_entry_s CxMapEntry; 52 typedef struct cx_map_entry_s CxMapEntry;
53 53
54 /** Type for a map iterator. */
55 typedef struct cx_map_iterator_s CxMapIterator;
56
54 /** Type for map class definitions. */ 57 /** Type for map class definitions. */
55 typedef struct cx_map_class_s cx_map_class; 58 typedef struct cx_map_class_s cx_map_class;
56 59
57 /** Structure for the UCX map. */ 60 /** Structure for the UCX map. */
58 struct cx_map_s { 61 struct cx_map_s {
63 /** The map class definition. */ 66 /** The map class definition. */
64 cx_map_class *cl; 67 cx_map_class *cl;
65 }; 68 };
66 69
67 /** 70 /**
71 * A map entry.
72 */
73 struct cx_map_entry_s {
74 /**
75 * A pointer to the key.
76 */
77 const CxHashKey *key;
78 /**
79 * A pointer to the value.
80 */
81 void *value;
82 };
83
84 /**
68 * The type of iterator for a map. 85 * The type of iterator for a map.
69 */ 86 */
70 enum cx_map_iterator_type { 87 enum cx_map_iterator_type {
71 /** 88 /**
72 * Iterates over key/value pairs. 89 * Iterates over key/value pairs.
78 CX_MAP_ITERATOR_KEYS, 95 CX_MAP_ITERATOR_KEYS,
79 /** 96 /**
80 * Iterates over values only. 97 * Iterates over values only.
81 */ 98 */
82 CX_MAP_ITERATOR_VALUES 99 CX_MAP_ITERATOR_VALUES
100 };
101
102 /**
103 * Internal iterator struct - use CxMapIterator.
104 */
105 struct cx_map_iterator_s {
106 /**
107 * Inherited common data for all iterators.
108 */
109 CX_ITERATOR_BASE;
110
111 /**
112 * Handle for the source map.
113 */
114 union {
115 /**
116 * Access for mutating iterators.
117 */
118 CxMap *m;
119 /**
120 * Access for normal iterators.
121 */
122 const CxMap *c;
123 } map;
124
125 /**
126 * Handle for the current element.
127 *
128 * @attention Depends on the map implementation, do not assume a type (better: do not use!).
129 */
130 void *elem;
131
132 /**
133 * Reserved memory for a map entry.
134 *
135 * If a map implementation uses an incompatible layout, the iterator needs something
136 * to point to during iteration which @em is compatible.
137 */
138 CxMapEntry entry;
139
140 /**
141 * Field for storing the current slot number.
142 *
143 * (Used internally)
144 */
145 size_t slot;
146
147 /**
148 * Counts the elements successfully.
149 * It usually does not denote a stable index within the map as it would be for arrays.
150 */
151 size_t index;
152
153 /**
154 * The size of a value stored in this map.
155 */
156 size_t elem_size;
157
158 /**
159 * May contain the total number of elements, if known.
160 * Set to @c SIZE_MAX when the total number is unknown during iteration.
161 *
162 * @remark The UCX implementations of #CxMap always know the number of elements they store.
163 */
164 size_t elem_count;
165
166 /**
167 * The type of this iterator.
168 */
169 enum cx_map_iterator_type type;
83 }; 170 };
84 171
85 /** 172 /**
86 * The class definition for arbitrary maps. 173 * The class definition for arbitrary maps.
87 */ 174 */
130 ); 217 );
131 218
132 /** 219 /**
133 * Creates an iterator for this map. 220 * Creates an iterator for this map.
134 */ 221 */
135 CxIterator (*iterator)(const CxMap *map, enum cx_map_iterator_type type); 222 CxMapIterator (*iterator)(const CxMap *map, enum cx_map_iterator_type type);
136 };
137
138 /**
139 * A map entry.
140 */
141 struct cx_map_entry_s {
142 /**
143 * A pointer to the key.
144 */
145 const CxHashKey *key;
146 /**
147 * A pointer to the value.
148 */
149 void *value;
150 }; 223 };
151 224
152 /** 225 /**
153 * A shared instance of an empty map. 226 * A shared instance of an empty map.
154 * 227 *
193 } 266 }
194 267
195 /** 268 /**
196 * Creates a value iterator for a map. 269 * Creates a value iterator for a map.
197 * 270 *
271 * When the map is storing pointers, those pointers are returned.
272 * Otherwise, the iterator iterates over pointers to the memory within the map where the
273 * respective elements are stored.
274 *
198 * @note An iterator iterates over all elements successively. Therefore, the order 275 * @note An iterator iterates over all elements successively. Therefore, the order
199 * highly depends on the map implementation and may change arbitrarily when the contents change. 276 * highly depends on the map implementation and may change arbitrarily when the contents change.
200 * 277 *
201 * @param map the map to create the iterator for 278 * @param map the map to create the iterator for
202 * @return an iterator for the currently stored values 279 * @return an iterator for the currently stored values
203 */ 280 */
204 cx_attr_nonnull 281 cx_attr_nonnull
205 cx_attr_nodiscard 282 cx_attr_nodiscard
206 static inline CxIterator cxMapIteratorValues(const CxMap *map) { 283 static inline CxMapIterator cxMapIteratorValues(const CxMap *map) {
207 return map->cl->iterator(map, CX_MAP_ITERATOR_VALUES); 284 return map->cl->iterator(map, CX_MAP_ITERATOR_VALUES);
208 } 285 }
209 286
210 /** 287 /**
211 * Creates a key iterator for a map. 288 * Creates a key iterator for a map.
212 * 289 *
213 * The elements of the iterator are keys of type CxHashKey. 290 * The elements of the iterator are keys of type CxHashKey and the pointer returned
291 * during iterator shall be treated as @c const @c CxHashKey* .
214 * 292 *
215 * @note An iterator iterates over all elements successively. Therefore, the order 293 * @note An iterator iterates over all elements successively. Therefore, the order
216 * highly depends on the map implementation and may change arbitrarily when the contents change. 294 * highly depends on the map implementation and may change arbitrarily when the contents change.
217 * 295 *
218 * @param map the map to create the iterator for 296 * @param map the map to create the iterator for
219 * @return an iterator for the currently stored keys 297 * @return an iterator for the currently stored keys
220 */ 298 */
221 cx_attr_nonnull 299 cx_attr_nonnull
222 cx_attr_nodiscard 300 cx_attr_nodiscard
223 static inline CxIterator cxMapIteratorKeys(const CxMap *map) { 301 static inline CxMapIterator cxMapIteratorKeys(const CxMap *map) {
224 return map->cl->iterator(map, CX_MAP_ITERATOR_KEYS); 302 return map->cl->iterator(map, CX_MAP_ITERATOR_KEYS);
225 } 303 }
226 304
227 /** 305 /**
228 * Creates an iterator for a map. 306 * Creates an iterator for a map.
229 * 307 *
230 * The elements of the iterator are key/value pairs of type CxMapEntry. 308 * The elements of the iterator are key/value pairs of type CxMapEntry and the pointer returned
309 * during iterator shall be treated as @c const @c CxMapEntry* .
231 * 310 *
232 * @note An iterator iterates over all elements successively. Therefore, the order 311 * @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. 312 * highly depends on the map implementation and may change arbitrarily when the contents change.
234 * 313 *
235 * @param map the map to create the iterator for 314 * @param map the map to create the iterator for
237 * @see cxMapIteratorKeys() 316 * @see cxMapIteratorKeys()
238 * @see cxMapIteratorValues() 317 * @see cxMapIteratorValues()
239 */ 318 */
240 cx_attr_nonnull 319 cx_attr_nonnull
241 cx_attr_nodiscard 320 cx_attr_nodiscard
242 static inline CxIterator cxMapIterator(const CxMap *map) { 321 static inline CxMapIterator cxMapIterator(const CxMap *map) {
243 return map->cl->iterator(map, CX_MAP_ITERATOR_PAIRS); 322 return map->cl->iterator(map, CX_MAP_ITERATOR_PAIRS);
244 } 323 }
245 324
246 325
247 /** 326 /**
248 * Creates a mutating iterator over the values of a map. 327 * Creates a mutating iterator over the values of a map.
328 *
329 * When the map is storing pointers, those pointers are returned.
330 * Otherwise, the iterator iterates over pointers to the memory within the map where the
331 * respective elements are stored.
249 * 332 *
250 * @note An iterator iterates over all elements successively. Therefore, the order 333 * @note An iterator iterates over all elements successively. Therefore, the order
251 * highly depends on the map implementation and may change arbitrarily when the contents change. 334 * highly depends on the map implementation and may change arbitrarily when the contents change.
252 * 335 *
253 * @param map the map to create the iterator for 336 * @param map the map to create the iterator for
254 * @return an iterator for the currently stored values 337 * @return an iterator for the currently stored values
255 */ 338 */
256 cx_attr_nonnull 339 cx_attr_nonnull
257 cx_attr_nodiscard 340 cx_attr_nodiscard
258 CxIterator cxMapMutIteratorValues(CxMap *map); 341 CxMapIterator cxMapMutIteratorValues(CxMap *map);
259 342
260 /** 343 /**
261 * Creates a mutating iterator over the keys of a map. 344 * Creates a mutating iterator over the keys of a map.
262 * 345 *
263 * The elements of the iterator are keys of type CxHashKey. 346 * The elements of the iterator are keys of type CxHashKey and the pointer returned
347 * during iterator shall be treated as @c const @c CxHashKey* .
264 * 348 *
265 * @note An iterator iterates over all elements successively. Therefore, the order 349 * @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. 350 * highly depends on the map implementation and may change arbitrarily when the contents change.
267 * 351 *
268 * @param map the map to create the iterator for 352 * @param map the map to create the iterator for
269 * @return an iterator for the currently stored keys 353 * @return an iterator for the currently stored keys
270 */ 354 */
271 cx_attr_nonnull 355 cx_attr_nonnull
272 cx_attr_nodiscard 356 cx_attr_nodiscard
273 CxIterator cxMapMutIteratorKeys(CxMap *map); 357 CxMapIterator cxMapMutIteratorKeys(CxMap *map);
274 358
275 /** 359 /**
276 * Creates a mutating iterator for a map. 360 * Creates a mutating iterator for a map.
277 * 361 *
278 * The elements of the iterator are key/value pairs of type CxMapEntry. 362 * The elements of the iterator are key/value pairs of type CxMapEntry and the pointer returned
363 * during iterator shall be treated as @c const @c CxMapEntry* .
279 * 364 *
280 * @note An iterator iterates over all elements successively. Therefore, the order 365 * @note An iterator iterates over all elements successively. Therefore, the order
281 * highly depends on the map implementation and may change arbitrarily when the contents change. 366 * highly depends on the map implementation and may change arbitrarily when the contents change.
282 * 367 *
283 * @param map the map to create the iterator for 368 * @param map the map to create the iterator for
285 * @see cxMapMutIteratorKeys() 370 * @see cxMapMutIteratorKeys()
286 * @see cxMapMutIteratorValues() 371 * @see cxMapMutIteratorValues()
287 */ 372 */
288 cx_attr_nonnull 373 cx_attr_nonnull
289 cx_attr_nodiscard 374 cx_attr_nodiscard
290 CxIterator cxMapMutIterator(CxMap *map); 375 CxMapIterator cxMapMutIterator(CxMap *map);
291 376
292 #ifdef __cplusplus 377 #ifdef __cplusplus
293 } // end the extern "C" block here, because we want to start overloading 378 } // end the extern "C" block here, because we want to start overloading
294 cx_attr_nonnull 379 cx_attr_nonnull
295 static inline int cxMapPut( 380 static inline int cxMapPut(

Mercurial Repository: ucx

mercurial