Array

The bj_array type is a sequence container that encapsulates dynamic C-style arrays. More...

Collaboration diagram for Array:

Detailed Description

The elements are stored contiguously, allowing access using offsets.

The storage of the array is expanded as needed.

Macros
#define	bj_array_new_t(T)
	Creates a new bj_array with a payload size inferred from the type T.

Typedefs
typedef struct bj_array_t	bj_array
	Typedef for the bj_array_t struct.

Functions
bj_array *	bj_array_new (size_t bytes_payload)
	Creates a new bj_array with a payload size specified in bytes.
void	bj_array_del (bj_array *p_array)
	Deletes a bj_array object and releases associated memory.
bj_array *	bj_array_alloc (void)
	Allocate enough memory to hold an Array object.
bj_array *	bj_array_init (bj_array *p_instance, size_t bytes_payload)
	Initialize a new array with given size.
void	bj_array_reset (bj_array *p_array)
	Resets the entire array object, making it suitable for free.
void	bj_array_clear (bj_array *array)
	Clears all elements in the array.
void	bj_array_shrink (bj_array *array)
	Shrinks the memory allocation to fit the current array length.
void	bj_array_set_len (bj_array *array, size_t len)
	Resizes the array to the specified length.
void	bj_array_reserve (bj_array *array, size_t capacity)
	Reserves memory for up to capacity elements in the array.
void	bj_array_push (bj_array *array, const void *value)
	Appends a value to the end of the array.
void	bj_array_pop (bj_array *array)
	Removes the last value from the array.
void *	bj_array_at (const bj_array *array, size_t at)
	Retrieves the value stored at the specified index in the array.
void *	bj_array_data (const bj_array *array)
	Retrieves a pointer to the underlying data of the array.
size_t	bj_array_len (const bj_array *array)
	Retrieves the number of elements in the array.
size_t	bj_array_capacity (const bj_array *array)
	Retrieves the current capacity of the array.

Macro Definition Documentation

bj_array_new_t

#define bj_array_new_t

(

T

)

Value:

bj_array_new(sizeof(T))

Parameters

T	Type of elements.

Returns

A pointer to the newly created bj_array object.

See also

bj_array_new

Examples

array.c.

Function Documentation

bj_array_alloc()

bj_array * bj_array_alloc

(

void

)

Returns

A pointer to the newly allocated memory.

Memory Management

The memory returned by the function must be freed with bj_free

See also

bj_array_new, bj_array_init, bj_array_reset, bj_array_del

bj_array_at()

void * bj_array_at	(	const bj_array *	array,
		size_t	at )

Parameters

array	The array object to retrieve the value from.
at	Index of the element to retrieve.

Returns

Pointer to the value at the specified index.

Return values

0	if array is null.

Examples

array.c.

bj_array_capacity()

size_t bj_array_capacity

(

const bj_array *

array

)

Parameters

array

The array object to get the capacity from.

Returns

Current capacity of the array.

Return values

0	if array is null.

Examples

array.c.

bj_array_clear()

void bj_array_clear

(

bj_array *

array

)

Parameters

array

The array object to clear.

If the array is already empty, this function does nothing. To release the internal memory, call bj_array_shrink after clearing.

Note

When called on a null object, this function does nothing.

Examples

array.c.

bj_array_data()

void * bj_array_data

(

const bj_array *

array

)

Parameters

array

The array object to get the data pointer from.

Returns

Pointer to the underlying data.

Return values

0	if array is null.

Examples

array.c.

bj_array_del()

void bj_array_del

(

bj_array *

p_array

)

Parameters

p_array

Pointer to the bj_array object to delete.

Examples

array.c.

bj_array_init()

bj_array * bj_array_init	(	bj_array *	p_instance,
		size_t	bytes_payload )

Parameters

p_instance	A pointer to an array object.
bytes_payload	Size of each element in bytes.

Returns

A pointer to the newly created bj_array object.

bj_array_len()

size_t bj_array_len

(

const bj_array *

array

)

Parameters

array

The array object to get the length from.

Returns

Number of elements in the array.

Return values

0	if array is null.

Examples

array.c.

bj_array_new()

bj_array * bj_array_new

(

size_t

bytes_payload

)

The function effectively uses bj_array_alloc and bj_array_init.

Parameters

bytes_payload

Size of each element in bytes.

Returns

A pointer to the newly created bj_array object.

bj_array_pop()

void bj_array_pop

(

bj_array *

array

)

Parameters

array

The array object to remove the last value from.

This function reduces the array size by one.

Note

When called on a null object, this function does nothing.

Examples

array.c.

bj_array_push()

void bj_array_push	(	bj_array *	array,
		const void *	value )

Parameters

array	The array object to push the value into.
value	Pointer to the value to append.

Copies the memory pointed to by value into the array using bj_memcpy.

Note

Calling this function may reserve more space in the array, which invalidates the data pointer.

When called on a null object, this function does nothing.

Examples

array.c.

bj_array_reserve()

void bj_array_reserve	(	bj_array *	array,
		size_t	capacity )

Parameters

array	The array object to reserve memory for.
capacity	Number of elements to reserve space for.

If capacity is smaller than the current capacity, this function does nothing. Otherwise, it reallocates memory to fit the new capacity.

Note

When called on a null object, this function does nothing. This function invalidates the array data pointer if reallocation is performed.

bj_array_reset()

void bj_array_reset

(

bj_array *

p_array

)

Parameters

p_array

The array object to reset.

bj_array_set_len()

void bj_array_set_len	(	bj_array *	array,
		size_t	len )

Parameters

array	The array object to resize.
len	New length of the array.

If len == 0, this function is equivalent to calling bj_array_clear.

Note

When called on a null object, this function does nothing. This function invalidates the array data pointer if reallocation is necessary.

bj_array_shrink()

void bj_array_shrink

(

bj_array *

array

)

Parameters

array

The array object to shrink.

This function reallocates the memory used by the array to fit its current length.

Note

When called on a null object, this function does nothing. This function invalidates the array data pointer.

Examples

array.c.