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

Arbitrary lists can be compared item-wise with `cxListCompare()`, as long as the compare functions of both lists are equivalent.

That means, you can compare an UCX [array list](array_list.h.md) with a [linked list](linked_list.h.md),
and you could even compare lists that are storing pointers with lists that are not storing pointers.

However, the optimized list-internal compare implementation is only used, when both the compare functions and the list classes are identical.
Otherwise, `cxListCompare()` will behave as if you were iterating through both lists and manually comparing the items.

The return value of `cxListCompare()` is zero, if the lists are item-wise equivalent.
If they are not, the non-zero return value equals the return value of the used compare function for the first pair of elements that are not equal. 

## Dispose

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

No matter with which function a `CxList` has been created, you can _always_ deallocate the entire memory with a call to `cxListFree()`.

The effect is equivalent to invoking `cxListClear()` plus deallocating the memory for the list structure.
That means, for each item in the list, the destructor functions defined by `cxDefineDestructor()` or `cxDefineAdvancedDestructor()` are called,
before deallocating the list.

When the list has been storing pointers, make sure that either another reference to the same memory exist in your program,
or any of the destructor functions deallocates the memory.
Otherwise, there is a risk of a memory leak.

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