List.h File Reference

Implements a doubly linked list. More...

#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.

Data Structures
struct	ZyanListNode_
	Defines the ZyanListNode struct. More...
struct	ZyanList_
	Defines the ZyanList struct. More...

Macros
#define	ZYAN_LIST_INITIALIZER
	Defines an uninitialized ZyanList instance.
#define	ZYAN_LIST_GET(type, node)
	Returns the data value of the given node.

Typedefs
typedef struct ZyanListNode_	ZyanListNode
	Defines the ZyanListNode struct.
typedef struct ZyanList_	ZyanList
	Defines the ZyanList struct.

Functions
ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus	ZyanListInit (ZyanList *list, ZyanUSize element_size, ZyanMemberProcedure destructor)
	Initializes the given ZyanList instance.
ZYCORE_EXPORT ZyanStatus	ZyanListInitEx (ZyanList *list, ZyanUSize element_size, ZyanMemberProcedure destructor, ZyanAllocator *allocator)
	Initializes the given ZyanList instance and sets a custom allocator.
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.
ZYCORE_EXPORT ZyanStatus	ZyanListDestroy (ZyanList *list)
	Destroys the given ZyanList instance.
ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus	ZyanListDuplicate (ZyanList *destination, const ZyanList *source)
	Initializes a new ZyanList instance by duplicating an existing list.
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.
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.
ZYCORE_EXPORT ZyanStatus	ZyanListGetHeadNode (const ZyanList *list, const ZyanListNode **node)
	Returns a pointer to the first ZyanListNode struct of the given list.
ZYCORE_EXPORT ZyanStatus	ZyanListGetTailNode (const ZyanList *list, const ZyanListNode **node)
	Returns a pointer to the last ZyanListNode struct of the given list.
ZYCORE_EXPORT ZyanStatus	ZyanListGetPrevNode (const ZyanListNode **node)
	Receives a pointer to the previous ZyanListNode struct linked to the passed one.
ZYCORE_EXPORT ZyanStatus	ZyanListGetNextNode (const ZyanListNode **node)
	Receives a pointer to the next ZyanListNode struct linked to the passed one.
ZYCORE_EXPORT const void *	ZyanListGetNodeData (const ZyanListNode *node)
	Returns a constant pointer to the data of the given node.
ZYCORE_EXPORT ZyanStatus	ZyanListGetNodeDataEx (const ZyanListNode *node, const void **value)
	Returns a constant pointer to the data of the given node.
ZYCORE_EXPORT void *	ZyanListGetNodeDataMutable (const ZyanListNode *node)
	Returns a mutable pointer to the data of the given node.
ZYCORE_EXPORT ZyanStatus	ZyanListGetNodeDataMutableEx (const ZyanListNode *node, void **value)
	Returns a mutable pointer to the data of the given node.
ZYCORE_EXPORT ZyanStatus	ZyanListSetNodeData (const ZyanList *list, const ZyanListNode *node, const void *value)
	Assigns a new data value to the given node.
ZYCORE_EXPORT ZyanStatus	ZyanListPushBack (ZyanList *list, const void *item)
	Adds a new item to the end of the list.
ZYCORE_EXPORT ZyanStatus	ZyanListPushFront (ZyanList *list, const void *item)
	Adds a new item to the beginning of the list.
ZYCORE_EXPORT ZyanStatus	ZyanListEmplaceBack (ZyanList *list, void **item, ZyanMemberFunction constructor)
	Constructs an item in-place at the end of the list.
ZYCORE_EXPORT ZyanStatus	ZyanListEmplaceFront (ZyanList *list, void **item, ZyanMemberFunction constructor)
	Constructs an item in-place at the beginning of the list.
ZYCORE_EXPORT ZyanStatus	ZyanListPopBack (ZyanList *list)
	Removes the last element of the list.
ZYCORE_EXPORT ZyanStatus	ZyanListPopFront (ZyanList *list)
	Removes the firstelement of the list.
ZYCORE_EXPORT ZyanStatus	ZyanListRemove (ZyanList *list, const ZyanListNode *node)
	Removes the given node from the list.
ZYCORE_EXPORT ZyanStatus	ZyanListRemoveRange (ZyanList *list, const ZyanListNode *first, const ZyanListNode *last)
	Removes multiple nodes from the list.
ZYCORE_EXPORT ZyanStatus	ZyanListClear (ZyanList *list)
	Erases all elements of the list.
ZYCORE_EXPORT ZyanStatus	ZyanListResize (ZyanList *list, ZyanUSize size)
	Resizes the given ZyanList instance.
ZYCORE_EXPORT ZyanStatus	ZyanListResizeEx (ZyanList *list, ZyanUSize size, const void *initializer)
	Resizes the given ZyanList instance.
ZYCORE_EXPORT ZyanStatus	ZyanListGetSize (const ZyanList *list, ZyanUSize *size)
	Returns the current size of the list.

Detailed Description

Implements a doubly linked list.

Macro Definition Documentation

ZYAN_LIST_GET

#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.

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

list	A pointer to the ZyanList instance.

Returns

A zyan status code.

ZyanListDestroy()

ZYCORE_EXPORT ZyanStatus ZyanListDestroy

(

ZyanList *

list

)

Destroys the given ZyanList instance.

Parameters

list	A 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

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.

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

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.

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

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.

ZyanListEmplaceBack()

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.

ZyanListEmplaceFront()

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.

ZyanListGetHeadNode()

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.

ZyanListGetNextNode()

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.

ZyanListGetNodeData()

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.

ZyanListGetNodeDataEx()

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.

ZyanListGetNodeDataMutable()

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.

ZyanListGetNodeDataMutableEx()

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.

ZyanListGetPrevNode()

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.

ZyanListGetSize()

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.

ZyanListGetTailNode()

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.

ZyanListInit()

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.

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

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.

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

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.

ZyanListPopBack()

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.

ZyanListPopFront()

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.

ZyanListPushBack()

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.

ZyanListPushFront()

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.

ZyanListRemove()

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.

ZyanListRemoveRange()

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.

ZyanListResize()

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.

ZyanListResizeEx()

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.

ZyanListSetNodeData()

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.