Loading...
Searching...
No Matches
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)

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

Value:
(*(const type*)ZyanListGetNodeData(node))
ZyanListGetNodeData
ZYCORE_EXPORT const void * ZyanListGetNodeData(const ZyanListNode *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.