DOKK / manpages / debian 13 / libzycore-doc / Vector.h.3.en
include/Zycore/Vector.h(3) Library Functions Manual include/Zycore/Vector.h(3)

include/Zycore/Vector.h

#include <Zycore/Allocator.h>
#include <Zycore/Comparison.h>
#include <Zycore/Object.h>
#include <Zycore/Status.h>
#include <Zycore/Types.h>


struct ZyanVector_


#define ZYAN_VECTOR_MIN_CAPACITY 1
#define ZYAN_VECTOR_DEFAULT_GROWTH_FACTOR 2
#define ZYAN_VECTOR_DEFAULT_SHRINK_THRESHOLD 4
#define ZYAN_VECTOR_INITIALIZER
#define ZYAN_VECTOR_GET(type, vector, index) (*(const type*)ZyanVectorGet(vector, index))
#define ZYAN_VECTOR_FOREACH(type, vector, item_name, body)
#define ZYAN_VECTOR_FOREACH_MUTABLE(type, vector, item_name, body)


typedef struct ZyanVector_ ZyanVector


ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus ZyanVectorInit (ZyanVector *vector, ZyanUSize element_size, ZyanUSize capacity, ZyanMemberProcedure destructor)
ZYCORE_EXPORT ZyanStatus ZyanVectorInitEx (ZyanVector *vector, ZyanUSize element_size, ZyanUSize capacity, ZyanMemberProcedure destructor, ZyanAllocator *allocator, ZyanU8 growth_factor, ZyanU8 shrink_threshold)
ZYCORE_EXPORT ZyanStatus ZyanVectorInitCustomBuffer (ZyanVector *vector, ZyanUSize element_size, void *buffer, ZyanUSize capacity, ZyanMemberProcedure destructor)
ZYCORE_EXPORT ZyanStatus ZyanVectorDestroy (ZyanVector *vector)
ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus ZyanVectorDuplicate (ZyanVector *destination, const ZyanVector *source, ZyanUSize capacity)
ZYCORE_EXPORT ZyanStatus ZyanVectorDuplicateEx (ZyanVector *destination, const ZyanVector *source, ZyanUSize capacity, ZyanAllocator *allocator, ZyanU8 growth_factor, ZyanU8 shrink_threshold)
ZYCORE_EXPORT ZyanStatus ZyanVectorDuplicateCustomBuffer (ZyanVector *destination, const ZyanVector *source, void *buffer, ZyanUSize capacity)
ZYCORE_EXPORT const void * ZyanVectorGet (const ZyanVector *vector, ZyanUSize index)
ZYCORE_EXPORT void * ZyanVectorGetMutable (const ZyanVector *vector, ZyanUSize index)
ZYCORE_EXPORT ZyanStatus ZyanVectorGetPointer (const ZyanVector *vector, ZyanUSize index, const void **value)
ZYCORE_EXPORT ZyanStatus ZyanVectorGetPointerMutable (const ZyanVector *vector, ZyanUSize index, void **value)
ZYCORE_EXPORT ZyanStatus ZyanVectorSet (ZyanVector *vector, ZyanUSize index, const void *value)
ZYCORE_EXPORT ZyanStatus ZyanVectorPushBack (ZyanVector *vector, const void *element)
ZYCORE_EXPORT ZyanStatus ZyanVectorInsert (ZyanVector *vector, ZyanUSize index, const void *element)
ZYCORE_EXPORT ZyanStatus ZyanVectorInsertRange (ZyanVector *vector, ZyanUSize index, const void *elements, ZyanUSize count)
ZYCORE_EXPORT ZyanStatus ZyanVectorEmplace (ZyanVector *vector, void **element, ZyanMemberFunction constructor)
ZYCORE_EXPORT ZyanStatus ZyanVectorEmplaceEx (ZyanVector *vector, ZyanUSize index, void **element, ZyanMemberFunction constructor)
ZYCORE_EXPORT ZyanStatus ZyanVectorSwapElements (ZyanVector *vector, ZyanUSize index_first, ZyanUSize index_second)
ZYCORE_EXPORT ZyanStatus ZyanVectorDelete (ZyanVector *vector, ZyanUSize index)
ZYCORE_EXPORT ZyanStatus ZyanVectorDeleteRange (ZyanVector *vector, ZyanUSize index, ZyanUSize count)
ZYCORE_EXPORT ZyanStatus ZyanVectorPopBack (ZyanVector *vector)
ZYCORE_EXPORT ZyanStatus ZyanVectorClear (ZyanVector *vector)
ZYCORE_EXPORT ZyanStatus ZyanVectorFind (const ZyanVector *vector, const void *element, ZyanISize *found_index, ZyanEqualityComparison comparison)
ZYCORE_EXPORT ZyanStatus ZyanVectorFindEx (const ZyanVector *vector, const void *element, ZyanISize *found_index, ZyanEqualityComparison comparison, ZyanUSize index, ZyanUSize count)
ZYCORE_EXPORT ZyanStatus ZyanVectorBinarySearch (const ZyanVector *vector, const void *element, ZyanUSize *found_index, ZyanComparison comparison)
ZYCORE_EXPORT ZyanStatus ZyanVectorBinarySearchEx (const ZyanVector *vector, const void *element, ZyanUSize *found_index, ZyanComparison comparison, ZyanUSize index, ZyanUSize count)
ZYCORE_EXPORT ZyanStatus ZyanVectorResize (ZyanVector *vector, ZyanUSize size)
ZYCORE_EXPORT ZyanStatus ZyanVectorResizeEx (ZyanVector *vector, ZyanUSize size, const void *initializer)
ZYCORE_EXPORT ZyanStatus ZyanVectorReserve (ZyanVector *vector, ZyanUSize capacity)
ZYCORE_EXPORT ZyanStatus ZyanVectorShrinkToFit (ZyanVector *vector)
ZYCORE_EXPORT ZyanStatus ZyanVectorGetCapacity (const ZyanVector *vector, ZyanUSize *capacity)
ZYCORE_EXPORT ZyanStatus ZyanVectorGetSize (const ZyanVector *vector, ZyanUSize *size)

Implements the vector container class.

The default growth factor for all vector instances.

The default shrink threshold for all vector instances.

Value:.PP



    { \


        const ZyanUSize ZYAN_MACRO_CONCAT_EXPAND(size_d50d3303, item_name) = (vector)->size; \


        for (ZyanUSize ZYAN_MACRO_CONCAT_EXPAND(i_bfd62679, item_name) = 0; \


            ZYAN_MACRO_CONCAT_EXPAND(i_bfd62679, item_name) < \


            ZYAN_MACRO_CONCAT_EXPAND(size_d50d3303, item_name); \


            ++ZYAN_MACRO_CONCAT_EXPAND(i_bfd62679, item_name)) \


        { \


            const type item_name = ZYAN_VECTOR_GET(type, vector, \


                ZYAN_MACRO_CONCAT_EXPAND(i_bfd62679, item_name)); \


            body \


        } \


    }

Loops through all elements of the vector.

Parameters

type The desired value type.
vector A pointer to the ZyanVector instance.
item_name The name of the iterator item.
body The body to execute for each item in the vector.

Value:.PP



    { \


        const ZyanUSize ZYAN_MACRO_CONCAT_EXPAND(size_d50d3303, item_name) = (vector)->size; \


        for (ZyanUSize ZYAN_MACRO_CONCAT_EXPAND(i_bfd62679, item_name) = 0; \


            ZYAN_MACRO_CONCAT_EXPAND(i_bfd62679, item_name) < \


            ZYAN_MACRO_CONCAT_EXPAND(size_d50d3303, item_name); \


            ++ZYAN_MACRO_CONCAT_EXPAND(i_bfd62679, item_name)) \


        { \


            type* const item_name = ZyanVectorGetMutable(vector, \


                ZYAN_MACRO_CONCAT_EXPAND(i_bfd62679, item_name)); \


            body \


        } \


    }

Loops through all elements of the vector.

Parameters

type The desired value type.
vector A pointer to the ZyanVector instance.
item_name The name of the iterator item.
body The body to execute for each item in the vector.

Returns the value of the element at the given index.

Parameters

type The desired value type.
vector A pointer to the ZyanVector instance.
index The element index.

Returns

The value of the desired element in the vector.

Note that this function is unsafe and might dereference a null-pointer.

Value:.PP



    { \


        /* allocator        */ ZYAN_NULL, \


        /* growth_factor    */ 0, \


        /* shrink_threshold */ 0, \


        /* size             */ 0, \


        /* capacity         */ 0, \


        /* element_size     */ 0, \


        /* destructor       */ ZYAN_NULL, \


        /* data             */ ZYAN_NULL \


    }

Defines an uninitialized ZyanVector instance.

The initial minimum capacity (number of elements) for all dynamically allocated vector instances.

Defines the ZyanVector struct.

All fields in this struct should be considered as 'private'. Any changes may lead to unexpected behavior.

ZYCORE_EXPORT ZyanStatus ZyanVectorBinarySearch (const ZyanVector * vector, const void * element, ZyanUSize * found_index, ZyanComparison comparison)

Searches for the first occurrence of element in the given vector using a binary- search algorithm.

Parameters

vector A pointer to the ZyanVector instance.
element A pointer to the element to search for.
found_index A pointer to a variable that receives the index of the found element.
comparison The comparison function to use.

Returns

ZYAN_STATUS_TRUE if the element was found, ZYAN_STATUS_FALSE if not or a generic zyan status code if an error occurred.

If found, found_index contains the zero-based index of element. If not found, found_index contains the index of the first entry larger than element.

This function requires all elements in the vector to be strictly ordered (sorted).

ZYCORE_EXPORT ZyanStatus ZyanVectorBinarySearchEx (const ZyanVector * vector, const void * element, ZyanUSize * found_index, ZyanComparison comparison, ZyanUSize index, ZyanUSize count)

Searches for the first occurrence of element in the given vector using a binary- search algorithm.

Parameters

vector A pointer to the ZyanVector instance.
element A pointer to the element to search for.
found_index A pointer to a variable that receives the index of the found element.
comparison The comparison function to use.
index The start index.
count The maximum number of elements to iterate, beginning from the start index.

Returns

ZYAN_STATUS_TRUE if the element was found, ZYAN_STATUS_FALSE if not or a generic zyan status code if an error occurred.

If found, found_index contains the zero-based index of element. If not found, found_index contains the index of the first entry larger than element.

This function requires all elements in the vector to be strictly ordered (sorted).

ZYCORE_EXPORT ZyanStatus ZyanVectorClear (ZyanVector * vector)

Erases all elements of the given vector.

Parameters

vector A pointer to the ZyanVector instance.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorDelete (ZyanVector * vector, ZyanUSize index)

Deletes the element at the given index of the vector.

Parameters

vector A pointer to the ZyanVector instance.
index The element index.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorDeleteRange (ZyanVector * vector, ZyanUSize index, ZyanUSize count)

Deletes multiple elements from the given vector, starting at index.

Parameters

vector A pointer to the ZyanVector instance.
index The index of the first element to delete.
count The number of elements to delete.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorDestroy (ZyanVector * vector)

Destroys the given ZyanVector instance.

Parameters

vector A pointer to the ZyanVector instance..

Returns

A zyan status code.

ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus ZyanVectorDuplicate (ZyanVector * destination, const ZyanVector * source, ZyanUSize capacity)

Initializes a new ZyanVector instance by duplicating an existing vector.

Parameters

destination A pointer to the (uninitialized) destination ZyanVector instance.
source A pointer to the source vector.
capacity The initial capacity (number of elements). 



                 This value is automatically adjusted to the size of the source vector, if


                 a smaller value was passed.

Returns

A zyan status code.

The memory for the vector is dynamically allocated by the default allocator using the default growth factor and the default shrink threshold.

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

ZYCORE_EXPORT ZyanStatus ZyanVectorDuplicateCustomBuffer (ZyanVector * destination, const ZyanVector * source, void * buffer, ZyanUSize capacity)

Initializes a new ZyanVector instance by duplicating an existing vector and configures it to use a custom user defined buffer with a fixed size.

Parameters

destination A pointer to the (uninitialized) destination ZyanVector instance.
source A pointer to the source vector.
buffer A pointer to the buffer that is used as storage for the elements.
capacity The maximum capacity (number of elements) of the buffer. 



                 This function will fail, if the capacity of the buffer is less than the


                 size of the source vector.

Returns

A zyan status code.

Finalization is not required for instances created by this function.

ZYCORE_EXPORT ZyanStatus ZyanVectorDuplicateEx (ZyanVector * destination, const ZyanVector * source, ZyanUSize capacity, ZyanAllocator * allocator, ZyanU8 growth_factor, ZyanU8 shrink_threshold)

Initializes a new ZyanVector instance by duplicating an existing vector and sets a custom allocator and memory allocation/deallocation parameters.

Parameters

destination A pointer to the (uninitialized) destination ZyanVector instance.
source A pointer to the source vector.
capacity The initial capacity (number of elements). 



                         This value is automatically adjusted to the size of the source


                         vector, if a smaller value was passed.

allocator A pointer to a ZyanAllocator instance.
growth_factor The growth factor.
shrink_threshold The shrink threshold.

Returns

A zyan status code.

A growth factor of 1 disables overallocation and a shrink threshold of 0 disables dynamic shrinking.

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

ZYCORE_EXPORT ZyanStatus ZyanVectorEmplace (ZyanVector * vector, void ** element, ZyanMemberFunction constructor)

Constructs an element in-place at the end of the vector.

Parameters

vector A pointer to the ZyanVector instance.
element Receives a pointer to the new element.
constructor The constructor callback or ZYAN_NULL. The new element will be in undefined state, if no constructor was passed.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorEmplaceEx (ZyanVector * vector, ZyanUSize index, void ** element, ZyanMemberFunction constructor)

Constructs an element in-place and inserts it at the given index of the vector.

Parameters

vector A pointer to the ZyanVector instance.
index The insert index.
element Receives a pointer to the new element.
constructor The constructor callback or ZYAN_NULL. The new element will be in undefined state, if no constructor was passed.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorFind (const ZyanVector * vector, const void * element, ZyanISize * found_index, ZyanEqualityComparison comparison)

Sequentially searches for the first occurrence of element in the given vector.

Parameters

vector A pointer to the ZyanVector instance.
element A pointer to the element to search for.
found_index A pointer to a variable that receives the index of the found element.
comparison The comparison function to use.

Returns

ZYAN_STATUS_TRUE if the element was found, ZYAN_STATUS_FALSE if not or a generic zyan status code if an error occurred.

The found_index is set to -1, if the element was not found.

ZYCORE_EXPORT ZyanStatus ZyanVectorFindEx (const ZyanVector * vector, const void * element, ZyanISize * found_index, ZyanEqualityComparison comparison, ZyanUSize index, ZyanUSize count)

Sequentially searches for the first occurrence of element in the given vector.

Parameters

vector A pointer to the ZyanVector instance.
element A pointer to the element to search for.
found_index A pointer to a variable that receives the index of the found element.
comparison The comparison function to use.
index The start index.
count The maximum number of elements to iterate, beginning from the start index.

Returns

ZYAN_STATUS_TRUE if the element was found, ZYAN_STATUS_FALSE if not or a generic zyan status code if an error occurred.

The found_index is set to -1, if the element was not found.

ZYCORE_EXPORT const void * ZyanVectorGet (const ZyanVector * vector, ZyanUSize index)

Returns a constant pointer to the element at the given index.

Parameters

vector A pointer to the ZyanVector instance.
index The element index.

Returns

A constant pointer to the desired element in the vector or ZYAN_NULL, if an error occurred.

Note that the returned pointer might get invalid when the vector is resized by either a manual call to the memory-management functions or implicitly by inserting or removing elements.

Take a look at ZyanVectorGetPointer instead, if you need a function that returns a zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorGetCapacity (const ZyanVector * vector, ZyanUSize * capacity)

Returns the current capacity of the vector.

Parameters

vector A pointer to the ZyanVector instance.
capacity Receives the size of the vector.

Returns

A zyan status code.

ZYCORE_EXPORT void * ZyanVectorGetMutable (const ZyanVector * vector, ZyanUSize index)

Returns a mutable pointer to the element at the given index.

Parameters

vector A pointer to the ZyanVector instance.
index The element index.

Returns

A mutable pointer to the desired element in the vector or ZYAN_NULL, if an error occurred.

Note that the returned pointer might get invalid when the vector is resized by either a manual call to the memory-management functions or implicitly by inserting or removing elements.

Take a look at ZyanVectorGetPointerMutable instead, if you need a function that returns a zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorGetPointer (const ZyanVector * vector, ZyanUSize index, const void ** value)

Returns a constant pointer to the element at the given index.

Parameters

vector A pointer to the ZyanVector instance.
index The element index.
value Receives a constant pointer to the desired element in the vector.

Note that the returned pointer might get invalid when the vector is resized by either a manual call to the memory-management functions or implicitly by inserting or removing elements.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorGetPointerMutable (const ZyanVector * vector, ZyanUSize index, void ** value)

Returns a mutable pointer to the element at the given index.

Parameters

vector A pointer to the ZyanVector instance.
index The element index.
value Receives a mutable pointer to the desired element in the vector.

Note that the returned pointer might get invalid when the vector is resized by either a manual call to the memory-management functions or implicitly by inserting or removing elements.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorGetSize (const ZyanVector * vector, ZyanUSize * size)

Returns the current size of the vector.

Parameters

vector A pointer to the ZyanVector instance.
size Receives the size of the vector.

Returns

A zyan status code.

ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus ZyanVectorInit (ZyanVector * vector, ZyanUSize element_size, ZyanUSize capacity, ZyanMemberProcedure destructor)

Initializes the given ZyanVector instance.

Parameters

vector A pointer to the ZyanVector instance.
element_size The size of a single element in bytes.
capacity The initial capacity (number of elements).
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 vector elements is dynamically allocated by the default allocator using the default growth factor and the default shrink threshold.

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

ZYCORE_EXPORT ZyanStatus ZyanVectorInitCustomBuffer (ZyanVector * vector, ZyanUSize element_size, void * buffer, ZyanUSize capacity, ZyanMemberProcedure destructor)

Initializes the given ZyanVector instance and configures it to use a custom user defined buffer with a fixed size.

Parameters

vector A pointer to the ZyanVector instance.
element_size The size of a single element in bytes.
buffer A pointer to the buffer that is used as storage for the elements.
capacity The maximum capacity (number of elements) of the buffer.
destructor A destructor callback that is invoked every time an item is deleted, or ZYAN_NULL if not needed.

Returns

A zyan status code.

Finalization is not required for instances created by this function.

ZYCORE_EXPORT ZyanStatus ZyanVectorInitEx (ZyanVector * vector, ZyanUSize element_size, ZyanUSize capacity, ZyanMemberProcedure destructor, ZyanAllocator * allocator, ZyanU8 growth_factor, ZyanU8 shrink_threshold)

Initializes the given ZyanVector instance and sets a custom allocator and memory allocation/deallocation parameters.

Parameters

vector A pointer to the ZyanVector instance.
element_size The size of a single element in bytes.
capacity The initial capacity (number of elements).
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.
growth_factor The growth factor.
shrink_threshold The shrink threshold.

Returns

A zyan status code.

A growth factor of 1 disables overallocation and a shrink threshold of 0 disables dynamic shrinking.

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

ZYCORE_EXPORT ZyanStatus ZyanVectorInsert (ZyanVector * vector, ZyanUSize index, const void * element)

Inserts an element at the given index of the vector.

Parameters

vector A pointer to the ZyanVector instance.
index The insert index.
element A pointer to the element to insert.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorInsertRange (ZyanVector * vector, ZyanUSize index, const void * elements, ZyanUSize count)

Inserts multiple elements at the given index of the vector.

Parameters

vector A pointer to the ZyanVector instance.
index The insert index.
elements A pointer to the first element.
count The number of elements to insert.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorPopBack (ZyanVector * vector)

Removes the last element of the vector.

Parameters

vector A pointer to the ZyanVector instance.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorPushBack (ZyanVector * vector, const void * element)

Adds a new element to the end of the vector.

Parameters

vector A pointer to the ZyanVector instance.
element A pointer to the element to add.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorReserve (ZyanVector * vector, ZyanUSize capacity)

Changes the capacity of the given ZyanVector instance.

Parameters

vector A pointer to the ZyanVector instance.
capacity The new minimum capacity of the vector.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorResize (ZyanVector * vector, ZyanUSize size)

Resizes the given ZyanVector instance.

Parameters

vector A pointer to the ZyanVector instance.
size The new size of the vector.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorResizeEx (ZyanVector * vector, ZyanUSize size, const void * initializer)

Resizes the given ZyanVector instance.

Parameters

vector A pointer to the ZyanVector instance.
size The new size of the vector.
initializer A pointer to a value to be used as initializer for new items.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorSet (ZyanVector * vector, ZyanUSize index, const void * value)

Assigns a new value to the element at the given index.

Parameters

vector A pointer to the ZyanVector instance.
index The value index.
value The value to assign.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorShrinkToFit (ZyanVector * vector)

Shrinks the capacity of the given vector to match it's size.

Parameters

vector A pointer to the ZyanVector instance.

Returns

A zyan status code.

ZYCORE_EXPORT ZyanStatus ZyanVectorSwapElements (ZyanVector * vector, ZyanUSize index_first, ZyanUSize index_second)

Swaps the element at index_first with the element at index_second.

Parameters

vector A pointer to the ZyanVector instance.
index_first The index of the first element.
index_second The index of the second element.

Returns

A zyan status code.

This function requires the vector to have spare capacity for one temporary element. Call ZyanVectorReserve before this function to increase capacity, if needed.

Generated automatically by Doxygen for Zycore from the source code.

Version 1.5.2.0 Zycore