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](#implement-own-list-structures).

## Example

<warning>
TODO: add example how to work with lists
</warning>

> If you want to lazy-initialize lists, you can use the global `cxEmptyList` symbol as a placeholder instead of using a `NULL`-pointer.
> While you *must not* insert items into that list, you can safely access this list 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 list before inserting items.

## Insert

```C
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);
```

<warning>
TODO: add documentation
</warning>

## Access and Find

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

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

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

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

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

<warning>
TODO: add documentation
</warning>

## Remove

```C
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);
```

<warning>
TODO: add documentation
</warning>

## Iterators

```C
CxIterator cxListIterator(const CxList *list);

CxIterator cxListMutIterator(CxList *list);

CxIterator cxListBackwardsIterator(const CxList *list);

CxIterator cxListMutBackwardsIterator(CxList *list);

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

<warning>
TODO: add documentation
</warning>

## Reorder

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

void cxListSort(CxList *list);

void cxListReverse(CxList *list);
```

<warning>
TODO: add documentation
</warning>

## Compare

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

<warning>
TODO: add documentation
</warning>

## Dispose

```C
void cxListFree(CxList *list);
```

<warning>
TODO: add documentation
</warning>

## Implement own List Structures

<warning>
TODO: add documentation
</warning>

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