sopc_array.h File Reference

A generic array implementation. More...

#include <stdbool.h>
#include <stddef.h>

Go to the source code of this file.

Macros
#define	SOPC_Array_Append(array, val)
	Appends one value to an array.
#define	SOPC_Array_Get(array, ty, index)
	Gets a value from an array by its index.

Typedefs
typedef struct _SOPC_Array	SOPC_Array
typedef void	SOPC_Array_Free_Func(void *data)
	Type of functions used to free array values.
typedef int	SOPC_Array_Compare_Func(const void *a, const void *b)
	Type of functions used to compare items when sorting an array.

Functions
SOPC_Array *	SOPC_Array_Create (size_t element_size, size_t initial_capacity, SOPC_Array_Free_Func *free_func)
	Creates a new array with a given capacity.
SOPC_Array *	SOPC_Array_Copy (const SOPC_Array *array)
	Makes a copy of an array.
void	SOPC_Array_Delete (SOPC_Array *array)
	Deletes an array.
bool	SOPC_Array_Append_Values (SOPC_Array *array, const void *data, size_t n_elements)
	Appends several values contiguous in memory to an array.
void *	SOPC_Array_Get_Ptr (const SOPC_Array *array, size_t index)
	Gets a pointer to a value in an array by its index.
size_t	SOPC_Array_Size (const SOPC_Array *array)
	Gets the number of elements in an array.
void	SOPC_Array_Sort (SOPC_Array *array, SOPC_Array_Compare_Func *compare_func)
	Sorts the elements in an array.
void *	SOPC_Array_Into_Raw (SOPC_Array *array)
	Converts a SOPC_Array into a raw C array.
SOPC_Array_Free_Func *	SOPC_Array_Get_Free_Func (SOPC_Array *array)
	Returns the function used to clear the elements of an array on deletion.
void	SOPC_Array_Set_Free_Func (SOPC_Array *array, SOPC_Array_Free_Func *func)
	Sets the function used to clear the array elements when it is deleted.

Detailed Description

A generic array implementation.

Macro Definition Documentation

SOPC_Array_Append

#define SOPC_Array_Append	(		array,
			val )

Value:

SOPC_Array_Append_Values((array), &(val), 1)

Appends one value to an array.

Parameters

array	The array.
val	The value to append.

Returns

TRUE on success, FALSE on memory allocation failure or if array is NULL.

SOPC_Array_Get

#define SOPC_Array_Get	(		array,
			ty,
			index )

Value:

(*((ty*) SOPC_Array_Get_Ptr((array), (index))))

Gets a value from an array by its index.

Parameters

array	The array.
ty	The type of the value stored in the array.
index	The index of the value in the array.

Returns

The value or NULL if array is NULL.

Typedef Documentation

SOPC_Array

typedef struct _SOPC_Array SOPC_Array

SOPC_Array_Free_Func

typedef void SOPC_Array_Free_Func(void *data)

Type of functions used to free array values.

The parameter passed to the function is a pointer to the item. That means that if your array holds pointers, the free function will be passed a pointer to the pointer held in the array.

SOPC_Array_Compare_Func

typedef int SOPC_Array_Compare_Func(const void *a, const void *b)

Type of functions used to compare items when sorting an array.

The function should return a value less than 0 if a is less than b, 0 if a and b have the same value, and greater than 0 if a is greater than b.

The parameters passed to the function are pointers to the items. That means that if your array holds pointers, the compare function will be passed pointers to the pointers held in the array.

Function Documentation

SOPC_Array_Create()

SOPC_Array * SOPC_Array_Create	(	size_t	element_size,
		size_t	initial_capacity,
		SOPC_Array_Free_Func *	free_func )

Creates a new array with a given capacity.

Parameters

element_size	The size of one element of the array.
initial_capacity	The initial capacity to allocate (can be 0).
free_func	A function to call on each array element when the array is deleted. Can be NULL.

Returns

The created array in case of success, or NULL on memory allocation failure.

The actual allocated size might be greater than the requested capacity.

SOPC_Array_Copy()

SOPC_Array * SOPC_Array_Copy

(

const SOPC_Array *

array

)

Makes a copy of an array.

Parameters

array

The array.

Returns

The copied array in case of success, or NULL on memory allocation failure or if array is NULL.

SOPC_Array_Delete()

void SOPC_Array_Delete

(

SOPC_Array *

array

)

Deletes an array.

Parameters

array

The array.

The free function passed in the constructor or via SOPC_Array_Set_Free_Func (if any) will be called for each element of the array before the array is freed.

SOPC_Array_Append_Values()

bool SOPC_Array_Append_Values	(	SOPC_Array *	array,
		const void *	data,
		size_t	n_elements )

Appends several values contiguous in memory to an array.

Parameters

array	The array.
data	The memory location of the first value. If NULL, the array grows by n_elements items, but does not initialize them.
n_elements	The number of values present in memory.

Returns

TRUE on success, FALSE on memory allocation failure or if array is NULL.

SOPC_Array_Get_Ptr()

void * SOPC_Array_Get_Ptr	(	const SOPC_Array *	array,
		size_t	index )

Gets a pointer to a value in an array by its index.

Parameters

array	The array.
index	The index of the value.

Returns

A pointer to the value.

SOPC_Array_Size()

size_t SOPC_Array_Size

(

const SOPC_Array *

array

)

Gets the number of elements in an array.

Parameters

array

The array.

Returns

The number of elements in the array or 0 if array is NULL.

SOPC_Array_Sort()

void SOPC_Array_Sort	(	SOPC_Array *	array,
		SOPC_Array_Compare_Func *	compare_func )

Sorts the elements in an array.

Parameters

array	The array.
compare_func	The function to use to compare to elements.

The sort is not guaranteed to be stable.

SOPC_Array_Into_Raw()

void * SOPC_Array_Into_Raw

(

SOPC_Array *

array

)

Converts a SOPC_Array into a raw C array.

Parameters

array

The array.

Returns

A contiguous region of memory holding the array data, or NULL if the array was empty.

This function releases the memory of the SOPC_Array itself, only keeping the data before returning it. The returned memory region holds the data exactly, without any padding before or after, and must be freed when no longer needed.

SOPC_Array_Get_Free_Func()

SOPC_Array_Free_Func * SOPC_Array_Get_Free_Func

(

SOPC_Array *

array

)

Returns the function used to clear the elements of an array on deletion.

Parameters

array

The array.

Returns

The function used to clear the elements when the array is deleted, or NULL if no such function is defined or if array is NULL.

SOPC_Array_Set_Free_Func()

void SOPC_Array_Set_Free_Func	(	SOPC_Array *	array,
		SOPC_Array_Free_Func *	func )

Sets the function used to clear the array elements when it is deleted.

Parameters

array	The array.
func	The function to use for clearing elements, or NULL if no such function should be called.