Mercurial > hg > ucx / file comparison

comparison: docs/Writerside/topics/map.h.md

docs/Writerside/topics/map.h.md

changeset 1243
13e15cd529ae
parent 1190
a7b913d5d589
equal deleted inserted replaced
1242:bbb734f73392 1243:13e15cd529ae
1 # Map Interface 1 # Map Interface
2 2
3 Similar to the list interface, the map interface provides a common API for implementing maps.
4
5 UCX is shipped with a [hash map](hash_map.h.md) implementation of this interface.
6
7 ```C
8 #include <cx/hash_map.h>
9
10 CxMap *cxHashMapCreate(const CxAllocator *allocator,
11 size_t itemsize, size_t buckets);
12
13 CxMap *cxHashMapCreateSimple(size_t itemsize);
14 ```
15
16 The function `cxHashMapCreate()` creates a new [map](map.h.md) where both the map structure
17 and the contained buckets are allocated by the specified `allocator`.
18 The default stdlib allocator is used in `cxHashMapCreateSimple()`.
19
20 The map will store items of size `itemsize`.
21 You can use the `CX_STORE_POINTERS` macro for `itemsize` to indicate that the map shall store
22 pointers instead of actual items.
23
24 If you pass zero for the number of `buckets`, or use `cxHashMapSimple()`,
25 the map is initialized with a default of 16 buckets, otherwise the specified number of buckets is allocated.
26
27 > If you want to lazy-initialize maps, you can use the global `cxEmptyMap` symbol as a placeholder instead of using a `NULL`-pointer.
28 > While you *must not* insert elements into that map, you can safely access this map or create iterators.
29 > This allows you to write clean code without checking for `NULL`-pointer everywhere.
30 > You still need to make sure that the placeholder is replaced with an actual map before inserting elements.
31
32 ## Overview
33
3 <warning> 34 <warning>
4 Outdated Section - will be updated soon! 35 TODO: write example
5 </warning> 36 </warning>
6 37
7 Similar to the list interface, the map interface provides a common API for implementing maps. 38 ## Insert
8 There are some minor subtle differences, though.
9 39
10 First, the `remove` method is not always a destructive removal. 40 ```C
11 Instead, the last argument is a Boolean that indicates whether the element shall be destroyed or returned. 41 #include <cx/map.h>
12 ```c 42
13 void *(*remove)(CxMap *map, CxHashKey key, bool destroy); 43 int cxMapPut(CxMap *map, KeyType key, void *value);
14 ``` 44 ```
15 When you implement this method, you are either supposed to invoke the destructors and return `NULL`,
16 or just remove the element from the map and return it.
17 45
18 Secondly, the iterator method is a bit more complete. The signature is as follows: 46 <warning>
19 ```c 47 TODO: document
20 CxIterator (*iterator)(const CxMap *map, enum cx_map_iterator_type type); 48 </warning>
49
50 ## Access
51
52 ```C
53 #include <cx/map.h>
54
55 void *cxMapGet(CxMap *map, KeyType key);
56
57 size_t cxMapSize(const CxMap *map);
21 ``` 58 ```
22 There are three map iterator types: for values, for keys, for pairs.
23 Depending on the iterator type requested, you need to create an iterator with the correct methods that
24 return the requested thing.
25 There are no automatic checks to enforce this - it's completely up to you.
26 If you need inspiration on how to do that, check the hash map implementation that comes with UCX.
27 59
28 <!-- 60 <warning>
29 ## Undocumented Symbols (TODO) 61 TODO: document
30 ### cx_empty_map 62 </warning>
31 ### cxEmptyMap 63
32 ### cxMapFree 64 ## Remove
33 ### cxMapMutIterator 65
34 ### cxMapMutIteratorKeys 66 ```C
35 ### cxMapMutIteratorValues 67 #include <cx/map.h>
36 --> 68
69 int cxMapRemove(CxMap *map, KeyType key);
70
71 int cxMapRemoveAndGet(CxMap *map, KeyType key, void* targetbuf);
72
73 void cxMapClear(CxMap *map);
74 ```
75
76 <warning>
77 TODO: document
78 </warning>
79
80 ## Iterators
81
82 ```C
83 #include <cx/map.h>
84
85 CxMapIterator cxMapIteratorValues(const CxMap *map);
86
87 CxMapIterator cxMapIteratorKeys(const CxMap *map);
88
89 CxMapIterator cxMapIteratorValues(const CxMap *map);
90
91 CxMapIterator cxMapMutIteratorValues(CxMap *map);
92
93 CxMapIterator cxMapMutIteratorKeys(CxMap *map);
94
95 CxMapIterator cxMapMutIteratorValues(CxMap *map);
96 ```
97
98 <warning>
99 TODO: document
100 </warning>
101
102 ## Dispose
103
104 ```C
105 #include <cx/map.h>
106
107 void cxMapFree(CxMap *map);
108 ```
109
110 <warning>
111 TODO: document
112 </warning>
113
114 ## Implement own Map Structures
115
116 ```C
117 typedef struct cx_map_entry_s {
118 const CxHashKey *key;
119 void *value;
120 } CxMapEntry;
121 ```
122
123 <warning>
124 TODO: document
125 </warning>
126
37 127
38 <seealso> 128 <seealso>
39 <category ref="apidoc"> 129 <category ref="apidoc">
40 <a href="https://ucx.sourceforge.io/api/map_8h.html">map.h</a> 130 <a href="https://ucx.sourceforge.io/api/map_8h.html">map.h</a>
41 </category> 131 </category>

Mercurial Repository: ucx

mercurial