include/Zycore/List.h(3)

📦
version 1.5.2 · 2 versions
, in ubuntu resolute, ubuntu stonking

💖 include/Zycore/List.h 💖

Library Functions Manual · section 3 🦋

okay bestie, sit down, grab a strawberry 🍓, because this is THE header for a doubly linked list and she is serving. no cap, every flag, every param, every little "this might explode" warning is right here. iykyk 💅

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

🦋 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

so what IS this? it's a doubly linked list. that's the whole vibe. girl goes both ways (forward and backward through nodes) and we love that for her 💖

🌸 Macro Definition Documentation 🌸

#define ZYAN_LIST_GET( type, node)

Value:

(*(const type*)ZyanListGetNodeData(node))

grabs the data value sitting inside the node you hand her. one line, no thoughts, just dereference ✨

Parameters

  • type — the value type you're manifesting. the desired one. 👑
  • node — a pointer to the ZyanListNode struct.

Returns

the data value of the given node. periodt.

⚠️ lowkey important bestie: note that this macro is unsafe and might dereference a null-pointer. like, she WILL do it. no guardrails. be careful 😭

#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 \
}

this one defines an uninitialized ZyanList instance. it's giving blank canvas, main character before the glow-up 🎀

🦋 Typedef Documentation 🦋

typedef struct ZyanList_ ZyanList

defines the ZyanList struct. that's her.

🫶 heads up: every single field in this struct is to be treated as "private". any changes you make may lead to unexpected behavior. do not touch. hands off. 💅

typedef struct ZyanListNode_ ZyanListNode

defines the ZyanListNode struct. the little one. the building block. iconic in her own right.

🫶 same deal: all fields in this struct should be considered "private". any changes may lead to unexpected behavior. no poking 🙈

🔥 Function Documentation 🔥

ZYCORE_EXPORT ZyanStatus ZyanListClear (ZyanList * list)

erases all elements of the list. not some. all. clean slate energy ✨

Parameters

  • list — a pointer to the ZyanList instance.

Returns

a zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanListDestroy (ZyanList * list)

destroys the given ZyanList instance. she's done, she's logging off 🌙

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. clone behavior, but make it cute 🧚

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 gets dynamically allocated by the default allocator.

⚠️ finalization with ZyanListDestroy is required for all instances created by this function. don't forget her, bestie 😭

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. diy queen 💅

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. no room, no party 🚫

Returns

a zyan status code.

the buffer capacity required to store n elements of type T is calculated by:

size = n * sizeof(ZyanListNode) + n * sizeof(T)
💖 and the best part: finalization is not required for instances created by this function. she handles herself.

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. choose your own adventure 🌈

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. back of the line but make it glamorous 🫶

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 an undefined state if no constructor was passed. 😭 (yes, undefined. she's fresh out the box with no instruction manual.)

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. front row seat, main character energy 👑

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 an 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. the head. the one at the front. 💖

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. keep it moving bestie ➡️ 🦋

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. look, don't touch 💅

Parameters

  • node — a pointer to the ZyanListNode struct.

Returns

a constant pointer to the data of the given node, or ZYAN_NULL if an error occurred.

✨ take a look at ZyanListGetNodeDataEx if you need a function that returns a zyan status code instead.

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

returns a constant pointer to the data of the given node. same energy as above, but she reports back properly 🎀

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. now we're editing, now we're changing things 🔥

Parameters

  • node — a pointer to the ZyanListNode struct.

Returns

a mutable pointer to the data of the given node, or ZYAN_NULL if an error occurred.

✨ take a look at ZyanListGetPointerMutableEx instead — yes, that's the name, don't @ me — 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. the grown-up version. she signs the paperwork 📝

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. yes she can go backwards. it's called range ⬅️ 💜

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

ZyanListGetTailNode 🦋

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

Returns a pointer to the last ZyanListNode struct of the given list. Lowkey the move when you need the tail without scrolling the whole thing, periodt.

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. It's giving setup era, bestie.

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. No skipping this, bestie. 🫶

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. Bespoke storage, no default allocator energy. 🌸

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. Choose your own allocator, main character move. 🔥

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. Bye-bye, tail. ✨

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. (Yes, one word. The manpage really said that, and honestly? Iconic.) 🙈

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. Append slay. 🦋

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. Prepend princess. 🌸

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. Targeted removal, no cap. 💅

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. Range delete, we love a clean sweep. 🌈

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. Glow up or shrink, either way. 💜

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. Same as above but with an initializer for new items, so new elements aren't just sitting there uninitialized. Very considerate. 🎀

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. Data makeover, bestie. ✨

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.

That's the whole list vibe, bestie. This page is chillin' as Zycore Version 1.5.2.0 for include/Zycore/List.h(3). Stay slay. 💖✨🦋

📦 where this page comes from