cl_vector.h File Reference

#include "allocator.h"
#include "cl_types.h"
#include "types.h"
#include <stdbool.h>

Go to the source code of this file.

Macros
#define	CL_VECTOR_FOREACH(__type, __name, __arr, ...)
	Macro to iterate over the elements of the vector.
#define	CL_VECTOR_FOREACH_PTR(__type, __name, __arr, ...)
	Macro to iterate over the elements of the vector with a pointer to the current element.

Typedefs
typedef struct __Vector	CL_Vector

Functions
CL_Vector *	CL_VectorAllocWithCapacity (MEM_Allocator *const alloc, u32 capacity, u32 elem_sz)
	Initializes the vector with allocated memory provided by the user.
CL_Vector *	CL_VectorAlloc (MEM_Allocator *const alloc, u32 elem_sz)
	Initializes the vector with a default capacity.
void	CL_VectorFree (CL_Vector *const arr)
	Frees the memory previously assigned to the vector.
CL_Error	CL_VectorPushBack (CL_Vector *const arr, const void *const elem, u32 *out_index)
	Adds an element at the end of the vector.
CL_Error	CL_VectorPushFront (CL_Vector *const arr, const void *const elem)
	Adds an element at the front of the vector.
void	CL_VectorPopBack (CL_Vector *const arr, void *out_elem)
	Removes the last element from the vector, optionally returning it.
void	CL_VectorPopFront (CL_Vector *const arr, void *out_elem)
	Removes the first element from the vector, optionally returning it.
CL_Error	CL_VectorGet (const CL_Vector *const arr, u32 index, void *out_elem)
	Gets an element at the specified index.
CL_Error	CL_VectorGetPtr (const CL_Vector *const arr, u32 index, void **out_elem)
	Gets a pointer to an element at the specified index.
CL_Error	CL_VectorGetLast (const CL_Vector *const arr, void *out_elem)
	Gets the last element from the vector.
CL_Error	CL_VectorGetLastPtr (const CL_Vector *const arr, void **out_elem)
	Gets a pointer to the last element from the vector.
CL_Error	CL_VectorInsert (CL_Vector *const arr, const void *const elem, u32 index)
	Inserts an element at the specified index.
CL_Error	CL_VectorRemove (CL_Vector *const arr, u32 index)
	Removes an element at the specified index.
void	CL_VectorClear (CL_Vector *const arr)
	Clears the vector.
bool	CL_VectorIsEmpty (const CL_Vector *const arr)
	Checks if the vector is empty.
u32	CL_VectorSize (const CL_Vector *const arr)
	Gets the size of the vector.
u32	CL_VectorCapacity (const CL_Vector *const arr)
	Gets the capacity of the vector.
void	CL_VectorSort (CL_Vector *arr, CL_CompareFn compare_fn)
	Sorts the vector.
bool	CL_VectorSearch (const CL_Vector *const arr, const void *elem, CL_CompareFn compare_fn, u32 *out_index)
	Searches for an element in the vector.

Macro Definition Documentation

CL_VECTOR_FOREACH

#define CL_VECTOR_FOREACH	(		__type,
			__name,
			__arr,
			...
	)

Value:

    for (u32 __i = 0; __i < CL_VectorSize(__arr); __i++)                                                               \
    {                                                                                                                  \
        __type __name;                                                                                                 \
        CL_VectorGet(__arr, __i, (void *)&__name);                                                                     \
        __VA_ARGS__                                                                                                    \
    }

Macro to iterate over the elements of the vector.

Parameters

__type	The type of the elements in the vector.
__name	The name of the variable to hold the current element.
__arr	The vector to iterate over.
...	The code to execute for each element.

Definition at line 20 of file cl_vector.h.

    {                                                                                                                  \
        __type __name;                                                                                                 \
        CL_VectorGet(__arr, __i, (void *)&__name);                                                                     \
        __VA_ARGS__                                                                                                    \
    }

CL_VECTOR_FOREACH_PTR

#define CL_VECTOR_FOREACH_PTR	(		__type,
			__name,
			__arr,
			...
	)

Value:

    for (u32 __i = 0; __i < CL_VectorSize(__arr); __i++)                                                               \
    {                                                                                                                  \
        __type *__name;                                                                                                \
        CL_VectorGetPtr(__arr, __i, (void **)&__name);                                                                 \
        __VA_ARGS__                                                                                                    \
    }

Macro to iterate over the elements of the vector with a pointer to the current element.

Parameters

__type	The type of the elements in the vector.
__name	The name of the variable to hold the current element.
__arr	The vector to iterate over.
...	The code to execute for each element.

Definition at line 33 of file cl_vector.h.

    {                                                                                                                  \
        __type *__name;                                                                                                \
        CL_VectorGetPtr(__arr, __i, (void **)&__name);                                                                 \
        __VA_ARGS__                                                                                                    \
    }

Typedef Documentation

CL_Vector

typedef struct __Vector CL_Vector

Definition at line 11 of file cl_vector.h.

Function Documentation

CL_VectorAlloc()

CL_Vector * CL_VectorAlloc	(	MEM_Allocator *const	alloc,
		u32	elem_sz
	)

Initializes the vector with a default capacity.

Parameters

alloc	The allocator to use for memory allocation.
elem_sz	The size of each element in the vector.

Returns

Pointer to the new vector or NULL on error.

Definition at line 59 of file cl_vector.c.

{
    return CL_VectorAllocWithCapacity(alloc, BASE_CAPACITY, elem_sz);
}

CL_VectorAllocWithCapacity()

CL_Vector * CL_VectorAllocWithCapacity	(	MEM_Allocator *const	alloc,
		u32	capacity,
		u32	elem_sz
	)

Initializes the vector with allocated memory provided by the user.

Parameters

alloc	The allocator to use for memory allocation.
capacity	The initial capacity of the vector.
elem_sz	The size of each element in the vector.

Returns

Pointer to the new vector or NULL on error.

Definition at line 33 of file cl_vector.c.

{
    if (!alloc || !capacity || !elem_sz)
        return NULL;
 
    CL_Vector *const arr = MEM_Alloc(alloc, sizeof(CL_Vector));
    if (!arr)
        return NULL;
 
    *arr = (CL_Vector){
        .data = MEM_Alloc(alloc, capacity * elem_sz),
        .size = 0,
        .capacity = capacity,
        .elem_size = elem_sz,
        .allocator = alloc,
    };
 
    if (!arr->data)
    {
        MEM_Free(alloc, arr);
        return NULL;
    }
 
    return arr;
}

CL_VectorCapacity()

u32 CL_VectorCapacity

(

const CL_Vector *const

arr

)

Gets the capacity of the vector.

Parameters

arr	The vector to get the capacity of.

Returns

The capacity of the vector.

Definition at line 238 of file cl_vector.c.

{
    return arr ? arr->capacity : 0;
}

CL_VectorClear()

void CL_VectorClear

(

CL_Vector *const

arr

)

Clears the vector.

Parameters

arr	The vector to clear.

Definition at line 219 of file cl_vector.c.

{
    if (!arr || !arr->size)
        return;
 
    // memset(arr->data, 0, arr->size * arr->elem_size); // Not necessary
    arr->size = 0;
}

CL_VectorFree()

void CL_VectorFree

(

CL_Vector *const

arr

)

Frees the memory previously assigned to the vector.

Parameters

arr	The vector to release the memory of.

Note

CL_Vector does not take ownership of the elements, so it's the user's responsibility to free them.

Definition at line 64 of file cl_vector.c.

{
    if (!arr)
        return;
 
    MEM_Free(arr->allocator, arr->data);
    MEM_Free(arr->allocator, arr);
}

CL_VectorGet()

CL_Error CL_VectorGet	(	const CL_Vector *const	arr,
		u32	index,
		void *	out_elem
	)

Gets an element at the specified index.

Parameters

arr	The vector to get the element from.
index	The index of the element to get.
out_elem	[OUTPUT] The element at the specified index.

Returns

CL_Error The error code.

Definition at line 126 of file cl_vector.c.

{
    if (!arr || !out_elem)
        return CL_ERR_INVALID_PARAMS;
 
    if (index >= arr->size || index < 0)
        return CL_ERR_OUT_OF_BOUNDS;
 
    if (arr->size == 0)
        return CL_ERR_EMPTY;
 
    const u32 offset = index * arr->elem_size;
    memcpy(out_elem, (u8 *)(arr->data) + offset, arr->elem_size);
    return CL_ERR_OK;
}

CL_VectorGetLast()

CL_Error CL_VectorGetLast	(	const CL_Vector *const	arr,
		void *	out_elem
	)

Gets the last element from the vector.

Parameters

arr	The vector to get the last element from.
out_elem	[OUTPUT] The last element.

Returns

CL_Error The error code.

Definition at line 158 of file cl_vector.c.

{
    if (arr->size == 0)
        return CL_ERR_EMPTY;
 
    return CL_VectorGet(arr, arr->size - 1, out_elem);
}

CL_VectorGetLastPtr()

CL_Error CL_VectorGetLastPtr	(	const CL_Vector *const	arr,
		void **	out_elem
	)

Gets a pointer to the last element from the vector.

Parameters

arr	The vector to get the last element from.
out_elem	[OUTPUT] The pointer to the last element.

Returns

CL_Error The error code.

Definition at line 166 of file cl_vector.c.

{
    if (arr->size == 0)
        return CL_ERR_EMPTY;
 
    return CL_VectorGetPtr(arr, arr->size - 1, out_elem);
}

CL_VectorGetPtr()

CL_Error CL_VectorGetPtr	(	const CL_Vector *const	arr,
		u32	index,
		void **	out_elem
	)

Gets a pointer to an element at the specified index.

Parameters

arr	The vector to get the element from.
index	The index of the element to get.
out_elem	[OUTPUT] The pointer to the element at the specified index.

Returns

CL_Error The error code.

Definition at line 142 of file cl_vector.c.

{
    if (!arr || !out_elem)
        return CL_ERR_INVALID_PARAMS;
 
    if (index >= arr->size || index < 0)
        return CL_ERR_OUT_OF_BOUNDS;
 
    if (arr->size == 0)
        return CL_ERR_EMPTY;
 
    const u32 offset = index * arr->elem_size;
    *out_elem = (u8 *)(arr->data) + offset;
    return CL_ERR_OK;
}

CL_VectorInsert()

CL_Error CL_VectorInsert	(	CL_Vector *const	arr,
		const void *const	elem,
		u32	index
	)

Inserts an element at the specified index.

Parameters

arr	The vector to insert the element to.
elem	The element to insert.
index	The index to insert the element at.

Returns

CL_Error The error code.

Note

This operation is not O(1) for vectors. Consider using a list if you need frequent insertions.

Definition at line 174 of file cl_vector.c.

{
    if (!arr || !elem)
        return CL_ERR_INVALID_PARAMS;
 
    if (index > arr->size || index < 0)
        return CL_ERR_OUT_OF_BOUNDS;
 
    if (arr->size >= arr->capacity)
    {
        const u32 new_cap = arr->capacity * RESZ_FACTOR;
        if (!realloc_data(arr, new_cap))
            return CL_ERR_NO_MEMORY;
    }
 
    const u32 where_offset = index * arr->elem_size;
    const u32 next_offset = where_offset + arr->elem_size;
 
    // Shift the elements to the right, in order to make space for the new element
    memmove((u8 *)arr->data + next_offset, (u8 *)arr->data + where_offset, (arr->size - index) * arr->elem_size);
    memcpy((u8 *)arr->data + where_offset, elem, arr->elem_size);
    arr->size++;
    return CL_ERR_OK;
}

CL_VectorIsEmpty()

bool CL_VectorIsEmpty

(

const CL_Vector *const

arr

)

Checks if the vector is empty.

Parameters

arr	The vector to check.

Returns

true if the vector is empty, false otherwise.

Definition at line 228 of file cl_vector.c.

{
    return arr ? arr->size == 0 : true;
}

CL_VectorPopBack()

void CL_VectorPopBack	(	CL_Vector *const	arr,
		void *	out_elem
	)

Removes the last element from the vector, optionally returning it.

Parameters

arr	The vector to remove the last element from.
out_elem	[OUTPUT] The removed element, if not NULL.

Definition at line 102 of file cl_vector.c.

{
    if (!arr || !arr->size)
        return;
 
    const u32 offset = (arr->size - 1) * arr->elem_size;
    if (out_elem)
        memcpy(out_elem, (u8 *)(arr->data) + offset, arr->elem_size);
 
    // memset((u8 *)(arr->data) + offset, 0, arr->elem_size); // Not necessary
    arr->size--;
}

CL_VectorPopFront()

void CL_VectorPopFront	(	CL_Vector *const	arr,
		void *	out_elem
	)

Removes the first element from the vector, optionally returning it.

Parameters

arr	The vector to remove the first element from.
out_elem	[OUTPUT] The removed element, if not NULL.

Note

This operation is not O(1) for vectors. Consider using a list if you need frequent removals at the front.

Definition at line 115 of file cl_vector.c.

{
    if (!arr || !arr->size)
        return;
 
    if (out_elem)
        CL_VectorGet(arr, 0, out_elem);
 
    CL_VectorRemove(arr, 0);
}

CL_VectorPushBack()

CL_Error CL_VectorPushBack	(	CL_Vector *const	arr,
		const void *const	elem,
		u32 *	out_index
	)

Adds an element at the end of the vector.

Parameters

arr	The vector to add the element to.
elem	The element to add.
out_index	[OUTPUT] The index of the added element, if not NULL.

Returns

CL_Error The error code.

Definition at line 73 of file cl_vector.c.

{
    if (!arr || !elem)
        return CL_ERR_INVALID_PARAMS;
 
    // Checking if the array can hold the element
    if (arr->size >= arr->capacity)
    {
        const u32 new_cap = arr->capacity * RESZ_FACTOR;
        if (!realloc_data(arr, new_cap))
            return CL_ERR_NO_MEMORY;
    }
 
    const u32 offset = arr->size * arr->elem_size;
    memcpy((u8 *)(arr->data) + offset, elem, arr->elem_size);
    arr->size++;
 
    if (out_index)
        *out_index = arr->size - 1;
 
    return CL_ERR_OK;
}

CL_VectorPushFront()

CL_Error CL_VectorPushFront	(	CL_Vector *const	arr,
		const void *const	elem
	)

Adds an element at the front of the vector.

Parameters

arr	The vector to add the element to.
elem	The element to add.

Returns

CL_Error The error code.

Note

This operation is not O(1) for vectors. Consider using a list if you need frequent insertions at the front.

Definition at line 96 of file cl_vector.c.

{
    // Inserting at the front is equivalent to inserting at index 0
    return CL_VectorInsert(arr, elem, 0);
}

CL_VectorRemove()

CL_Error CL_VectorRemove	(	CL_Vector *const	arr,
		u32	index
	)

Removes an element at the specified index.

Parameters

arr	The vector to remove the element from.
index	The index to remove the element from.

Returns

CL_Error The error code.

Note

This operation is not O(1) for vectors. Consider using a list if you need frequent removald in the middle.

Definition at line 199 of file cl_vector.c.

{
    if (!arr)
        return CL_ERR_INVALID_PARAMS;
 
    if (index >= arr->size || index < 0)
        return CL_ERR_OUT_OF_BOUNDS;
 
    if (arr->size == 0)
        return CL_ERR_EMPTY;
 
    const u32 where_offset = index * arr->elem_size;
    const u32 next_offset = where_offset + arr->elem_size;
 
    // Shift the elements to the left, in order to remove the element
    memmove((u8 *)arr->data + where_offset, (u8 *)arr->data + next_offset, (arr->size - index - 1) * arr->elem_size);
    arr->size--;
    return CL_ERR_OK;
}

CL_VectorSearch()

bool CL_VectorSearch	(	const CL_Vector *const	arr,
		const void *	elem,
		CL_CompareFn	compare_fn,
		u32 *	out_index
	)

Searches for an element in the vector.

Parameters

arr	The vector to search in.
elem	The element to search for.
compare_fn	The comparison function.
out_index	[OUTPUT] The index of the element, if found and not NULL.

Returns

true if the element was found, false otherwise.

Definition at line 251 of file cl_vector.c.

{
    if (!arr || !elem || !compare_fn)
        return false;
 
    u32 offset;
    for (u32 i = 0; i < arr->size; i++)
    {
        offset = i * arr->elem_size;
        if (!compare_fn(elem, (u8 *)(arr->data) + offset))
        {
            if (out_index)
                *out_index = i;
 
            return true;
        }
    }
 
    return false;
}

CL_VectorSize()

u32 CL_VectorSize

(

const CL_Vector *const

arr

)

Gets the size of the vector.

Parameters

arr	The vector to get the size of.

Returns

The size of the vector.

Definition at line 233 of file cl_vector.c.

{
    return arr ? arr->size : 0;
}

CL_VectorSort()

void CL_VectorSort	(	CL_Vector *	arr,
		CL_CompareFn	compare_fn
	)

Sorts the vector.

Parameters

arr	The vector to sort.
compare_fn	The comparison function.

Definition at line 243 of file cl_vector.c.

{
    if (!arr || !cmp || arr->size < 2)
        return;
 
    qsort(arr->data, arr->size, arr->elem_size, cmp);
}