This files contains an implementation of a dynamic array. More...

#include "defines.h"

Macros
#define	DARRAY_DEFAULT_CAPACITY 1
	The default darray capacity. More...

#define	DARRAY_RESIZE_FACTOR 2
	The default resize factor (doubles on resize) More...

#define	darray_create(type) _darray_create(DARRAY_DEFAULT_CAPACITY, sizeof(type), 0)
	Creates a new darray of the given type with the default capacity. Performs a dynamic memory allocation. More...

#define	darray_create_with_allocator(type, allocator) _darray_create(DARRAY_DEFAULT_CAPACITY, sizeof(type), allocator)
	Creates a new darray of the given type with the default capacity. Performs a dynamic memory allocation. More...

#define	darray_reserve(type, capacity) _darray_create(capacity, sizeof(type), 0)
	Creates a new darray of the given type with the provided capacity. Performs a dynamic memory allocation. More...

#define	darray_reserve_with_allocator(type, capacity, allocator) _darray_create(capacity, sizeof(type), allocator)
	Creates a new darray of the given type with the provided capacity. Performs a dynamic memory allocation. More...

#define	darray_push(array, value)
	Pushes a new entry to the given array. Resizes if necessary. More...

#define	darray_insert_at(array, index, value)
	Inserts a copy of the given value into the supplied array at the given index. Triggers an array resize if required. More...

Functions
KAPI void *	_darray_create (u64 length, u64 stride, struct frame_allocator_int *frame_allocator)
	Creates a new darray of the given length and stride. Note that this performs a dynamic memory allocation. More...

KAPI void *	_darray_resize (void *array)
	Resizes the given array using internal resizing amounts. Causes a new allocation. More...

KAPI void *	_darray_push (void array, const void value_ptr)
	Pushes a new entry to the given array. Resizes if necessary. More...

KAPI void *	_darray_insert_at (void array, u64 index, void value_ptr)
	Inserts a copy of the given value into the supplied array at the given index. Triggers an array resize if required. More...

KAPI void	darray_destroy (void *array)
	Destroys the provided array, freeing any memory allocated by it. More...

KAPI void	darray_pop (void array, void value_ptr)
	Pops an entry out of the array and places it into dest. More...

KAPI void *	darray_pop_at (void array, u64 index, void value_ptr)
	Pops an entry out of the array at the given index and places it into dest. Brings in all entries after the popped index in by one. More...

KAPI void	darray_clear (void *array)
	Clears all entries from the array. Does not release any internally-allocated memory. More...

KAPI u64	darray_capacity (void *array)
	Gets the given array's capacity. More...

KAPI u64	darray_length (void *array)
	Gets the length (number of elements) in the given array. More...

KAPI u64	darray_stride (void *array)
	Gets the stride (element size) of the given array. More...

KAPI void	darray_length_set (void *array, u64 value)
	Sets the length of the given array. This ensures the array has the required capacity to be able to set entries directly, for instance. Can trigger an internal reallocation. More...

Detailed Description

This files contains an implementation of a dynamic array.

Author: Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

Memory layout:

u64 capacity = number elements that can be held.
u64 length = number of elements currently contained
u64 stride = size of each element in bytes
void* elements
Version
2.0

Date
2023-08-30

Copyright
Kohi Game Engine is Copyright (c) Travis Vroman 2021-2023

Macro Definition Documentation

◆ darray_create

#define darray_create ( type ) _darray_create(DARRAY_DEFAULT_CAPACITY, sizeof(type), 0)

Creates a new darray of the given type with the default capacity. Performs a dynamic memory allocation.

Parameters

type	The type to be used to create the darray.

Returns: A pointer to the array's memory block.

◆ darray_create_with_allocator

#define darray_create_with_allocator	(	type,
		allocator
	)	_darray_create(DARRAY_DEFAULT_CAPACITY, sizeof(type), allocator)

Creates a new darray of the given type with the default capacity. Performs a dynamic memory allocation.

Parameters

type	The type to be used to create the darray.
allocator	A pointer to a frame allocator.

Returns: A pointer to the array's memory block.

◆ DARRAY_DEFAULT_CAPACITY

#define DARRAY_DEFAULT_CAPACITY 1

The default darray capacity.

◆ darray_insert_at

#define darray_insert_at	(	array,
		index,
		value
	)

Value:

    {                                                   \
        typeof(value) temp = value;                     \
        array = _darray_insert_at(array, index, &temp); \
    }

Inserts a copy of the given value into the supplied array at the given index. Triggers an array resize if required.

Parameters

array	The array to insert into.
index	The index to insert at.
value_ptr	A pointer holding the value to be inserted.

Returns: The array block.

◆ darray_push

#define darray_push	(	array,
		value
	)

Value:

    {                                       \
        typeof(value) temp = value;         \
        array = _darray_push(array, &temp); \
    }

Pushes a new entry to the given array. Resizes if necessary.

Parameters

array	The array to be pushed to.
value	The value to be pushed. A copy of this value is taken.

Returns: A pointer to the array block.

◆ darray_reserve

#define darray_reserve	(	type,
		capacity
	)	_darray_create(capacity, sizeof(type), 0)

Creates a new darray of the given type with the provided capacity. Performs a dynamic memory allocation.

Parameters

type	The type to be used to create the darray.
capacity	The number of elements the darray can initially hold (can be resized).

Returns: A pointer to the array's memory block.

◆ darray_reserve_with_allocator

#define darray_reserve_with_allocator	(	type,
		capacity,
		allocator
	)	_darray_create(capacity, sizeof(type), allocator)

Creates a new darray of the given type with the provided capacity. Performs a dynamic memory allocation.

Parameters

type	The type to be used to create the darray.
capacity	The number of elements the darray can initially hold (can be resized).
allocator	A pointer to a frame allocator.

Returns: A pointer to the array's memory block.

◆ DARRAY_RESIZE_FACTOR

#define DARRAY_RESIZE_FACTOR 2

The default resize factor (doubles on resize)

Function Documentation

◆ _darray_create()

KAPI void* _darray_create	(	u64	length,
		u64	stride,
		struct frame_allocator_int *	frame_allocator
	)

Creates a new darray of the given length and stride. Note that this performs a dynamic memory allocation.

Note: Avoid using this directly; use the darray_create macro instead.

Parameters

length	The default number of elements in the array.
stride	The size of each array element.

Returns: A pointer representing the block of memory containing the array.

◆ _darray_insert_at()

KAPI void* _darray_insert_at	(	void *	array,
		u64	index,
		void *	value_ptr
	)

Inserts a copy of the given value into the supplied array at the given index. Triggers an array resize if required.

Note: Avoid using this directly; call the darray_insert_at macro instead.

Parameters

array	The array to insert into.
index	The index to insert at.
value_ptr	A pointer holding the value to be inserted.

Returns: The array block.

◆ _darray_push()

KAPI void* _darray_push	(	void *	array,
		const void *	value_ptr
	)

Pushes a new entry to the given array. Resizes if necessary.

Note: Avoid using this directly; call the darray_push macro instead.

Parameters

array	The array to be pushed to.
value_ptr	A pointer to the value to be pushed. A copy of this value is taken.

Returns: A pointer to the array block.

◆ _darray_resize()

KAPI void* _darray_resize ( void * array )

Resizes the given array using internal resizing amounts. Causes a new allocation.

Note: This is an internal implementation detail and should not be called directly.

Parameters

array The array to be resized.

Returns: A pointer to the resized array block.

◆ darray_capacity()

KAPI u64 darray_capacity ( void * array )

Gets the given array's capacity.

Parameters

array The array whose capacity to retrieve.

Returns: The capacity of the given array.

◆ darray_clear()

KAPI void darray_clear ( void * array )

Clears all entries from the array. Does not release any internally-allocated memory.

Parameters

array The array to be cleared.

◆ darray_destroy()

KAPI void darray_destroy ( void * array )

Destroys the provided array, freeing any memory allocated by it.

Parameters

array The array to be destroyed.

◆ darray_length()

KAPI u64 darray_length ( void * array )

Gets the length (number of elements) in the given array.

Parameters

array The array to obtain the length of.

Returns: The length of the given array.

◆ darray_length_set()

KAPI void darray_length_set	(	void *	array,
		u64	value
	)

Sets the length of the given array. This ensures the array has the required capacity to be able to set entries directly, for instance. Can trigger an internal reallocation.

Parameters

array	The array to set the length of.
value	The length to set the array to.

◆ darray_pop()

KAPI void darray_pop	(	void *	array,
		void *	value_ptr
	)

Pops an entry out of the array and places it into dest.

Parameters

array	The array to pop from.
dest	A pointer to hold the popped value.

◆ darray_pop_at()

KAPI void* darray_pop_at	(	void *	array,
		u64	index,
		void *	value_ptr
	)

Pops an entry out of the array at the given index and places it into dest. Brings in all entries after the popped index in by one.

Parameters

array	The array to pop from.
index	The index to pop from.
dest	A pointer to hold the popped value.

Returns: The array block.

◆ darray_stride()

KAPI u64 darray_stride ( void * array )

Gets the stride (element size) of the given array.

Parameters

array The array to obtain the stride of.

Returns: The stride of the given array.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ darray_create

◆ darray_create_with_allocator

◆ DARRAY_DEFAULT_CAPACITY

◆ darray_insert_at

◆ darray_push

◆ darray_reserve

◆ darray_reserve_with_allocator

◆ DARRAY_RESIZE_FACTOR

Function Documentation

◆ _darray_create()

◆ _darray_insert_at()

◆ _darray_push()

◆ _darray_resize()

◆ darray_capacity()

◆ darray_clear()

◆ darray_destroy()

◆ darray_length()

◆ darray_length_set()

◆ darray_pop()

◆ darray_pop_at()

◆ darray_stride()