--- name: "List.h" section: "3" platform: "linux" package: "libzycore-doc" version: "1.5.2-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/List.h" --- # List.h(3) ## NAME include/Zycore/List.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ ### Classes struct **ZyanListNode\_**\ struct **ZyanList\_**\ ### Macros \#define **ZYAN\_LIST\_INITIALIZER**\ \#define **ZYAN\_LIST\_GET**(type, node) (\*(const type\*)**ZyanListGetNodeData**(node))\ ### Typedefs typedef struct **ZyanListNode\_** **ZyanListNode**\ typedef struct **ZyanList\_** **ZyanList**\ ### Functions **ZYCORE\_EXPORT** **ZYAN\_REQUIRES\_LIBC** **ZyanStatus** **ZyanListInit** (**ZyanList** \*list, ZyanUSize element\_size, **ZyanMemberProcedure** destructor)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListInitEx** (**ZyanList** \*list, ZyanUSize element\_size, **ZyanMemberProcedure** destructor, **ZyanAllocator** \*allocator)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListInitCustomBuffer** (**ZyanList** \*list, ZyanUSize element\_size, **ZyanMemberProcedure** destructor, void \*buffer, ZyanUSize capacity)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListDestroy** (**ZyanList** \*list)\ **ZYCORE\_EXPORT** **ZYAN\_REQUIRES\_LIBC** **ZyanStatus** **ZyanListDuplicate** (**ZyanList** \*destination, const **ZyanList** \*source)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListDuplicateEx** (**ZyanList** \*destination, const **ZyanList** \*source, **ZyanAllocator** \*allocator)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListDuplicateCustomBuffer** (**ZyanList** \*destination, const **ZyanList** \*source, void \*buffer, ZyanUSize capacity)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListGetHeadNode** (const **ZyanList** \*list, const **ZyanListNode** \*\*node)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListGetTailNode** (const **ZyanList** \*list, const **ZyanListNode** \*\*node)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListGetPrevNode** (const **ZyanListNode** \*\*node)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListGetNextNode** (const **ZyanListNode** \*\*node)\ **ZYCORE\_EXPORT** const void \* **ZyanListGetNodeData** (const **ZyanListNode** \*node)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListGetNodeDataEx** (const **ZyanListNode** \*node, const void \*\*value)\ **ZYCORE\_EXPORT** void \* **ZyanListGetNodeDataMutable** (const **ZyanListNode** \*node)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListGetNodeDataMutableEx** (const **ZyanListNode** \*node, void \*\*value)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListSetNodeData** (const **ZyanList** \*list, const **ZyanListNode** \*node, const void \*value)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListPushBack** (**ZyanList** \*list, const void \*item)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListPushFront** (**ZyanList** \*list, const void \*item)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListEmplaceBack** (**ZyanList** \*list, void \*\*item, **ZyanMemberFunction** constructor)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListEmplaceFront** (**ZyanList** \*list, void \*\*item, **ZyanMemberFunction** constructor)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListPopBack** (**ZyanList** \*list)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListPopFront** (**ZyanList** \*list)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListRemove** (**ZyanList** \*list, const **ZyanListNode** \*node)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListRemoveRange** (**ZyanList** \*list, const **ZyanListNode** \*first, const **ZyanListNode** \*last)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListClear** (**ZyanList** \*list)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListResize** (**ZyanList** \*list, ZyanUSize size)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListResizeEx** (**ZyanList** \*list, ZyanUSize size, const void \*initializer)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanListGetSize** (const **ZyanList** \*list, ZyanUSize \*size)\ ## Detailed Description Implements a doubly linked list. ## Macro Definition Documentation ### #define ZYAN\_LIST\_GET(type, node) (\*(const type\*)ZyanListGetNodeData(node)) Returns the data value of the given `node`. **Parameters** *type* The desired value type. \ *node* A pointer to the `ZyanListNode` struct. **Returns** The data value of the given `node`. Note that this function is unsafe and might dereference a null-pointer. ### #define ZYAN\_LIST\_INITIALIZER **Value:**.PP ``` { \ /* allocator */ ZYAN_NULL, \ /* size */ 0, \ /* element_size */ 0, \ /* head */ ZYAN_NULL, \ /* destructor */ ZYAN_NULL, \ /* tail */ ZYAN_NULL, \ /* buffer */ ZYAN_NULL, \ /* capacity */ 0, \ /* first_unused */ ZYAN_NULL \ } ``` Defines an uninitialized `ZyanList` instance. ## Typedef Documentation ### typedef struct ZyanList\_ ZyanList Defines the `ZyanList` struct. All fields in this struct should be considered as 'private'. Any changes may lead to unexpected behavior. ### typedef struct ZyanListNode\_ ZyanListNode Defines the `ZyanListNode` struct. All fields in this struct should be considered as 'private'. Any changes may lead to unexpected behavior. ## Function Documentation ### ZYCORE\_EXPORT ZyanStatus ZyanListClear (ZyanList \* list) Erases all elements of the list. **Parameters** *list* A pointer to the `ZyanList` instance. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListDestroy (ZyanList \* list) Destroys the given `ZyanList` instance. **Parameters** *list* A pointer to the `ZyanList` instance. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZYAN\_REQUIRES\_LIBC ZyanStatus ZyanListDuplicate (ZyanList \* destination, const ZyanList \* source) Initializes a new `ZyanList` instance by duplicating an existing list. **Parameters** *destination* A pointer to the (uninitialized) destination `ZyanList` instance. \ *source* A pointer to the source list. **Returns** A zyan status code. The memory for the list is dynamically allocated by the default allocator. Finalization with `ZyanListDestroy` is required for all instances created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanListDuplicateCustomBuffer (ZyanList \* destination, const ZyanList \* source, void \* buffer, ZyanUSize capacity) Initializes a new `ZyanList` instance by duplicating an existing list and configures it to use a custom user defined buffer with a fixed size. **Parameters** *destination* A pointer to the (uninitialized) destination `ZyanList` instance. \ *source* A pointer to the source list. \ *buffer* A pointer to the buffer that is used as storage for the elements. \ *capacity* The maximum capacity (number of bytes) of the buffer including the space required for the list-nodes. This function will fail, if the capacity of the buffer is not sufficient to store all elements of the source list. **Returns** A zyan status code. The buffer capacity required to store `n` elements of type `T` is be calculated by: `size = n * sizeof(ZyanListNode) + n * sizeof(T)` Finalization is not required for instances created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanListDuplicateEx (ZyanList \* destination, const ZyanList \* source, ZyanAllocator \* allocator) Initializes a new `ZyanList` instance by duplicating an existing list and sets a custom `allocator`. **Parameters** *destination* A pointer to the (uninitialized) destination `ZyanList` instance. \ *source* A pointer to the source list. \ *allocator* A pointer to a `ZyanAllocator` instance. **Returns** A zyan status code. Finalization with `ZyanListDestroy` is required for all instances created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanListEmplaceBack (ZyanList \* list, void \*\* item, ZyanMemberFunction constructor) Constructs an `item` in-place at the end of the list. **Parameters** *list* A pointer to the `ZyanList` instance. \ *item* Receives a pointer to the new item. \ *constructor* The constructor callback or `ZYAN_NULL`. The new item will be in undefined state, if no constructor was passed. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListEmplaceFront (ZyanList \* list, void \*\* item, ZyanMemberFunction constructor) Constructs an `item` in-place at the beginning of the list. **Parameters** *list* A pointer to the `ZyanList` instance. \ *item* Receives a pointer to the new item. \ *constructor* The constructor callback or `ZYAN_NULL`. The new item will be in undefined state, if no constructor was passed. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListGetHeadNode (const ZyanList \* list, const ZyanListNode \*\* node) Returns a pointer to the first `ZyanListNode` struct of the given list. **Parameters** *list* A pointer to the `ZyanList` instance. \ *node* Receives a pointer to the first `ZyanListNode` struct of the list. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListGetNextNode (const ZyanListNode \*\* node) Receives a pointer to the next `ZyanListNode` struct linked to the passed one. **Parameters** *node* Receives a pointer to the next `ZyanListNode` struct linked to the passed one. **Returns** A zyan status code. ### ZYCORE\_EXPORT const void \* ZyanListGetNodeData (const ZyanListNode \* node) Returns a constant pointer to the data of the given `node`. **Parameters** *node* A pointer to the `ZyanListNode` struct. **Returns** A constant pointer to the the data of the given `node` or `ZYAN_NULL`, if an error occured. Take a look at `ZyanListGetNodeDataEx`, if you need a function that returns a zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListGetNodeDataEx (const ZyanListNode \* node, const void \*\* value) Returns a constant pointer to the data of the given `node`.. **Parameters** *node* A pointer to the `ZyanListNode` struct. \ *value* Receives a constant pointer to the data of the given `node`. Take a look at `ZyanListGetNodeData`, if you need a function that directly returns a pointer. **Returns** A zyan status code. ### ZYCORE\_EXPORT void \* ZyanListGetNodeDataMutable (const ZyanListNode \* node) Returns a mutable pointer to the data of the given `node`. **Parameters** *node* A pointer to the `ZyanListNode` struct. **Returns** A mutable pointer to the the data of the given `node` or `ZYAN_NULL`, if an error occured. Take a look at `ZyanListGetPointerMutableEx` instead, if you need a function that returns a zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListGetNodeDataMutableEx (const ZyanListNode \* node, void \*\* value) Returns a mutable pointer to the data of the given `node`.. **Parameters** *node* A pointer to the `ZyanListNode` struct. \ *value* Receives a mutable pointer to the data of the given `node`. Take a look at `ZyanListGetNodeDataMutable`, if you need a function that directly returns a pointer. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListGetPrevNode (const ZyanListNode \*\* node) Receives a pointer to the previous `ZyanListNode` struct linked to the passed one. **Parameters** *node* Receives a pointer to the previous `ZyanListNode` struct linked to the passed one. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListGetSize (const ZyanList \* list, ZyanUSize \* size) Returns the current size of the list. **Parameters** *list* A pointer to the `ZyanList` instance. \ *size* Receives the size of the list. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListGetTailNode (const ZyanList \* list, const ZyanListNode \*\* node) Returns a pointer to the last `ZyanListNode` struct of the given list. **Parameters** *list* A pointer to the `ZyanList` instance. \ *node* Receives a pointer to the last `ZyanListNode` struct of the list. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZYAN\_REQUIRES\_LIBC ZyanStatus ZyanListInit (ZyanList \* list, ZyanUSize element\_size, ZyanMemberProcedure destructor) Initializes the given `ZyanList` instance. **Parameters** *list* A pointer to the `ZyanList` instance. \ *element\_size* The size of a single element in bytes. \ *destructor* A destructor callback that is invoked every time an item is deleted, or `ZYAN_NULL` if not needed. **Returns** A zyan status code. The memory for the list elements is dynamically allocated by the default allocator. Finalization with `ZyanListDestroy` is required for all instances created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanListInitCustomBuffer (ZyanList \* list, ZyanUSize element\_size, ZyanMemberProcedure destructor, void \* buffer, ZyanUSize capacity) Initializes the given `ZyanList` instance and configures it to use a custom user defined buffer with a fixed size. **Parameters** *list* A pointer to the `ZyanList` instance. \ *element\_size* The size of a single element in bytes. \ *destructor* A destructor callback that is invoked every time an item is deleted, or `ZYAN_NULL` if not needed. \ *buffer* A pointer to the buffer that is used as storage for the elements. \ *capacity* The maximum capacity (number of bytes) of the buffer including the space required for the list-nodes. **Returns** A zyan status code. The buffer capacity required to store `n` elements of type `T` is be calculated by: `size = n * sizeof(ZyanListNode) + n * sizeof(T)` Finalization is not required for instances created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanListInitEx (ZyanList \* list, ZyanUSize element\_size, ZyanMemberProcedure destructor, ZyanAllocator \* allocator) Initializes the given `ZyanList` instance and sets a custom `allocator`. **Parameters** *list* A pointer to the `ZyanList` instance. \ *element\_size* The size of a single element in bytes. \ *destructor* A destructor callback that is invoked every time an item is deleted, or `ZYAN_NULL` if not needed. \ *allocator* A pointer to a `ZyanAllocator` instance. **Returns** A zyan status code. Finalization with `ZyanListDestroy` is required for all instances created by this function. ### ZYCORE\_EXPORT ZyanStatus ZyanListPopBack (ZyanList \* list) Removes the last element of the list. **Parameters** *list* A pointer to the `ZyanList` instance. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListPopFront (ZyanList \* list) Removes the firstelement of the list. **Parameters** *list* A pointer to the `ZyanList` instance. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListPushBack (ZyanList \* list, const void \* item) Adds a new `item` to the end of the list. **Parameters** *list* A pointer to the `ZyanList` instance. \ *item* A pointer to the item to add. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListPushFront (ZyanList \* list, const void \* item) Adds a new `item` to the beginning of the list. **Parameters** *list* A pointer to the `ZyanList` instance. \ *item* A pointer to the item to add. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListRemove (ZyanList \* list, const ZyanListNode \* node) Removes the given `node` from the list. **Parameters** *list* A pointer to the `ZyanList` instance. \ *node* A pointer to the `ZyanListNode` struct. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListRemoveRange (ZyanList \* list, const ZyanListNode \* first, const ZyanListNode \* last) Removes multiple nodes from the list. **Parameters** *list* A pointer to the `ZyanList` instance. \ *first* A pointer to the first node. \ *last* A pointer to the last node. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListResize (ZyanList \* list, ZyanUSize size) Resizes the given `ZyanList` instance. **Parameters** *list* A pointer to the `ZyanList` instance. \ *size* The new size of the list. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListResizeEx (ZyanList \* list, ZyanUSize size, const void \* initializer) Resizes the given `ZyanList` instance. **Parameters** *list* A pointer to the `ZyanList` instance. \ *size* The new size of the list. \ *initializer* A pointer to a value to be used as initializer for new items. **Returns** A zyan status code. ### ZYCORE\_EXPORT ZyanStatus ZyanListSetNodeData (const ZyanList \* list, const ZyanListNode \* node, const void \* value) Assigns a new data value to the given `node`. **Parameters** *list* A pointer to the `ZyanList` instance. \ *node* A pointer to the `ZyanListNode` struct. \ *value* The value to assign. **Returns** A zyan status code. ## Author Generated automatically by Doxygen for Zycore from the source code.