docs/Writerside/topics/kv_list.h.md

# Key/Value List

The key/value list is a linked list of key/value pairs.
It implements both the `CxList` and `CxMap` interfaces.

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

CxList *cxKvListCreate(const CxAllocator *allocator,
        cx_compare_func comparator, size_t elem_size);
        
CxList *cxKvListCreateSimple(size_t elem_size);

CxMap *cxKvListCreateAsMap(const CxAllocator *allocator,
        cx_compare_func comparator, size_t elem_size);
        
CxMap *cxKvListCreateAsMapSimple(size_t elem_size);
```

The lists are created as usual linked lists with an additional map to look up items by key.
The map is created with the same allocator as the list.
You can use either interface to access the list.
Also, defining destructors on either interface will work as if you defined them on the list.
Using the list interface to insert items will insert them without an assigned key,
but you can always set a key later using the `cxKvListSetKey()` function (see [](#special-functions) below).

> The special thing about key/value lists when used with the map interface is,
> that when you iterate over the map, the elements are returned in the order they appear in the list.
> In contrast, a normal hash map will return the elements in arbitrary order.
> This way you can use a key/value list as an ordered map.
> {style="note"}

## Converting between the Interfaces

To easily convert between the `CxList` and `CxMap` interfaces, we provide the following functions.

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

CxMap *cxKvListAsMap(CxList *list);

CxList *cxKvListAsList(CxMap *map);
```

They must only be used on lists that have been created as key/value lists.
Using them with other lists will result in undefined behavior.

## Special Functions

The key/value list has some special functions that are not part of the `CxList` or `CxMap` interface.
They also may only be used with lists that have been created as key/value lists.
Using them with other lists will result in undefined behavior.

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

int cxKvListSetKey(CxList *list, size_t index, KeyType key);

int cxKvListRemoveKey(CxList *list, size_t index);

const CxHashKey *cxKvListGetKey(CxList *list, size_t index);

int cxKvListAdd(CxList *list, KeyType key, void *value);

int cxKvListInsert(CxList *list, size_t index,
        KeyType key, void *value);
```

> All functions working with keys are implemented as generics, so that the following types are supported:
> `CxHashKey`, `cxstring`, `cxmutstr`, `const char*`, and `char*`.
> When we write `KeyType`, we mean any of these types.
> {style="note"}

The `cxKvListSetKey()` and `cxKvListRemoveKey()` functions are used to set or remove the key of an element.
They return zero on success and non-zero on failure.
A failure can happen when the index is out of bounds or when a memory allocation failed.
The `cxKvListSetKey()` function also returns non-zero if the key already exists for _another_ element.
With `cxKvListGetKey()`, you can retrieve the key of an element.
This function returns `NULL` when an element has no key assigned or the index is out of bounds.

With the `cxKvListAdd()` and `cxKvListInsert()` functions, you can add a new element to the list and immediately assign a key to it.
The `cxKvListAdd()` function will add the element at the end of the list,
while the `cxKvListInsert()` function will insert the element at the specified index.

> The effect of `cxKvListAdd()` using the list interface and `cxMapPut()` using the map interface is the same.