ARRAY

Description

Manages accesses and assignments on an already allocated buffer of uint8_t elements, keeping track of its usage. A common use case is buffer management of UTF-8 strings, or operations on binary data, characters and strings over a fixed uint8_t buffer in general. Each ARRAY instance should handle a unique buffer. The Array instance does not own the buffer passed at initialization and will never try to free or reallocate it.

Design and development status

This is not a full-featured Array implementation. Only the bare minimum functionality required for known use cases has been implemented. String and binary stores are not optimized for speed; these are executed one element at a time by internal calls to ARRAY_AppendOne().

Changelog

Version	Date*	Author	Comment
1.0.0	2022.9.7	sgermino	Initial release.

* Date format is Year.Month.Day.

API reference

struct ARRAY

The user should treat this as an opaque structure. No member should be directly accessed or modified.

void ARRAY_Init(struct ARRAY *const A, uint8_t *const Buffer, const uint32_t Capacity)

Array initialization.

Parameters

• Buffer – Already allocated buffer.

• Capacity – Buffer capacity, in uint8_t elements.

void ARRAY_Reset(struct ARRAY *const A)

Array reset. Internal index pointer is set to zero.

uint8_t ARRAY_Element(struct ARRAY *const A, const uint32_t Index)

Gets the element value at the given index. The caller must check for inserted elements (ARRAY_Count()) before specifying an invalid index; the function asserts this condition.

Parameters

• Index – Element index.

Returns

Element value.

const uint8_t *ARRAY_Data(struct ARRAY *const A, const uint32_t Index)

Returns a read-only buffer pointer to the element at the given index. The caller must check for inserted elements count (ARRAY_Count()) before requesting an invalid index; the function asserts this condition.

Parameters

• Index – Element index.

Returns

Read-only buffer pointer.

uint32_t ARRAY_Count(struct ARRAY *const A)

Returns the number of inserted elements.

Returns

Element count.

uint32_t ARRAY_Left(struct ARRAY *const A)

Returns available space for new elements.

Returns

Capacity left. Zero if full.

_Bool ARRAY_AppendOne(struct ARRAY *const A, const uint8_t Value)

Appends one uint8_t element.

Parameters

• Value – The new element to append.

Returns

true if the element was successfully appended. false if the array has no capacity left.

_Bool ARRAY_AppendString(struct ARRAY *const A, const char *const Str, const size_t MaxLen)

Appends a null-terminated string.

Parameters

• Str – Null-terminated string.

• MaxLen – Maximum number of octets before finding a null termination in Str.

Returns

true if successfully appended, false if there is no null before MaxLen octets or no capacity left to insert the whole string.

_Bool ARRAY_AppendBinary(struct ARRAY *const A, const uint8_t *const Data, const uint32_t Size)

Append binary data.

Parameters

• Data – Binary data.

• Size – Number of octets to append.

Returns

true if successfully appended, false if there is no capacity left to insert the data.

uint8_t ARRAY_RemoveLast(struct ARRAY *const A)

Removes elements from the back of the Array. Caller must check that the array has at least one element; this condition is asserted.

Returns

Last element value.

_Bool ARRAY_IsEqual(struct ARRAY *const A, struct ARRAY *const B)

Checks for content equality between two Arrays.

Returns

true if contents match, false otherwise.

void ARRAY_Copy(struct ARRAY *const A, struct ARRAY *const B)

Copy contents from one Array to the other without touching buffer pointers or sizes. The destination capacity must suffice; this condition is asserted.

Parameters

• A – Source.

• B – Destination.