libref_array 0.6.2
Loading...
Searching...
No Matches
Typedefs | Enumerations | Functions
Interface

Typedefs

typedef void(* ref_array_fn) (void *elem, ref_array_del_enum type, void *data)
 Element cleanup callback.
 
typedef int(* ref_array_copy_cb) (void *elem, void *new_elem)
 Copy callback.
 

Enumerations

enum  ref_array_del_enum
 Enumeration of the delete modes. More...
 

Functions

int ref_array_create (struct ref_array **ra, size_t elem, uint32_t grow_by, ref_array_fn cb, void *data)
 Create referenced array.
 
struct ref_array * ref_array_getref (struct ref_array *ra)
 Get new reference to an array.
 
void ref_array_destroy (struct ref_array *ra)
 Delete the array.
 
int ref_array_append (struct ref_array *ra, void *element)
 Add new element to the array.
 
void * ref_array_get (struct ref_array *ra, uint32_t idx, void *acptr)
 Get element data.
 
int ref_array_getlen (struct ref_array *ra, uint32_t *len)
 Get array length.
 
uint32_t ref_array_len (struct ref_array *ra)
 Array length.
 
int ref_array_insert (struct ref_array *ra, uint32_t idx, void *element)
 Insert a new element into the array.
 
int ref_array_replace (struct ref_array *ra, uint32_t idx, void *element)
 Replace element in the array.
 
int ref_array_remove (struct ref_array *ra, uint32_t idx)
 Remove element from the array.
 
int ref_array_swap (struct ref_array *ra, uint32_t idx1, uint32_t idx2)
 Swap two elements in the array.
 
void ref_array_reset (struct ref_array *ra)
 Reset array.
 
int ref_array_copy (struct ref_array *ra, ref_array_copy_cb copy_cb, ref_array_fn cb, void *data, struct ref_array **copy_ra)
 Copy array.
 
void ref_array_debug (struct ref_array *ra, int num)
 Print array for debugging purposes.
 

Detailed Description

Typedef Documentation

◆ ref_array_fn

typedef void(* ref_array_fn) (void *elem, ref_array_del_enum type, void *data)

Element cleanup callback.

Callback that can be provided by a caller to free data when the storage is actually destroyed.

Parameters
[in]elemPointer to the array element.
[in]typeType of the operation performed.
[in]dataApplication data that can be used inside the callback. No return value.

◆ ref_array_copy_cb

typedef int(* ref_array_copy_cb) (void *elem, void *new_elem)

Copy callback.

Callback that can be provided by a caller to copy elements of the array.

Parameters
[in]elemPointer to the array element.
[out]new_elemPointer to pointer to the new element.
Returns
0 - Success.
ENOMEM - No memory.
EINVAL - Invalid argument.

Callback can return other errors and the implementor's discretion.

Enumeration Type Documentation

◆ ref_array_del_enum

Enumeration of the delete modes.

When the array is destroyed each element of the array most likely needs to be freed. Same is true when an element is removed from the array. However the caller might need to do different things with the data depending on whether the array is destroyed or whether the element is removed. This enumeration defines constants that you used to indicate which operation was performed.

Function Documentation

◆ ref_array_create()

int ref_array_create ( struct ref_array **  ra,
size_t  elem,
uint32_t  grow_by,
ref_array_fn  cb,
void *  data 
)

Create referenced array.

Parameters
[out]raNewly created array object.
[in]elemElement size in bytes.
[in]grow_byDefines how many elements should be allocated together as one chunk.
[in]cbCleanup callback.
[in]dataCaller supplied data passed to cleanup callback.
Returns
0 - Success.
ENOMEM - No memory.
EINVAL - Invalid argument.

◆ ref_array_getref()

struct ref_array * ref_array_getref ( struct ref_array *  ra)

Get new reference to an array.

Parameters
[in]raExisting array object.
Returns
A new reference to an array object.
NULL - Invalid argument.

◆ ref_array_destroy()

void ref_array_destroy ( struct ref_array *  ra)

Delete the array.

Parameters
[in]raExisting array object or a reference.

◆ ref_array_append()

int ref_array_append ( struct ref_array *  ra,
void *  element 
)

Add new element to the array.

Appends an element to the end of the array.

Parameters
[in]raExisting array object.
[in]elementPointer to data. The number of bytes defined at the array creation as the array size will be copied into the array element.
Returns
0 - Success.
ENOMEM - No memory.
EINVAL - Invalid argument.

◆ ref_array_get()

void * ref_array_get ( struct ref_array *  ra,
uint32_t  idx,
void *  acptr 
)

Get element data.

Retrieves data from the array element.

Parameters
[in]raExisting array object.
[in]idxIndex of the array element.
[in]acptrPointer to the memory where the element's data will be copied. Can be NULL. In this case nothing is copied.
Returns
Pointer to the data stored in the element. Conventionally it should be a const pointer, however such declaration would make using variable that receives the result of this function immutable. This is very inconvenient because such variable should be able to point to data related to multiple elements of the array.
Pointer to the element's data.
NULL if index is out of range.

◆ ref_array_getlen()

int ref_array_getlen ( struct ref_array *  ra,
uint32_t *  len 
)

Get array length.

Determines length of the array.

Parameters
[in]raExisting array object.
[out]lenVariable will receive the length of the array.
Returns
0 - Success.
EINVAL - Invalid argument.

◆ ref_array_len()

uint32_t ref_array_len ( struct ref_array *  ra)

Array length.

Alternative function to get length.

Parameters
[in]raExisting array object.
Returns
Length of the array. Returns 0 if the array is invalid.

◆ ref_array_insert()

int ref_array_insert ( struct ref_array *  ra,
uint32_t  idx,
void *  element 
)

Insert a new element into the array.

Inserts an element into the array. If idx is 0 the element will be added to the beginning of the array, if idx is 1 the element will be added after the first element of the array and so on. If index is greater than the number of elements in the array the function returns error.

Parameters
[in]raExisting array object.
[in]idxIndex of the array element.
[in]elementPointer to data. The number of bytes defined at the array creation as the array size will be copied into the array element.
Returns
0 - Success.
ENOMEM - No memory.
EINVAL - Invalid argument.
ERANGE - Index is our of range.

◆ ref_array_replace()

int ref_array_replace ( struct ref_array *  ra,
uint32_t  idx,
void *  element 
)

Replace element in the array.

Replace an element of the array identified by index with a new value. If index is greater than the number of elements in the array the function returns error.

Parameters
[in]raExisting array object.
[in]idxIndex of the array element.
[in]elementPointer to data. The number of bytes defined at the array creation as the array size will be copied into the array element.
Returns
0 - Success.
ENOMEM - No memory.
EINVAL - Invalid argument.
ERANGE - Index is our of range.

◆ ref_array_remove()

int ref_array_remove ( struct ref_array *  ra,
uint32_t  idx 
)

Remove element from the array.

The element is removed and the length is decreased by 1. If index is greater than the number of elements in the array the function returns error.

Parameters
[in]raExisting array object.
[in]idxIndex of the array element.
Returns
0 - Success.
EINVAL - Invalid argument.
ERANGE - Index is our of range.

◆ ref_array_swap()

int ref_array_swap ( struct ref_array *  ra,
uint32_t  idx1,
uint32_t  idx2 
)

Swap two elements in the array.

If any of the indexes is greater than the number of elements in the array the function returns error.

Parameters
[in]raExisting array object.
[in]idx1Index of the array element.
[in]idx2Index of the array element.
Returns
0 - Success.
EINVAL - Invalid argument.
ERANGE - Index is our of range.
ENOMEM - No memory.

◆ ref_array_reset()

void ref_array_reset ( struct ref_array *  ra)

Reset array.

Function clears all contents without destroying the object. The delete callback will be called for every element of the array from the beginning to the end passing in REF_ARRAY_DESTROY value. All the storage for the array will be deallocated. After the call the array will be empty as if just created.

Parameters
[in]raExisting array object. No return value.

◆ ref_array_copy()

int ref_array_copy ( struct ref_array *  ra,
ref_array_copy_cb  copy_cb,
ref_array_fn  cb,
void *  data,
struct ref_array **  copy_ra 
)

Copy array.

Function copies all contents calling a provided callback for every entry of the array.

Parameters
[in]raExisting array object to copy.
[in]copy_cbCopy callback.
[in]cbCleanup callback, will be used to clean data in the array copy.
[in]dataCaller supplied data passed to cleanup callback.
[out]copy_raNewly allocated copy.
Returns
0 - Success.
ENOMEM - No memory.
EINVAL - Invalid argument.

◆ ref_array_debug()

void ref_array_debug ( struct ref_array *  ra,
int  num 
)

Print array for debugging purposes.

Prints array internals.

Parameters
[in]raExisting array object.
[in]numIf num is 0 elements will be printed as strings. If num is greater than 0 elements will be printed as decimal numbers. Otherwise element will not be interpreted in concrete way.

No return value.