docs/Writerside/topics/list.h.md

# List Interface

<warning>
Outdated Section - will be updated soon!
</warning>

The `list.h` header defines a common interface for all list implementations.

UCX already comes with two common list implementations ([linked list](linked_list.h.md) and [array list](array_list.h.md))
that should cover most use cases.
But if you feel the need to implement an own list, you will find instructions [below](#implementing-own-list-structures).

## Overview

```C
size_t cxListSize(const CxList *list);

int cxListAdd(CxList *list, const void *elem);

size_t cxListAddArray(CxList *list, const void *array, size_t n);

int cxListInsert(CxList *list, size_t index, const void *elem);

int cxListInsertSorted(CxList *list, const void *elem);

size_t cxListInsertArray(CxList *list, size_t index,
        const void *array, size_t n);

size_t cxListInsertSortedArray(CxList *list,
        const void *array, size_t n);

int cxListInsertAfter(CxIterator *iter, const void *elem);

int cxListInsertBefore(CxIterator *iter, const void *elem);

int cxListRemove(CxList *list, size_t index);

int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf);

size_t cxListRemoveArray(CxList *list, size_t index, size_t num);

size_t cxListRemoveArrayAndGet(CxList *list, size_t index, size_t num,
        void *targetbuf);

void cxListClear(CxList *list);

int cxListSwap(CxList *list, size_t i, size_t j);

void *cxListAt(const CxList *list, size_t index);

CxIterator cxListIteratorAt(const CxList *list, size_t index);

CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index);

CxIterator cxListMutIteratorAt(CxList *list, size_t index);

CxIterator cxListMutBackwardsIteratorAt(CxList *list, size_t index);

CxIterator cxListIterator(const CxList *list);

CxIterator cxListMutIterator(CxList *list);

CxIterator cxListBackwardsIterator(const CxList *list);

CxIterator cxListMutBackwardsIterator(CxList *list);

size_t cxListFind(const CxList *list, const void *elem);

bool cxListIndexValid(const CxList *list, size_t index);

size_t cxListFindRemove(CxList *list, const void *elem);

void cxListSort(CxList *list);

void cxListReverse(CxList *list);

int cxListCompare(const CxList *list, const CxList *other);

void cxListFree(CxList *list);

extern CxList *const cxEmptyList;
```


## Implementing own List Structures

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