Zycore 1.5.1.0
Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Functions
List.h File Reference
#include <Zycore/Allocator.h>
#include <Zycore/Object.h>
#include <Zycore/Status.h>
#include <Zycore/Types.h>
Include dependency graph for List.h:

Go to the source code of this file.

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

◆ ZYAN_LIST_GET

#define ZYAN_LIST_GET (   type,
  node 
)     (*(const type*)ZyanListGetNodeData(node))

Returns the data value of the given node.

Parameters
typeThe desired value type.
nodeA 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.

◆ ZYAN_LIST_INITIALIZER

#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

◆ ZyanList

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.

◆ ZyanListNode

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

◆ ZyanListClear()

ZYCORE_EXPORT ZyanStatus ZyanListClear ( ZyanList list)

Erases all elements of the list.

Parameters
listA pointer to the ZyanList instance.
Returns
A zyan status code.

◆ ZyanListDestroy()

ZYCORE_EXPORT ZyanStatus ZyanListDestroy ( ZyanList list)

Destroys the given ZyanList instance.

Parameters
listA pointer to the ZyanList instance.
Returns
A zyan status code.

◆ ZyanListDuplicate()

ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus ZyanListDuplicate ( ZyanList destination,
const ZyanList source 
)

Initializes a new ZyanList instance by duplicating an existing list.

Parameters
destinationA pointer to the (uninitialized) destination ZyanList instance.
sourceA 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.

◆ ZyanListDuplicateCustomBuffer()

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
destinationA pointer to the (uninitialized) destination ZyanList instance.
sourceA pointer to the source list.
bufferA pointer to the buffer that is used as storage for the elements.
capacityThe 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.

◆ ZyanListDuplicateEx()

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
destinationA pointer to the (uninitialized) destination ZyanList instance.
sourceA pointer to the source list.
allocatorA pointer to a ZyanAllocator instance.
Returns
A zyan status code.

Finalization with ZyanListDestroy is required for all instances created by this function.

◆ ZyanListEmplaceBack()

ZYCORE_EXPORT ZyanStatus ZyanListEmplaceBack ( ZyanList list,
void **  item,
ZyanMemberFunction  constructor 
)

Constructs an item in-place at the end of the list.

Parameters
listA pointer to the ZyanList instance.
itemReceives a pointer to the new item.
constructorThe constructor callback or ZYAN_NULL. The new item will be in undefined state, if no constructor was passed.
Returns
A zyan status code.

◆ ZyanListEmplaceFront()

ZYCORE_EXPORT ZyanStatus ZyanListEmplaceFront ( ZyanList list,
void **  item,
ZyanMemberFunction  constructor 
)

Constructs an item in-place at the beginning of the list.

Parameters
listA pointer to the ZyanList instance.
itemReceives a pointer to the new item.
constructorThe constructor callback or ZYAN_NULL. The new item will be in undefined state, if no constructor was passed.
Returns
A zyan status code.

◆ ZyanListGetHeadNode()

ZYCORE_EXPORT ZyanStatus ZyanListGetHeadNode ( const ZyanList list,
const ZyanListNode **  node 
)

Returns a pointer to the first ZyanListNode struct of the given list.

Parameters
listA pointer to the ZyanList instance.
nodeReceives a pointer to the first ZyanListNode struct of the list.
Returns
A zyan status code.

◆ ZyanListGetNextNode()

ZYCORE_EXPORT ZyanStatus ZyanListGetNextNode ( const ZyanListNode **  node)

Receives a pointer to the next ZyanListNode struct linked to the passed one.

Parameters
nodeReceives a pointer to the next ZyanListNode struct linked to the passed one.
Returns
A zyan status code.

◆ ZyanListGetNodeData()

ZYCORE_EXPORT const void * ZyanListGetNodeData ( const ZyanListNode node)

Returns a constant pointer to the data of the given node.

Parameters
nodeA 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.

◆ ZyanListGetNodeDataEx()

ZYCORE_EXPORT ZyanStatus ZyanListGetNodeDataEx ( const ZyanListNode node,
const void **  value 
)

Returns a constant pointer to the data of the given node..

Parameters
nodeA pointer to the ZyanListNode struct.
valueReceives 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.

◆ ZyanListGetNodeDataMutable()

ZYCORE_EXPORT void * ZyanListGetNodeDataMutable ( const ZyanListNode node)

Returns a mutable pointer to the data of the given node.

Parameters
nodeA 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.

◆ ZyanListGetNodeDataMutableEx()

ZYCORE_EXPORT ZyanStatus ZyanListGetNodeDataMutableEx ( const ZyanListNode node,
void **  value 
)

Returns a mutable pointer to the data of the given node..

Parameters
nodeA pointer to the ZyanListNode struct.
valueReceives 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.

◆ ZyanListGetPrevNode()

ZYCORE_EXPORT ZyanStatus ZyanListGetPrevNode ( const ZyanListNode **  node)

Receives a pointer to the previous ZyanListNode struct linked to the passed one.

Parameters
nodeReceives a pointer to the previous ZyanListNode struct linked to the passed one.
Returns
A zyan status code.

◆ ZyanListGetSize()

ZYCORE_EXPORT ZyanStatus ZyanListGetSize ( const ZyanList list,
ZyanUSize *  size 
)

Returns the current size of the list.

Parameters
listA pointer to the ZyanList instance.
sizeReceives the size of the list.
Returns
A zyan status code.

◆ ZyanListGetTailNode()

ZYCORE_EXPORT ZyanStatus ZyanListGetTailNode ( const ZyanList list,
const ZyanListNode **  node 
)

Returns a pointer to the last ZyanListNode struct of the given list.

Parameters
listA pointer to the ZyanList instance.
nodeReceives a pointer to the last ZyanListNode struct of the list.
Returns
A zyan status code.

◆ ZyanListInit()

ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus ZyanListInit ( ZyanList list,
ZyanUSize  element_size,
ZyanMemberProcedure  destructor 
)

Initializes the given ZyanList instance.

Parameters
listA pointer to the ZyanList instance.
element_sizeThe size of a single element in bytes.
destructorA 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.

◆ ZyanListInitCustomBuffer()

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
listA pointer to the ZyanList instance.
element_sizeThe size of a single element in bytes.
destructorA destructor callback that is invoked every time an item is deleted, or ZYAN_NULL if not needed.
bufferA pointer to the buffer that is used as storage for the elements.
capacityThe 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.

◆ ZyanListInitEx()

ZYCORE_EXPORT ZyanStatus ZyanListInitEx ( ZyanList list,
ZyanUSize  element_size,
ZyanMemberProcedure  destructor,
ZyanAllocator allocator 
)

Initializes the given ZyanList instance and sets a custom allocator.

Parameters
listA pointer to the ZyanList instance.
element_sizeThe size of a single element in bytes.
destructorA destructor callback that is invoked every time an item is deleted, or ZYAN_NULL if not needed.
allocatorA pointer to a ZyanAllocator instance.
Returns
A zyan status code.

Finalization with ZyanListDestroy is required for all instances created by this function.

◆ ZyanListPopBack()

ZYCORE_EXPORT ZyanStatus ZyanListPopBack ( ZyanList list)

Removes the last element of the list.

Parameters
listA pointer to the ZyanList instance.
Returns
A zyan status code.

◆ ZyanListPopFront()

ZYCORE_EXPORT ZyanStatus ZyanListPopFront ( ZyanList list)

Removes the firstelement of the list.

Parameters
listA pointer to the ZyanList instance.
Returns
A zyan status code.

◆ ZyanListPushBack()

ZYCORE_EXPORT ZyanStatus ZyanListPushBack ( ZyanList list,
const void *  item 
)

Adds a new item to the end of the list.

Parameters
listA pointer to the ZyanList instance.
itemA pointer to the item to add.
Returns
A zyan status code.

◆ ZyanListPushFront()

ZYCORE_EXPORT ZyanStatus ZyanListPushFront ( ZyanList list,
const void *  item 
)

Adds a new item to the beginning of the list.

Parameters
listA pointer to the ZyanList instance.
itemA pointer to the item to add.
Returns
A zyan status code.

◆ ZyanListRemove()

ZYCORE_EXPORT ZyanStatus ZyanListRemove ( ZyanList list,
const ZyanListNode node 
)

Removes the given node from the list.

Parameters
listA pointer to the ZyanList instance.
nodeA pointer to the ZyanListNode struct.
Returns
A zyan status code.

◆ ZyanListRemoveRange()

ZYCORE_EXPORT ZyanStatus ZyanListRemoveRange ( ZyanList list,
const ZyanListNode first,
const ZyanListNode last 
)

Removes multiple nodes from the list.

Parameters
listA pointer to the ZyanList instance.
firstA pointer to the first node.
lastA pointer to the last node.
Returns
A zyan status code.

◆ ZyanListResize()

ZYCORE_EXPORT ZyanStatus ZyanListResize ( ZyanList list,
ZyanUSize  size 
)

Resizes the given ZyanList instance.

Parameters
listA pointer to the ZyanList instance.
sizeThe new size of the list.
Returns
A zyan status code.

◆ ZyanListResizeEx()

ZYCORE_EXPORT ZyanStatus ZyanListResizeEx ( ZyanList list,
ZyanUSize  size,
const void *  initializer 
)

Resizes the given ZyanList instance.

Parameters
listA pointer to the ZyanList instance.
sizeThe new size of the list.
initializerA pointer to a value to be used as initializer for new items.
Returns
A zyan status code.

◆ ZyanListSetNodeData()

ZYCORE_EXPORT ZyanStatus ZyanListSetNodeData ( const ZyanList list,
const ZyanListNode node,
const void *  value 
)

Assigns a new data value to the given node.

Parameters
listA pointer to the ZyanList instance.
nodeA pointer to the ZyanListNode struct.
valueThe value to assign.
Returns
A zyan status code.