Mercurial > hg > ucx / file comparison

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

docs/Writerside/topics/map.h.md

changeset 1244
9a8e781258ac
parent 1243
13e15cd529ae
child 1245
721e2032fa25
equal deleted inserted replaced
1243:13e15cd529ae 1244:9a8e781258ac
11 size_t itemsize, size_t buckets); 11 size_t itemsize, size_t buckets);
12 12
13 CxMap *cxHashMapCreateSimple(size_t itemsize); 13 CxMap *cxHashMapCreateSimple(size_t itemsize);
14 ``` 14 ```
15 15
16 The function `cxHashMapCreate()` creates a new [map](map.h.md) where both the map structure 16 The function `cxHashMapCreate()` creates a new map where both the map structure
17 and the contained buckets are allocated by the specified `allocator`. 17 and the contained buckets are allocated by the specified `allocator`.
18 The default stdlib allocator is used in `cxHashMapCreateSimple()`. 18 The default stdlib allocator is used in `cxHashMapCreateSimple()`.
19 19
20 The map will store items of size `itemsize`. 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 21 You can use the `CX_STORE_POINTERS` macro for `itemsize` to indicate that the map shall store
30 > You still need to make sure that the placeholder is replaced with an actual map before inserting elements. 30 > You still need to make sure that the placeholder is replaced with an actual map before inserting elements.
31 31
32 ## Overview 32 ## Overview
33 33
34 <warning> 34 <warning>
35 TODO: write example 35 TODO: example
36 </warning> 36 </warning>
37
38 > In the following Sections, the type for the key is denoted `KeyType`.
39 > All functions are implemented as generics, so that the following types are supported:
40 > `CxHashKey`, `cxstring`, `cxmutstr`, `const char*`, and `char*`.
41 > {style="note"}
37 42
38 ## Insert 43 ## Insert
39 44
40 ```C 45 ```C
41 #include <cx/map.h> 46 #include <cx/map.h>
42 47
43 int cxMapPut(CxMap *map, KeyType key, void *value); 48 int cxMapPut(CxMap *map, KeyType key, void *value);
44 ``` 49 ```
45 50
46 <warning> 51 The function `cxMapPut()` stores the specified `key` / `value` pair.
47 TODO: document 52
48 </warning> 53 The key is always copied.
54 The behavior for the value is dependent on whether the map is storing pointers.
55 If it is storing pointers, the `value` pointer is directly stored in the map.
56 Otherwise, the memory pointed to by `value` is copied, using the element size of the collection.
57
58 If an element is already associated with the specified key, it is replaced.
59 If [destructor functions](collection.h.md#destructor-functions) are registered,
60 they are invoked for the old element before it is replaced.
61
62 This function returns zero if the element was successfully put into the map and non-zero otherwise.
49 63
50 ## Access 64 ## Access
51 65
52 ```C 66 ```C
53 #include <cx/map.h> 67 #include <cx/map.h>
55 void *cxMapGet(CxMap *map, KeyType key); 69 void *cxMapGet(CxMap *map, KeyType key);
56 70
57 size_t cxMapSize(const CxMap *map); 71 size_t cxMapSize(const CxMap *map);
58 ``` 72 ```
59 73
60 <warning> 74 With the function `cxMapGet()` you can retrieve a value stored under the specified `key`.
61 TODO: document 75 If there is no such value, this function returns `NULL`.
62 </warning> 76
77 The function `cxMapSize()` returns how many key/value-pairs are currently stored in the map.
63 78
64 ## Remove 79 ## Remove
65 80
66 ```C 81 ```C
67 #include <cx/map.h> 82 #include <cx/map.h>
71 int cxMapRemoveAndGet(CxMap *map, KeyType key, void* targetbuf); 86 int cxMapRemoveAndGet(CxMap *map, KeyType key, void* targetbuf);
72 87
73 void cxMapClear(CxMap *map); 88 void cxMapClear(CxMap *map);
74 ``` 89 ```
75 90
76 <warning> 91 The function `cxMapRemove()` retrieves and removes a value stored under the specified `key`.
77 TODO: document 92 If [destructor functions](collection.h.md#destructor-functions) are registered, they are called before removal.
78 </warning> 93
94 On the other hand, `cxMapRemoveAndGet()` does not invoke the destructor functions,
95 and instead copies the value into the `targetbuf` which must be sufficiently large to hold the value.
96
97 In either case, the functions return zero when an element was found under the specified key, and non-zero otherwise.
98
99 The function `cxMapClear()` removes all elements from the map, invoking the destructor functions for each of them.
79 100
80 ## Iterators 101 ## Iterators
81 102
82 ```C 103 ```C
83 #include <cx/map.h> 104 #include <cx/map.h>
84 105
85 CxMapIterator cxMapIteratorValues(const CxMap *map); 106 CxMapIterator cxMapIterator(const CxMap *map);
86 107
87 CxMapIterator cxMapIteratorKeys(const CxMap *map); 108 CxMapIterator cxMapIteratorKeys(const CxMap *map);
88 109
89 CxMapIterator cxMapIteratorValues(const CxMap *map); 110 CxMapIterator cxMapIteratorValues(const CxMap *map);
90 111
91 CxMapIterator cxMapMutIteratorValues(CxMap *map); 112 CxMapIterator cxMapMutIterator(CxMap *map);
92 113
93 CxMapIterator cxMapMutIteratorKeys(CxMap *map); 114 CxMapIterator cxMapMutIteratorKeys(CxMap *map);
94 115
95 CxMapIterator cxMapMutIteratorValues(CxMap *map); 116 CxMapIterator cxMapMutIteratorValues(CxMap *map);
96 ``` 117 ```
97 118
98 <warning> 119 The above functions create a ([mutating](iterator.h.md#mutating-iterators)) iterator over the
99 TODO: document 120 pairs, keys, or values of the specified `map`, respectively.
100 </warning> 121
122 Iterators over pairs yield elements of type `CxMapEntry*` which is a struct containing a pointer to the `key` and the value, respectively.
123
124 Iterators over keys yield elements of type `const CxHashKey*` (cf. [CxHashKey documentation](hash_key.h.md)).
125
126 The behavior of iterators over values depends on the concrete implementation.
127 Implementations are encouraged to support `CX_STORE_POINTERS`.
128 If used, the `void*` elements the iterator yields, shall be directly the stored pointers.
129 Otherwise, the iterator shall yield pointers to the map's memory where the value is stored.
101 130
102 ## Dispose 131 ## Dispose
103 132
104 ```C 133 ```C
105 #include <cx/map.h> 134 #include <cx/map.h>
106 135
107 void cxMapFree(CxMap *map); 136 void cxMapFree(CxMap *map);
108 ``` 137 ```
109 138
110 <warning> 139 The function `cxMapFree()` invokes the [destructor functions](collection.h.md#destructor-functions) for all elements,
111 TODO: document 140 and then deallocates the entire memory for the map.
112 </warning>
113 141
114 ## Implement own Map Structures 142 ## Implement own Map Structures
115 143
116 ```C 144 ```C
117 typedef struct cx_map_entry_s { 145 typedef struct cx_map_entry_s {
119 void *value; 147 void *value;
120 } CxMapEntry; 148 } CxMapEntry;
121 ``` 149 ```
122 150
123 <warning> 151 <warning>
124 TODO: document 152 TODO: example
125 </warning> 153 </warning>
126 154
155 The required behavior for the implementations is described in the following table.
156 You can always look at the source code of the UCX hash map to get inspiration.
157
158 | Function | Description |
159 |--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
160 | `clear` | Invoke [destructor functions](collection.h.md#destructor-functions) on all elements and remove them from the map. |
161 | `deallocate` | Invoke destructor functions on all elements and deallocate the entire map memory. |
162 | `put` | Store an element in the map. If an element is already stored, invoke the destructor functions on that element and replace it with the new element. Return non-zero when allocating memory fails. |
163 | `get` | Look up the specified key and return the associated value (or `NULL` if the key was not found). |
164 | `remove` | Remove an element from the map. If a target buffer is specified, copy the elements to that buffer. Otherwise, invoke the destructor functions for the element. If the key was not found in the map, return non-zero. |
165 | `iterator` | Return an iterator over the pairs, the keys, or the values, depending on the iterator type passed with the last argument. |
166
167 > In contrast to the list interface, there is no `cx_map_init()` function which automatically
168 > configures a wrapping mechanism when `CX_STORE_POINTERS` is used.
169 > That means, in the implementation of the above functions you must take care of distinguishing between
170 > maps that are storing pointers and that are storing elements yourself (if you want to support both).
171 >{style="note"}
127 172
128 <seealso> 173 <seealso>
129 <category ref="apidoc"> 174 <category ref="apidoc">
130 <a href="https://ucx.sourceforge.io/api/map_8h.html">map.h</a> 175 <a href="https://ucx.sourceforge.io/api/map_8h.html">map.h</a>
131 </category> 176 </category>

Mercurial Repository: ucx

mercurial