comparison: docs/Writerside/topics/map.h.md
docs/Writerside/topics/map.h.md
- changeset 1489
- 185dc2a4b45c
- parent 1479
- ac1baaed2fd7
equal
deleted
inserted
replaced
| 1488:946895d19dde | 1489:185dc2a4b45c |
|---|---|
| 195 int cxMapPut(CxMap *map, KeyType key, void *value); | 195 int cxMapPut(CxMap *map, KeyType key, void *value); |
| 196 | 196 |
| 197 void *cxMapEmplace(CxMap *map, KeyType key); | 197 void *cxMapEmplace(CxMap *map, KeyType key); |
| 198 ``` | 198 ``` |
| 199 | 199 |
| 200 The function `cxMapPut()` stores the specified `key` / `value` pair, | 200 The function `cxMapPut()` stores the specified `key` / `value` pair |
| 201 and returns zero if the element was successfully put into the map and non-zero otherwise. | 201 and returns zero if the element was successfully put into the map and non-zero otherwise. |
| 202 | 202 |
| 203 The key is always copied. | 203 The key is always copied. |
| 204 The behavior for the value is dependent on whether the map is storing pointers. | 204 The behavior for the value is dependent on whether the map is storing pointers. |
| 205 If it is storing pointers, the `value` pointer is directly stored in the map. | 205 If it is storing pointers, the `value` pointer is directly stored in the map. |
| 248 ``` | 248 ``` |
| 249 | 249 |
| 250 The function `cxMapRemove()` retrieves and removes a value stored under the specified `key`. | 250 The function `cxMapRemove()` retrieves and removes a value stored under the specified `key`. |
| 251 If [destructor functions](collection.h.md#destructor-functions) are registered, they are called before removal. | 251 If [destructor functions](collection.h.md#destructor-functions) are registered, they are called before removal. |
| 252 | 252 |
| 253 On the other hand, `cxMapRemoveAndGet()` does not invoke the destructor functions, | 253 On the other hand, `cxMapRemoveAndGet()` does not invoke the destructor functions |
| 254 and instead copies the value into the `targetbuf` which must be sufficiently large to hold the value. | 254 and instead copies the value into the `targetbuf`, which must be large enough to hold the value. |
| 255 | 255 |
| 256 In either case, the functions return zero when an element was found under the specified key, and non-zero otherwise. | 256 In either case, the functions return zero when an element was found under the specified key, and non-zero otherwise. |
| 257 | 257 |
| 258 The function `cxMapClear()` removes all elements from the map, invoking the destructor functions for each of them. | 258 The function `cxMapClear()` removes all elements from the map, invoking the destructor functions for each of them. |
| 259 | 259 |
| 270 ``` | 270 ``` |
| 271 | 271 |
| 272 The above functions create iterators over the | 272 The above functions create iterators over the |
| 273 pairs, keys, or values of the specified `map`, respectively. | 273 pairs, keys, or values of the specified `map`, respectively. |
| 274 | 274 |
| 275 Iterators over pairs yield elements of type `CxMapEntry*` which is a struct containing a pointer to the `key` and the value, respectively. | 275 Iterators over pairs yield elements of the type `CxMapEntry*` which is a struct containing a pointer to the `key` and the value, respectively. |
| 276 | 276 |
| 277 Iterators over keys yield elements of type `const CxHashKey*` (cf. [CxHashKey documentation](hash_key.h.md)). | 277 Iterators over keys yield elements of the type `const CxHashKey*` (cf. [CxHashKey documentation](hash_key.h.md)). |
| 278 | 278 |
| 279 The behavior of iterators over values depends on the concrete implementation. | 279 The behavior of iterators over values depends on the concrete implementation. |
| 280 Implementations are encouraged to support `CX_STORE_POINTERS`. | 280 Implementations are encouraged to support `CX_STORE_POINTERS`. |
| 281 If used, the `void*` elements the iterator yields, shall be directly the stored pointers. | 281 If used, the `void*` elements the iterator yields shall be directly the stored pointers. |
| 282 Otherwise, the iterator shall yield pointers to the map's memory where the value is stored. | 282 Otherwise, the iterator shall yield pointers to the map's memory where the value is stored. |
| 283 | 283 |
| 284 It is always safe to call the above functions on a `NULL`-pointer. | 284 It is always safe to call the above functions on a `NULL`-pointer. |
| 285 In that case, the returned iterator will behave like an iterator over an empty map. | 285 In that case, the returned iterator will behave like an iterator over an empty map. |
| 286 | 286 |
| 354 | 354 |
| 355 The functions `cxMapDifference()` and `cxMapListDifference()` are similar to `cxMapClone()` | 355 The functions `cxMapDifference()` and `cxMapListDifference()` are similar to `cxMapClone()` |
| 356 except that they only clone an element from the source map, when the key is _not_ contained in the | 356 except that they only clone an element from the source map, when the key is _not_ contained in the |
| 357 other map (or list, respectively). | 357 other map (or list, respectively). |
| 358 This is equivalent to computing the set difference for the set of keys. | 358 This is equivalent to computing the set difference for the set of keys. |
| 359 Likewise, `cxMapIntersection()` and `cxMapListIntersection()` only clone an element from the source map, | 359 Likewise, `cxMapIntersection()` and `cxMapListIntersection()` only clone an element from the source map |
| 360 when the key is contained in _both_ collections. | 360 when the key is contained in _both_ collections. |
| 361 The function `cxMapUnion()` only clones elements from `src` to `dst` when their key is not present in `dst`. | 361 The function `cxMapUnion()` only clones elements from `src` to `dst` when their key is not present in `dst`. |
| 362 | 362 |
| 363 > The function `cxMapUnion()` does not operate on three maps for the sake of simplicity. | 363 > The function `cxMapUnion()` does not operate on three maps for the sake of simplicity. |
| 364 > If you want to combine two maps without modifying either of them, you can first use `cxMapClone()` | 364 > If you want to combine two maps without modifying either of them, you can first use `cxMapClone()` |
| 386 #include <cx/map.h> | 386 #include <cx/map.h> |
| 387 | 387 |
| 388 void cxMapFree(CxMap *map); | 388 void cxMapFree(CxMap *map); |
| 389 ``` | 389 ``` |
| 390 | 390 |
| 391 The function `cxMapFree()` invokes the [destructor functions](collection.h.md#destructor-functions) for all elements, | 391 The function `cxMapFree()` invokes the [destructor functions](collection.h.md#destructor-functions) for all elements |
| 392 and then deallocates the entire memory for the map. | 392 and then deallocates the entire memory for the map. |
| 393 | 393 |
| 394 ## Implement own Map Structures | 394 ## Implement own Map Structures |
| 395 | 395 |
| 396 If the UCX [hash map](hash_map.h.md) implementation does not suit your needs, | 396 If the UCX [hash map](hash_map.h.md) implementation does not suit your needs, |
| 402 const CxHashKey *key; | 402 const CxHashKey *key; |
| 403 void *value; | 403 void *value; |
| 404 } CxMapEntry; | 404 } CxMapEntry; |
| 405 ``` | 405 ``` |
| 406 | 406 |
| 407 When you are declaring your map structure, a `CxMap` member must be embedded as first member of this structure. | 407 When you are declaring your map structure, a `CxMap` member must be embedded as the first member of this structure. |
| 408 Secondly, you need to implement the `cx_map_class` and assign it when allocating your map. | 408 Secondly, you need to implement the `cx_map_class` and assign it when allocating your map. |
| 409 | 409 |
| 410 ```C | 410 ```C |
| 411 #include <cx/map.h> | 411 #include <cx/map.h> |
| 412 | 412 |
