include/Zycore/List.h(3)

NAME
include/Zycore/List.h

SYNOPSIS

#include <Zycore/Allocator.h>
#include <Zycore/Object.h>
#include <Zycore/Status.h>
#include <Zycore/Types.h>

  Classes

struct ZyanListNode_
struct ZyanList_

  Macros

#define ZYAN_LIST_INITIALIZER
#define ZYAN_LIST_GET(type, 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)
Value:
    (*(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:
    { \
        /* 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.