Kohi Game Engine
Data Structures | Macros | Typedefs | Functions
darray.h File Reference

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

#include "defines.h"

Go to the source code of this file.

Data Structures

struct  darray_header
 
struct  darray_base
 
struct  darray_iterator
 

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)    (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...
 
#define darray_duplicate(type, array)   (type*)_darray_duplicate(sizeof(type), array)
 Duplicates the given array to a completely fresh copy, including header data as well as actual data contained within. More...
 
#define DARRAY_TYPE_NAMED(type, name)
 
#define DARRAY_TYPE(type)   DARRAY_TYPE_NAMED(type, type)
 

Typedefs

typedef struct darray_header darray_header
 
typedef struct darray_base darray_base
 
typedef struct darray_iterator darray_iterator
 

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_duplicate (u64 stride, void *array)
 Duplicates the given array to a completely fresh copy, including header data as well as actual data contained within. 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 *dest)
 Pops an entry out of the array and places it into dest (if provided). More...
 
KAPI void * darray_pop_at (void *array, u64 index, void *dest)
 Pops an entry out of the array at the given index and places it into dest (if provided). 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...
 
KAPI void _kdarray_init (u32 length, u32 stride, u32 capacity, struct frame_allocator_int *allocator, u32 *out_length, u32 *out_stride, u32 *out_capacity, void **block, struct frame_allocator_int **out_allocator)
 
KAPI void _kdarray_free (u32 *length, u32 *capacity, u32 *stride, void **block, struct frame_allocator_int **out_allocator)
 
KAPI void _kdarray_ensure_size (u32 required_length, u32 stride, u32 *out_capacity, struct frame_allocator_int *allocator, void **block, void **base_block)
 
KAPI darray_iterator darray_iterator_begin (darray_base *arr)
 
KAPI darray_iterator darray_iterator_rbegin (darray_base *arr)
 
KAPI b8 darray_iterator_end (const darray_iterator *it)
 
KAPI void * darray_iterator_value (const darray_iterator *it)
 
KAPI void darray_iterator_next (darray_iterator *it)
 
KAPI void darray_iterator_prev (darray_iterator *it)
 
 DARRAY_TYPE (b8)
 
 DARRAY_TYPE (u8)
 
 DARRAY_TYPE (u16)
 
 DARRAY_TYPE (u32)
 
 DARRAY_TYPE (u64)
 
 DARRAY_TYPE (i8)
 
 DARRAY_TYPE (i16)
 
 DARRAY_TYPE (i32)
 
 DARRAY_TYPE (i64)
 
 DARRAY_TYPE (f32)
 
 DARRAY_TYPE (f64)
 
 DARRAY_TYPE_NAMED (const char *, string)
 

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. (8 bytes)
  • u64 length = number of elements currently contained (8 bytes)
  • u64 stride = size of each element in bytes (8 bytes)
  • void* allocator (if used, otherwise 0) (8 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)     (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
typeThe 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
typeThe type to be used to create the darray.
allocatorA 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_duplicate

#define darray_duplicate (   type,
  array 
)    (type*)_darray_duplicate(sizeof(type), array)

Duplicates the given array to a completely fresh copy, including header data as well as actual data contained within.

Performs a dynamic memory allocation.

Parameters
typeThe type to be used to duplicate the darray. Used for size verification.
arrayThe array to be duplicated.
Returns
A pointer to the array's memory block.

◆ darray_insert_at

#define darray_insert_at (   array,
  index,
  value 
)
Value:
{ \
typeof(value) __k_temp_dingus_value__ = value; \
array = _darray_insert_at(array, index, &__k_temp_dingus_value__); \
}
_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 resiz...

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

Parameters
arrayThe array to insert into.
indexThe index to insert at.
value_ptrA pointer holding the value to be inserted.
Returns
The array block.

◆ darray_push

#define darray_push (   array,
  value 
)
Value:
{ \
typeof(value) __k_temp_dingus_value__ = value; \
array = _darray_push(array, &__k_temp_dingus_value__); \
}
_darray_push
KAPI void * _darray_push(void *array, const void *value_ptr)
Pushes a new entry to the given array. Resizes if necessary.

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

Parameters
arrayThe array to be pushed to.
valueThe 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
typeThe type to be used to create the darray.
capacityThe 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
typeThe type to be used to create the darray.
capacityThe number of elements the darray can initially hold (can be resized).
allocatorA 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)

◆ DARRAY_TYPE

#define DARRAY_TYPE (   type)    DARRAY_TYPE_NAMED(type, type)

◆ DARRAY_TYPE_NAMED

#define DARRAY_TYPE_NAMED (   type,
  name 
)

Typedef Documentation

◆ darray_base

typedef struct darray_base darray_base

◆ darray_header

typedef struct darray_header darray_header

◆ darray_iterator

typedef struct darray_iterator darray_iterator

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
lengthThe default number of elements in the array.
strideThe size of each array element.
Returns
A pointer representing the block of memory containing the array.

◆ _darray_duplicate()

KAPI void* _darray_duplicate ( u64  stride,
void *  array 
)

Duplicates the given array to a completely fresh copy, including header data as well as actual data contained within.

Performs a dynamic memory allocation.

Parameters
typeThe type to be used to duplicate the darray. Used for size verification.
arrayThe array to be duplicated.
Returns
A pointer to the array's memory block.

◆ _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
arrayThe array to insert into.
indexThe index to insert at.
value_ptrA 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
arrayThe array to be pushed to.
value_ptrA 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
arrayThe array to be resized.
Returns
A pointer to the resized array block.

◆ _kdarray_ensure_size()

KAPI void _kdarray_ensure_size ( u32  required_length,
u32  stride,
u32 *  out_capacity,
struct frame_allocator_int *  allocator,
void **  block,
void **  base_block 
)

◆ _kdarray_free()

KAPI void _kdarray_free ( u32 *  length,
u32 *  capacity,
u32 *  stride,
void **  block,
struct frame_allocator_int **  out_allocator 
)

◆ _kdarray_init()

KAPI void _kdarray_init ( u32  length,
u32  stride,
u32  capacity,
struct frame_allocator_int *  allocator,
u32 *  out_length,
u32 *  out_stride,
u32 *  out_capacity,
void **  block,
struct frame_allocator_int **  out_allocator 
)

NEW DARRAY

◆ darray_capacity()

KAPI u64 darray_capacity ( void *  array)

Gets the given array's capacity.

Parameters
arrayThe 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
arrayThe array to be cleared.

◆ darray_destroy()

KAPI void darray_destroy ( void *  array)

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

Parameters
arrayThe array to be destroyed.

◆ darray_iterator_begin()

KAPI darray_iterator darray_iterator_begin ( darray_base *  arr)

◆ darray_iterator_end()

KAPI b8 darray_iterator_end ( const darray_iterator *  it)

◆ darray_iterator_next()

KAPI void darray_iterator_next ( darray_iterator *  it)

◆ darray_iterator_prev()

KAPI void darray_iterator_prev ( darray_iterator *  it)

◆ darray_iterator_rbegin()

KAPI darray_iterator darray_iterator_rbegin ( darray_base *  arr)

◆ darray_iterator_value()

KAPI void* darray_iterator_value ( const darray_iterator *  it)

◆ darray_length()

KAPI u64 darray_length ( void *  array)

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

Parameters
arrayThe 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
arrayThe array to set the length of.
valueThe length to set the array to.

◆ darray_pop()

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

Pops an entry out of the array and places it into dest (if provided).

Parameters
arrayThe array to pop from.
destA pointer to hold the popped value. Optional.

◆ darray_pop_at()

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

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

Parameters
arrayThe array to pop from.
indexThe index to pop from.
destA pointer to hold the popped value. Optional.
Returns
The array block.

◆ darray_stride()

KAPI u64 darray_stride ( void *  array)

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

Parameters
arrayThe array to obtain the stride of.
Returns
The stride of the given array.

◆ DARRAY_TYPE() [1/11]

DARRAY_TYPE ( b8  )

◆ DARRAY_TYPE() [2/11]

DARRAY_TYPE ( f32  )

◆ DARRAY_TYPE() [3/11]

DARRAY_TYPE ( f64  )

◆ DARRAY_TYPE() [4/11]

DARRAY_TYPE ( i16  )

◆ DARRAY_TYPE() [5/11]

DARRAY_TYPE ( i32  )

◆ DARRAY_TYPE() [6/11]

DARRAY_TYPE ( i64  )

◆ DARRAY_TYPE() [7/11]

DARRAY_TYPE ( i8  )

◆ DARRAY_TYPE() [8/11]

DARRAY_TYPE ( u16  )

◆ DARRAY_TYPE() [9/11]

DARRAY_TYPE ( u32  )

◆ DARRAY_TYPE() [10/11]

DARRAY_TYPE ( u64  )

◆ DARRAY_TYPE() [11/11]

DARRAY_TYPE ( u8  )

◆ DARRAY_TYPE_NAMED()

DARRAY_TYPE_NAMED ( const char *  ,
string   
)