dynarr.h File Reference

A dynamic array. (also called List, Vector or ArrayList) More...

#include "../headers/array_printf.h"
#include "../headers/attributes.h"
#include <stdbool.h>
#include <stdint.h>

Go to the source code of this file.

Macros
#define	list_init_type(TYPE)
#define	list_fetch(LIST, IDX, TYPE)
#define	list_access(LIST, IDX, TYPE)
#define	list_printf_sde(LIST, ITEM_TYPE, FORMAT, START_STR, DELIM, END_STR)
#define	list_printf_d(LIST, ITEM_TYPE, FORMAT, DELIM)
#define	list_printf(LIST, ITEM_TYPE, FORMAT)
#define	list_sprintf_d(STRING, LIST, TYPE, FMTSTR, DELIM)
#define	list_sprintf(STRING, LIST, TYPE, FMTSTR)

Typedefs
typedef struct dynamic_array	List

Functions
Constructor struct dynamic_array *	list_init_size (size_t el_size)
Constructor struct dynamic_array *	list_init_cap_size (size_t el_size, size_t init_cap)
int	list_copy (const struct dynamic_array *old, struct dynamic_array **new_ls_container)
Constructor struct dynamic_array *	list_copy_of (const struct dynamic_array *)
const void *	list_see (const struct dynamic_array *ls, size_t idx)
const void *	list_peek (const struct dynamic_array *ls)
void *	list_at (struct dynamic_array *, size_t idx)
void *	list_at_last (struct dynamic_array *)
int	list_set_at (struct dynamic_array *, size_t index, const void *data)
int	list_extend (struct dynamic_array *ls, const void *array, size_t array_len)
int	list_extend_list (struct dynamic_array *ls, const struct dynamic_array *app)
int	list_append (struct dynamic_array *, const void *datap)
int	list_insert (struct dynamic_array *, size_t index, const void *data)
int	list_pop (struct dynamic_array *, void *container)
int	list_remove_fast (struct dynamic_array *, size_t index, void *container)
int	list_remove (struct dynamic_array *, size_t index, void *container)
const void *	list_bsearch_p (const struct dynamic_array *, const void *needle, int(*cmp)(const void *, const void *))
int64_t	list_bsearch_i (const struct dynamic_array *, const void *needle, int(*cmp)(const void *, const void *))
const void *	list_lsearch_p (const struct dynamic_array *, const void *needle)
int64_t	list_lsearch_i (const struct dynamic_array *, const void *needle)
void	list_sort (struct dynamic_array *ls, int(*cmp)(const void *, const void *))
int	list_reverse (struct dynamic_array *)
Constructor struct dynamic_array *	list_reversed (const struct dynamic_array *)
int	list_cmp_size (const void *l1, const void *l2)
int	list_cmp_elsize (const void *l1, const void *l2)
void	list_destroy (struct dynamic_array *)
int	list_clear (struct dynamic_array *ls)
bool	list_is_empty (const struct dynamic_array *)
	Returns true if list is empty.
size_t	list_size (const struct dynamic_array *)
	Returns number of elements in the list.
size_t	list_el_size (const struct dynamic_array *)
	Returns sizeof elements (e.g. if list element type is char, returns 1)
const void *	list_items (const struct dynamic_array *)
UseResult void *	list_items_copy (const struct dynamic_array *)

Detailed Description

A dynamic array. (also called List, Vector or ArrayList)

The List can store any elements of arbitrary size.

A new List can (and should) be created with list_init_* functions

list_init_type() function takes as its type argument the C keyword e.g. char
list_init_size() function takes as its el_size argument the number of bytes (acquired by sizeof) for the desired type to be stored

list_init_* functions allocate and initialize a List with these default values:

List::capacity = LIST_DEF_CAP
List::size     = 0
List::items    = pointer to heap allocated memory of width ‹capacity›, set to 0
List::el_size  = width of a single element

Finalization (destruction) of a List is done with list_destroy().

Attention

All elements must be the same number of bytes long

Macro Definition Documentation

list_access

#define list_access	(		LIST,
			IDX,
			TYPE )

Value:

( *( ( TYPE * ) list_at( ( LIST ), ( IDX ) ) ) )

Accesses the list as if it was an array – like ARRAY[IDX] => assignment is possible. Type must be the same as the list element type.

OOB index dereferences a NULL pointer (so don't do that).

list_fetch

#define list_fetch	(		LIST,
			IDX,
			TYPE )

Value:

    ( *( ( const TYPE * ) list_see( ( LIST ), ( IDX ) ) ) )

Fetches an item at the specified index. Type must be the same as the list element type.

OOB index dereferences a NULL pointer (so don't do that).

list_init_type

#define list_init_type

(

TYPE

)

Value:

list_init_size( sizeof( TYPE ) )

Initializes the List to be of type TYPE

list_printf

#define list_printf	(		LIST,
			ITEM_TYPE,
			FORMAT )

Value:

    array_printf( list_items( LIST ), list_size( LIST ), ITEM_TYPE, FORMAT )

See also

array_fprintf_sde

list_printf_d

#define list_printf_d	(		LIST,
			ITEM_TYPE,
			FORMAT,
			DELIM )

Value:

    array_printf_d( list_items( LIST ), list_size( LIST ), ITEM_TYPE, FORMAT, DELIM )

See also

array_fprintf_sde

list_printf_sde

#define list_printf_sde	(		LIST,
			ITEM_TYPE,
			FORMAT,
			START_STR,
			DELIM,
			END_STR )

Value:

    array_printf_sde( list_items( LIST ),                                     \
                      list_size( LIST ),                                      \
                      ITEM_TYPE,                                              \
                      FORMAT,                                                 \
                      START_STR,                                              \
                      DELIM,                                                  \
                      END_STR )

See also

array_fprintf_sde

list_sprintf

#define list_sprintf	(		STRING,
			LIST,
			TYPE,
			FMTSTR )

Value:

    array_sprintf( STRING, list_items( LIST ), list_size( LIST ), TYPE, FMTSTR )

See also

array_sprintf_sde

list_sprintf_d

#define list_sprintf_d	(		STRING,
			LIST,
			TYPE,
			FMTSTR,
			DELIM )

Value:

    array_sprintf_d( STRING, list_items( LIST ), list_size( LIST ), TYPE, FMTSTR, DELIM )

See also

array_sprintf_sde

Typedef Documentation

List

typedef struct dynamic_array List

Function Documentation

list_append()

int list_append	(	struct dynamic_array *	,
		const void *	datap )

Appends an element to the end of the List.

The function assumes data is of the same type as the List.

Example:

List ls = list_init_type( int );
int number = 123;
list_append( ls, &number ); // note the `&`
// or
List ls_outer = list_init_type( List );
List ls_inner = list_init_type( char );
list_append( ls_outer, &ls_inner );

Returns

RV_ERROR if reallocation fails, RV_SUCCESS otherwise

list_at()

void * list_at	(	struct dynamic_array *	,
		size_t	idx )

Gets a mutable look of the element at the specified index

Returns

pointer to the element

list_at_last()

void * list_at_last

(

struct dynamic_array *

)

Gets a mutable look of the last element

Returns

pointer to the last element

list_bsearch_i()

int64_t list_bsearch_i	(	const struct dynamic_array *	,
		const void *	needle,
		int(*	cmp )(const void *, const void *) )

Binary search, returns index (-1 if not found)

list_bsearch_p()

const void * list_bsearch_p	(	const struct dynamic_array *	,
		const void *	needle,
		int(*	cmp )(const void *, const void *) )

Binary search, returns pointer (NULL if not found)

list_clear()

int list_clear

(

struct dynamic_array *

ls

)

Resets the list to the defaults

list_cmp_elsize()

int list_cmp_elsize	(	const void *	l1,
		const void *	l2 )

Compares the lists based on the size of elements, similar to memcmp/strcmp

list_cmp_size()

int list_cmp_size	(	const void *	l1,
		const void *	l2 )

Compares the lists based on the number of elements, similar to memcmp/strcmp

list_copy()

int list_copy	(	const struct dynamic_array *	old,
		struct dynamic_array **	new_ls_container )

Creates a copy of the List and stores it in new_ls_container

Parameters

old	old List to be copied
new_ls_container	pointer to your place in memory to store a List pointer

Returns

RV_ERROR if an error occurs, else RV_SUCCESS

list_copy_of()

Constructor struct dynamic_array * list_copy_of

(

const struct dynamic_array *

)

Creates a copy of the original List

Returns

newly allocated list pointer (see list_init_*) with a shallow copy of the data inside. This list may be passed to list_destroy()

list_destroy()

void list_destroy

(

struct dynamic_array *

)

Frees all memory owned by the List, including itself

list_el_size()

size_t list_el_size

(

const struct dynamic_array *

)

Returns sizeof elements (e.g. if list element type is char, returns 1)

list_extend()

int list_extend	(	struct dynamic_array *	ls,
		const void *	array,
		size_t	array_len )

Copies all elements from array of length array_len to the end of the List.

Parameters

ls	a List to be extended
array	array of array_len elements of size equal to ls::el_size
array_len	the number of elements in the array

Returns

RV_ERROR if realloc fails while creating space for the new elements, otherwise returns RV_SUCCESS

list_extend_list()

int list_extend_list	(	struct dynamic_array *	ls,
		const struct dynamic_array *	app )

Copies all elements from app to ls

Parameters

ls	a List to be extended
app	a List to extend ls

Returns

RV_ERROR if realloc fails while creating space for the new elements, otherwise returns RV_SUCCESS

list_init_cap_size()

Constructor struct dynamic_array * list_init_cap_size	(	size_t	el_size,
		size_t	init_cap )

Creates a new list

Parameters

el_size	sizeof a single element
init_cap	initial capacity in terms of elements (rather than bytes)

Returns

pointer to a new empty List, or NULL if allocation fails

list_init_size()

Constructor struct dynamic_array * list_init_size

(

size_t

el_size

)

Initializes the lists elements to be of size el_size

Parameters

el_size

sizeof() a single element

Returns

pointer to a new empty List, or NULL if allocation fails

list_insert()

int list_insert	(	struct dynamic_array *	,
		size_t	index,
		const void *	data )

Inserts data to list at specified index, all following data is moved one place forward

Parameters

index	index of new element
data	pointer to data of size ls::el_size

Returns

• if index is OOB -> RV_EXCEPTION
• if realloc fails -> RV_ERROR
• otherwise -> RV_SUCCESS

list_is_empty()

bool list_is_empty

(

const struct dynamic_array *

)

Returns true if list is empty.

list_items()

const void * list_items

(

const struct dynamic_array *

)

Gets a const view of the items.

Returns

A pointer to the lists items array.

list_items_copy()

UseResult void * list_items_copy

(

const struct dynamic_array *

)

Gets the lists items as an array. This pointer should be freed

Returns

A pointer to a copy of the lists items array.

list_lsearch_i()

int64_t list_lsearch_i	(	const struct dynamic_array *	,
		const void *	needle )

Linear search, returns index (-1 if not found)

list_lsearch_p()

const void * list_lsearch_p	(	const struct dynamic_array *	,
		const void *	needle )

Linear search, returns pointer (NULL if not found)

list_peek()

const void * list_peek

(

const struct dynamic_array *

ls

)

Gets a non-mutable look of the last element

Returns

const void * to the last element

list_pop()

int list_pop	(	struct dynamic_array *	,
		void *	container )

Removes the last element from the List, puts the result into container.

If container is NULL, this method discards the last element.

Parameters

container

pointer to valid space in memory of at least ls::el_size bytes

Returns

• RV_EXCEPTION if List is empty
• RV_ERROR if malloc fails
• else RV_SUCCESS

list_remove()

int list_remove	(	struct dynamic_array *	,
		size_t	index,
		void *	container )

Removes the element at index by moving the following elements back by one space.

If container is NULL, this method discards the last element.

Parameters

index
container	pointer to valid space in memory of at least ls::el_size bytes

Returns

• RV_EXCEPTION if index is OOB
• RV_ERROR if alloc fails
• else RV_SUCCESS

list_remove_fast()

int list_remove_fast	(	struct dynamic_array *	,
		size_t	index,
		void *	container )

Removes the element at index by swapping it with the last element and popping.

If container is NULL, this method discards the last element.

Parameters

index
container	pointer to valid space in memory of at least ls::el_size bytes

Returns

• RV_EXCEPTION if index is OOB
• RV_ERROR if alloc fails
• else RV_SUCCESS

list_reverse()

int list_reverse

(

struct dynamic_array *

)

Reverses the List – in place

Returns

RV_ERROR if an error occurs, else RV_SUCCESS

list_reversed()

Constructor struct dynamic_array * list_reversed

(

const struct dynamic_array *

)

Creates a new List

Returns

a new List with the same items as the original, in a reverse order

list_see()

const void * list_see	(	const struct dynamic_array *	ls,
		size_t	idx )

Gets a non-mutable look of the element at the specified index

Returns

const void * to the element

list_set_at()

int list_set_at	(	struct dynamic_array *	,
		size_t	index,
		const void *	data )

Changes element at index to data

Returns

Can return RV_EXCEPTION if index is OOB, else RV_SUCCESS

list_size()

size_t list_size

(

const struct dynamic_array *

)

Returns number of elements in the list.

list_sort()

void list_sort	(	struct dynamic_array *	ls,
		int(*	cmp )(const void *, const void *) )

Uses stdlib's qsort.

Parameters

ls	List to be sorted
cmp	compare function for the elements of the List

See also

qsort from <stdlib.h>