Zycore 1.4.0.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>

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.