Key/Value List

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

#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).

Converting between the Interfaces

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

#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.

#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);

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.

25 September 2025