Scroll to navigation

include/Zycore/List.h(3) Library Functions Manual 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) (*(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.

Version 1.5.0.0 Zycore