Zycore 1.4.0.0
|
#include <Zycore/Allocator.h>
#include <Zycore/Comparison.h>
#include <Zycore/Object.h>
#include <Zycore/Status.h>
#include <Zycore/Types.h>
Go to the source code of this file.
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_ | ZyanVector |
Implements the vector container class.
#define ZYAN_VECTOR_DEFAULT_GROWTH_FACTOR 2 |
The default growth factor for all vector instances.
#define ZYAN_VECTOR_DEFAULT_SHRINK_THRESHOLD 4 |
The default shrink threshold for all vector instances.
#define ZYAN_VECTOR_FOREACH | ( | type, | |
vector, | |||
item_name, | |||
body ) |
Loops through all elements of the vector.
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. |
#define ZYAN_VECTOR_FOREACH_MUTABLE | ( | type, | |
vector, | |||
item_name, | |||
body ) |
Loops through all elements of the vector.
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. |
#define ZYAN_VECTOR_GET | ( | type, | |
vector, | |||
index ) (*(const type*)ZyanVectorGet(vector, index)) |
Returns the value of the element at the given index
.
type | The desired value type. |
vector | A pointer to the ZyanVector instance. |
index | The element index. |
Note that this function is unsafe and might dereference a null-pointer.
#define ZYAN_VECTOR_INITIALIZER |
Defines an uninitialized ZyanVector
instance.
#define ZYAN_VECTOR_MIN_CAPACITY 1 |
The initial minimum capacity (number of elements) for all dynamically allocated vector instances.
typedef struct ZyanVector_ ZyanVector |
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.
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. |
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.
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 . |
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.
vector | A pointer to the ZyanVector instance. |
ZYCORE_EXPORT ZyanStatus ZyanVectorDelete | ( | ZyanVector * | vector, |
ZyanUSize | index ) |
Deletes the element at the given index
of the vector.
vector | A pointer to the ZyanVector instance. |
index | The element index. |
ZYCORE_EXPORT ZyanStatus ZyanVectorDeleteRange | ( | ZyanVector * | vector, |
ZyanUSize | index, | ||
ZyanUSize | count ) |
Deletes multiple elements from the given vector, starting at index
.
vector | A pointer to the ZyanVector instance. |
index | The index of the first element to delete. |
count | The number of elements to delete. |
ZYCORE_EXPORT ZyanStatus ZyanVectorDestroy | ( | ZyanVector * | vector | ) |
Destroys the given ZyanVector
instance.
vector | A pointer to the ZyanVector instance.. |
ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus ZyanVectorDuplicate | ( | ZyanVector * | destination, |
const ZyanVector * | source, | ||
ZyanUSize | capacity ) |
Initializes a new ZyanVector
instance by duplicating an existing vector.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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 . |
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
.
vector | A pointer to the ZyanVector instance. |
index | The element index. |
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.
vector | A pointer to the ZyanVector instance. |
capacity | Receives the size of the vector. |
ZYCORE_EXPORT void * ZyanVectorGetMutable | ( | const ZyanVector * | vector, |
ZyanUSize | index ) |
Returns a mutable pointer to the element at the given index
.
vector | A pointer to the ZyanVector instance. |
index | The element index. |
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
.
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.
ZYCORE_EXPORT ZyanStatus ZyanVectorGetPointerMutable | ( | const ZyanVector * | vector, |
ZyanUSize | index, | ||
void ** | value ) |
Returns a mutable pointer to the element at the given index
.
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.
ZYCORE_EXPORT ZyanStatus ZyanVectorGetSize | ( | const ZyanVector * | vector, |
ZyanUSize * | size ) |
Returns the current size of the vector.
vector | A pointer to the ZyanVector instance. |
size | Receives the size of the vector. |
ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus ZyanVectorInit | ( | ZyanVector * | vector, |
ZyanUSize | element_size, | ||
ZyanUSize | capacity, | ||
ZyanMemberProcedure | destructor ) |
Initializes the given ZyanVector
instance.
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. |
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.
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. |
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.
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. |
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.
vector | A pointer to the ZyanVector instance. |
index | The insert index. |
element | A pointer to the element to insert. |
ZYCORE_EXPORT ZyanStatus ZyanVectorInsertRange | ( | ZyanVector * | vector, |
ZyanUSize | index, | ||
const void * | elements, | ||
ZyanUSize | count ) |
Inserts multiple elements
at the given index
of the vector.
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. |
ZYCORE_EXPORT ZyanStatus ZyanVectorPopBack | ( | ZyanVector * | vector | ) |
Removes the last element of the vector.
vector | A pointer to the ZyanVector instance. |
ZYCORE_EXPORT ZyanStatus ZyanVectorPushBack | ( | ZyanVector * | vector, |
const void * | element ) |
Adds a new element
to the end of the vector.
vector | A pointer to the ZyanVector instance. |
element | A pointer to the element to add. |
ZYCORE_EXPORT ZyanStatus ZyanVectorReserve | ( | ZyanVector * | vector, |
ZyanUSize | capacity ) |
Changes the capacity of the given ZyanVector
instance.
vector | A pointer to the ZyanVector instance. |
capacity | The new minimum capacity of the vector. |
ZYCORE_EXPORT ZyanStatus ZyanVectorResize | ( | ZyanVector * | vector, |
ZyanUSize | size ) |
Resizes the given ZyanVector
instance.
vector | A pointer to the ZyanVector instance. |
size | The new size of the vector. |
ZYCORE_EXPORT ZyanStatus ZyanVectorResizeEx | ( | ZyanVector * | vector, |
ZyanUSize | size, | ||
const void * | initializer ) |
Resizes the given ZyanVector
instance.
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. |
ZYCORE_EXPORT ZyanStatus ZyanVectorSet | ( | ZyanVector * | vector, |
ZyanUSize | index, | ||
const void * | value ) |
Assigns a new value to the element at the given index
.
vector | A pointer to the ZyanVector instance. |
index | The value index. |
value | The value to assign. |
ZYCORE_EXPORT ZyanStatus ZyanVectorShrinkToFit | ( | ZyanVector * | vector | ) |
Shrinks the capacity of the given vector to match it's size.
vector | A pointer to the ZyanVector instance. |
ZYCORE_EXPORT ZyanStatus ZyanVectorSwapElements | ( | ZyanVector * | vector, |
ZyanUSize | index_first, | ||
ZyanUSize | index_second ) |
Swaps the element at index_first
with the element at index_second
.
vector | A pointer to the ZyanVector instance. |
index_first | The index of the first element. |
index_second | The index of the second element. |
This function requires the vector to have spare capacity for one temporary element. Call ZyanVectorReserve
before this function to increase capacity, if needed.