include/Zycore/Vector.h

Author

       Generated automatically by Doxygen for Zycore from the source code.

Zycore                                           Version 1.5.2.0                      include/Zycore/Vector.h(3)

Detailed Description

       Implements the vector container class.

Function Documentation

ZYCORE_EXPORTZyanStatusZyanVectorBinarySearch(constZyanVector*vector,constvoid*element,ZyanUSize*found_index,ZyanComparisoncomparison)
Searches for the first occurrence of element in the given vector using a binary- search algorithm.

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_EXPORTZyanStatusZyanVectorBinarySearchEx(constZyanVector*vector,constvoid*element,ZyanUSize*found_index,ZyanComparisoncomparison,ZyanUSizeindex,ZyanUSizecount)
Searches for the first occurrence of element in the given vector using a binary- search algorithm.

Parametersvector 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_EXPORTZyanStatusZyanVectorClear(ZyanVector*vector)
Erases all elements of the given vector.

Parametersvector A pointer to the ZyanVector instance.

Returns
A zyan status code.

ZYCORE_EXPORTZyanStatusZyanVectorDelete(ZyanVector*vector,ZyanUSizeindex)
Deletes the element at the given index of the vector.

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

Returns
A zyan status code.

ZYCORE_EXPORTZyanStatusZyanVectorDeleteRange(ZyanVector*vector,ZyanUSizeindex,ZyanUSizecount)
Deletes multiple elements from the given vector, starting at index.

Parametersvector 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_EXPORTZyanStatusZyanVectorDestroy(ZyanVector*vector)
Destroys the given ZyanVector instance.

Parametersvector A pointer to the ZyanVector instance..

Returns
A zyan status code.

ZYCORE_EXPORTZYAN_REQUIRES_LIBCZyanStatusZyanVectorDuplicate(ZyanVector*destination,constZyanVector*source,ZyanUSizecapacity)
Initializes a new ZyanVector instance by duplicating an existing vector.

Parametersdestination 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_EXPORTZyanStatusZyanVectorDuplicateCustomBuffer(ZyanVector*destination,constZyanVector*source,void*buffer,ZyanUSizecapacity)
Initializes a new ZyanVector instance by duplicating an existing vector and configures it to use a custom
user defined buffer with a fixed size.

Parametersdestination 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_EXPORTZyanStatusZyanVectorDuplicateEx(ZyanVector*destination,constZyanVector*source,ZyanUSizecapacity,ZyanAllocator*allocator,ZyanU8growth_factor,ZyanU8shrink_threshold)
Initializes a new ZyanVector instance by duplicating an existing vector and sets a custom allocator and
memory allocation/deallocation parameters.

Parametersdestination 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_EXPORTZyanStatusZyanVectorEmplace(ZyanVector*vector,void**element,ZyanMemberFunctionconstructor)
Constructs an element in-place at the end of the vector.

Parametersvector 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_EXPORTZyanStatusZyanVectorEmplaceEx(ZyanVector*vector,ZyanUSizeindex,void**element,ZyanMemberFunctionconstructor)
Constructs an element in-place and inserts it at the given index of the vector.

Parametersvector 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_EXPORTZyanStatusZyanVectorFind(constZyanVector*vector,constvoid*element,ZyanISize*found_index,ZyanEqualityComparisoncomparison)
Sequentially searches for the first occurrence of element in the given vector.

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_EXPORTZyanStatusZyanVectorFindEx(constZyanVector*vector,constvoid*element,ZyanISize*found_index,ZyanEqualityComparisoncomparison,ZyanUSizeindex,ZyanUSizecount)
Sequentially searches for the first occurrence of element in the given vector.

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_EXPORTconstvoid*ZyanVectorGet(constZyanVector*vector,ZyanUSizeindex)
Returns a constant pointer to the element at the given index.

Parametersvector 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_EXPORTZyanStatusZyanVectorGetCapacity(constZyanVector*vector,ZyanUSize*capacity)
Returns the current capacity of the vector.

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

Returns
A zyan status code.

ZYCORE_EXPORTvoid*ZyanVectorGetMutable(constZyanVector*vector,ZyanUSizeindex)
Returns a mutable pointer to the element at the given index.

Parametersvector 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_EXPORTZyanStatusZyanVectorGetPointer(constZyanVector*vector,ZyanUSizeindex,constvoid**value)
Returns a constant pointer to the element at the given index.

Parametersvector 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_EXPORTZyanStatusZyanVectorGetPointerMutable(constZyanVector*vector,ZyanUSizeindex,void**value)
Returns a mutable pointer to the element at the given index.

Parametersvector 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_EXPORTZyanStatusZyanVectorGetSize(constZyanVector*vector,ZyanUSize*size)
Returns the current size of the vector.

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

Returns
A zyan status code.

ZYCORE_EXPORTZYAN_REQUIRES_LIBCZyanStatusZyanVectorInit(ZyanVector*vector,ZyanUSizeelement_size,ZyanUSizecapacity,ZyanMemberProceduredestructor)
Initializes the given ZyanVector instance.

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_EXPORTZyanStatusZyanVectorInitCustomBuffer(ZyanVector*vector,ZyanUSizeelement_size,void*buffer,ZyanUSizecapacity,ZyanMemberProceduredestructor)
Initializes the given ZyanVector instance and configures it to use a custom user defined buffer with a
fixed size.

Parametersvector 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_EXPORTZyanStatusZyanVectorInitEx(ZyanVector*vector,ZyanUSizeelement_size,ZyanUSizecapacity,ZyanMemberProceduredestructor,ZyanAllocator*allocator,ZyanU8growth_factor,ZyanU8shrink_threshold)

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

Parametersvector 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_EXPORTZyanStatusZyanVectorInsert(ZyanVector*vector,ZyanUSizeindex,constvoid*element)
Inserts an element at the given index of the vector.

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

Returns
A zyan status code.

ZYCORE_EXPORTZyanStatusZyanVectorInsertRange(ZyanVector*vector,ZyanUSizeindex,constvoid*elements,ZyanUSizecount)
Inserts multiple elements at the given index of the vector.

Parametersvector 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_EXPORTZyanStatusZyanVectorPopBack(ZyanVector*vector)
Removes the last element of the vector.

Parametersvector A pointer to the ZyanVector instance.

Returns
A zyan status code.

ZYCORE_EXPORTZyanStatusZyanVectorPushBack(ZyanVector*vector,constvoid*element)
Adds a new element to the end of the vector.

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

Returns
A zyan status code.

ZYCORE_EXPORTZyanStatusZyanVectorReserve(ZyanVector*vector,ZyanUSizecapacity)
Changes the capacity of the given ZyanVector instance.

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

Returns
A zyan status code.

ZYCORE_EXPORTZyanStatusZyanVectorResize(ZyanVector*vector,ZyanUSizesize)
Resizes the given ZyanVector instance.

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

Returns
A zyan status code.

ZYCORE_EXPORTZyanStatusZyanVectorResizeEx(ZyanVector*vector,ZyanUSizesize,constvoid*initializer)
Resizes the given ZyanVector instance.

Parametersvector 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_EXPORTZyanStatusZyanVectorSet(ZyanVector*vector,ZyanUSizeindex,constvoid*value)
Assigns a new value to the element at the given index.

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

Returns
A zyan status code.

ZYCORE_EXPORTZyanStatusZyanVectorShrinkToFit(ZyanVector*vector)
Shrinks the capacity of the given vector to match it's size.

Parametersvector A pointer to the ZyanVector instance.

Returns
A zyan status code.

ZYCORE_EXPORTZyanStatusZyanVectorSwapElements(ZyanVector*vector,ZyanUSizeindex_first,ZyanUSizeindex_second)
Swaps the element at index_first with the element at index_second.

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

Macro Definition Documentation

#defineZYAN_VECTOR_DEFAULT_GROWTH_FACTOR2
       The default growth factor for all vector instances.

   #defineZYAN_VECTOR_DEFAULT_SHRINK_THRESHOLD4
       The default shrink threshold for all vector instances.

   #defineZYAN_VECTOR_FOREACH(type,vector,item_name,body)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.

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

   #defineZYAN_VECTOR_FOREACH_MUTABLE(type,vector,item_name,body)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.

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

   #defineZYAN_VECTOR_GET(type,vector,index)(*(consttype*)ZyanVectorGet(vector,index))
       Returns the value of the element at the given index.

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

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

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

Name

       include/Zycore/Vector.h

Synopsis

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

   Classes
       struct ZyanVector_Macros
       #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)

   Typedefs
       typedef struct ZyanVector_ZyanVectorFunctionsZYCORE_EXPORTZYAN_REQUIRES_LIBCZyanStatusZyanVectorInit (ZyanVector *vector, ZyanUSize element_size,
           ZyanUSize capacity, ZyanMemberProcedure destructor)
       ZYCORE_EXPORTZyanStatusZyanVectorInitEx (ZyanVector *vector, ZyanUSize element_size, ZyanUSize
           capacity, ZyanMemberProcedure destructor, ZyanAllocator *allocator, ZyanU8 growth_factor, ZyanU8
           shrink_threshold)
       ZYCORE_EXPORTZyanStatusZyanVectorInitCustomBuffer (ZyanVector *vector, ZyanUSize element_size, void
           *buffer, ZyanUSize capacity, ZyanMemberProcedure destructor)
       ZYCORE_EXPORTZyanStatusZyanVectorDestroy (ZyanVector *vector)
       ZYCORE_EXPORTZYAN_REQUIRES_LIBCZyanStatusZyanVectorDuplicate (ZyanVector *destination, const
           ZyanVector *source, ZyanUSize capacity)
       ZYCORE_EXPORTZyanStatusZyanVectorDuplicateEx (ZyanVector *destination, const ZyanVector *source,
           ZyanUSize capacity, ZyanAllocator *allocator, ZyanU8 growth_factor, ZyanU8 shrink_threshold)
       ZYCORE_EXPORTZyanStatusZyanVectorDuplicateCustomBuffer (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_EXPORTZyanStatusZyanVectorGetPointer (const ZyanVector *vector, ZyanUSize index, const void
           **value)
       ZYCORE_EXPORTZyanStatusZyanVectorGetPointerMutable (const ZyanVector *vector, ZyanUSize index, void
           **value)
       ZYCORE_EXPORTZyanStatusZyanVectorSet (ZyanVector *vector, ZyanUSize index, const void *value)
       ZYCORE_EXPORTZyanStatusZyanVectorPushBack (ZyanVector *vector, const void *element)
       ZYCORE_EXPORTZyanStatusZyanVectorInsert (ZyanVector *vector, ZyanUSize index, const void *element)
       ZYCORE_EXPORTZyanStatusZyanVectorInsertRange (ZyanVector *vector, ZyanUSize index, const void
           *elements, ZyanUSize count)
       ZYCORE_EXPORTZyanStatusZyanVectorEmplace (ZyanVector *vector, void **element, ZyanMemberFunction
           constructor)
       ZYCORE_EXPORTZyanStatusZyanVectorEmplaceEx (ZyanVector *vector, ZyanUSize index, void **element,
           ZyanMemberFunction constructor)
       ZYCORE_EXPORTZyanStatusZyanVectorSwapElements (ZyanVector *vector, ZyanUSize index_first, ZyanUSize
           index_second)
       ZYCORE_EXPORTZyanStatusZyanVectorDelete (ZyanVector *vector, ZyanUSize index)
       ZYCORE_EXPORTZyanStatusZyanVectorDeleteRange (ZyanVector *vector, ZyanUSize index, ZyanUSize count)
       ZYCORE_EXPORTZyanStatusZyanVectorPopBack (ZyanVector *vector)
       ZYCORE_EXPORTZyanStatusZyanVectorClear (ZyanVector *vector)
       ZYCORE_EXPORTZyanStatusZyanVectorFind (const ZyanVector *vector, const void *element, ZyanISize
           *found_index, ZyanEqualityComparison comparison)
       ZYCORE_EXPORTZyanStatusZyanVectorFindEx (const ZyanVector *vector, const void *element, ZyanISize
           *found_index, ZyanEqualityComparison comparison, ZyanUSize index, ZyanUSize count)
       ZYCORE_EXPORTZyanStatusZyanVectorBinarySearch (const ZyanVector *vector, const void *element, ZyanUSize
           *found_index, ZyanComparison comparison)
       ZYCORE_EXPORTZyanStatusZyanVectorBinarySearchEx (const ZyanVector *vector, const void *element,
           ZyanUSize *found_index, ZyanComparison comparison, ZyanUSize index, ZyanUSize count)
       ZYCORE_EXPORTZyanStatusZyanVectorResize (ZyanVector *vector, ZyanUSize size)
       ZYCORE_EXPORTZyanStatusZyanVectorResizeEx (ZyanVector *vector, ZyanUSize size, const void *initializer)
       ZYCORE_EXPORTZyanStatusZyanVectorReserve (ZyanVector *vector, ZyanUSize capacity)
       ZYCORE_EXPORTZyanStatusZyanVectorShrinkToFit (ZyanVector *vector)
       ZYCORE_EXPORTZyanStatusZyanVectorGetCapacity (const ZyanVector *vector, ZyanUSize *capacity)
       ZYCORE_EXPORTZyanStatusZyanVectorGetSize (const ZyanVector *vector, ZyanUSize *size)

Typedef Documentation

typedefstructZyanVector_ZyanVector
       Defines the ZyanVector struct.

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

include/Zycore/Vector.h

Contents

Author

Detailed Description

Function Documentation

Macro Definition Documentation

Name

Synopsis

Typedef Documentation

See Also