docs/Writerside/topics/map.h.md

# Map Interface

Similar to the list interface, the map interface provides a common API for implementing maps.

UCX is shipped with a [hash map](hash_map.h.md) implementation of this interface. 

```C
#include <cx/hash_map.h>

CxMap *cxHashMapCreate(const CxAllocator *allocator,
        size_t itemsize, size_t buckets);

CxMap *cxHashMapCreateSimple(size_t itemsize);
```

The function `cxHashMapCreate()` creates a new [map](map.h.md) where both the map structure
and the contained buckets are allocated by the specified `allocator`.
The default stdlib allocator is used in `cxHashMapCreateSimple()`.

The map will store items of size `itemsize`.
You can use the `CX_STORE_POINTERS` macro for `itemsize` to indicate that the map shall store
pointers instead of actual items.

If you pass zero for the number of `buckets`, or use `cxHashMapSimple()`,
the map is initialized with a default of 16 buckets, otherwise the specified number of buckets is allocated.

> If you want to lazy-initialize maps, you can use the global `cxEmptyMap` symbol as a placeholder instead of using a `NULL`-pointer.
> While you *must not* insert elements into that map, you can safely access this map or create iterators.
> This allows you to write clean code without checking for `NULL`-pointer everywhere.
> You still need to make sure that the placeholder is replaced with an actual map before inserting elements.

## Overview

<warning>
TODO: write example
</warning>

## Insert

```C
#include <cx/map.h>

int cxMapPut(CxMap *map, KeyType key, void *value);
```

<warning>
TODO: document
</warning>

## Access

```C
#include <cx/map.h>

void *cxMapGet(CxMap *map, KeyType key);

size_t cxMapSize(const CxMap *map);
```

<warning>
TODO: document
</warning>

## Remove

```C
#include <cx/map.h>

int cxMapRemove(CxMap *map, KeyType key);

int cxMapRemoveAndGet(CxMap *map, KeyType key, void* targetbuf);

void cxMapClear(CxMap *map);
```

<warning>
TODO: document
</warning>

## Iterators

```C
#include <cx/map.h>

CxMapIterator cxMapIteratorValues(const CxMap *map);

CxMapIterator cxMapIteratorKeys(const CxMap *map);

CxMapIterator cxMapIteratorValues(const CxMap *map);

CxMapIterator cxMapMutIteratorValues(CxMap *map);

CxMapIterator cxMapMutIteratorKeys(CxMap *map);

CxMapIterator cxMapMutIteratorValues(CxMap *map);
```

<warning>
TODO: document
</warning>

## Dispose

```C
#include <cx/map.h>

void cxMapFree(CxMap *map);
```

<warning>
TODO: document
</warning>

## Implement own Map Structures 

```C
typedef struct cx_map_entry_s {
    const CxHashKey *key;
    void *value;
} CxMapEntry;
```

<warning>
TODO: document
</warning>


<seealso>
<category ref="apidoc">
<a href="https://ucx.sourceforge.io/api/map_8h.html">map.h</a>
</category>
</seealso>