carr.h File Reference

Go to the source code of this file.

Classes
struct	CARR
	Represents a pointer-based vector container. More...

Typedefs
typedef struct CARR	CARR
typedef enum CARRError	CARRError

Enumerations
enum	CARRError {   CARR_VEC_OK , CARR_VEC_OutOfBounds , CARR_VEC_ResizeError , CARR_VEC_OOM ,   CARR_VEC_NULL }
	Error codes returned by CARR operations. More...

Functions
CARRError	carr_deleteIndex (CARR *vec, const size_t index, const bool fall)
	Deletes an element at a specified index.
void	carr_destroy (CARR *vec)
	Destroys a vector and releases its internal resources.
CARR	carr_init (const size_t cap, const bool dynamic)
	Initializes a new CARR vector.
CARRError	carr_pushBack (CARR *vec, void *item)
	Appends an element to the end of the vector.
CARRError	carr_pushFront (CARR *vec, void *item)
	Inserts an element at the beginning of the vector.
CARRError	carr_replaceIndex (CARR *vec, void *item, const size_t idx)
	Replaces an element at a specified index.
CARRError	carr_resize (CARR *vec, const size_t newCap)
	Changes the capacity of a vector.
CARRError	carr_reverse (CARR *vec)
	Reverses the order of elements in the vector.

Typedef Documentation

CARR

typedef struct CARR CARR

CARRError

typedef enum CARRError CARRError

Enumeration Type Documentation

CARRError

enum CARRError

Error codes returned by CARR operations.

Enumerator
CARR_VEC_OK	The operation completed successfully.
CARR_VEC_OutOfBounds	The requested index is outside the valid range.
CARR_VEC_ResizeError	The requested resize operation could not be completed.
CARR_VEC_OOM	Memory allocation failed.
CARR_VEC_NULL	A required pointer argument was NULL.

Definition at line 82 of file carr.h.

{
    /** @brief The operation completed successfully. */
    CARR_VEC_OK,
 
    /** @brief The requested index is outside the valid range. */
    CARR_VEC_OutOfBounds,
 
    /** @brief The requested resize operation could not be completed. */
    CARR_VEC_ResizeError,
 
    /** @brief Memory allocation failed. */
    CARR_VEC_OOM,
 
    /** @brief A required pointer argument was NULL. */
    CARR_VEC_NULL,
} CARRError;

Function Documentation

carr_deleteIndex()

CARRError carr_deleteIndex	(	CARR *	vec,
		const size_t	index,
		const bool	fall )

Deletes an element at a specified index.

Removes the element at index from the vector.

Parameters

[in,out]	vec	Pointer to the vector to modify.
[in]	index	Index of the element to delete.
[in]	fall	Controls the deletion behavior, as defined by the implementation.

Returns

CARR_VEC_OK if successful.

CARR_VEC_OutOfBounds if index is invalid.

CARR_VEC_NULL if a required pointer is NULL.

Note

The meaning of fall and whether the removed element's pointer is freed must be verified in the implementation.

References carr_deleteIndex().

Referenced by carr_deleteIndex().

carr_destroy()

void carr_destroy

(

CARR *

vec

)

Destroys a vector and releases its internal resources.

Releases resources owned by the vector implementation and invalidates the vector's internal storage.

Parameters

[in,out]

vec

Pointer to the vector to destroy.

Note

This function does not return an error code.

Whether the structure is reset to a safe, reusable state depends on the implementation.

The pointed-to elements are not assumed to be freed.

References carr_destroy().

Referenced by carr_destroy().

carr_init()

CARR carr_init	(	const size_t	cap,
		const bool	dynamic )

Initializes a new CARR vector.

Creates a vector with the requested initial capacity and resizing mode.

Parameters

[in]	cap	Initial capacity of the vector.
[in]	dynamic	Whether the vector supports dynamic resizing.

Returns

An initialized CARR instance.

Note

Check the returned instance according to the implementation's initialization and allocation-failure conventions.

References carr_init().

Referenced by carr_init().

carr_pushBack()

CARRError carr_pushBack	(	CARR *	vec,
		void *	item )

Appends an element to the end of the vector.

Stores item after the current last element. Depending on the vector's configuration, the operation may require additional capacity.

Parameters

[in,out]	vec	Pointer to the vector to modify.
[in]	item	Pointer to the element to append.

Returns

CARR_VEC_OK if successful.

CARR_VEC_NULL if a required pointer is NULL.

CARR_VEC_ResizeError if the required resize cannot be performed.

CARR_VEC_OOM if memory allocation fails.

References carr_pushBack().

Referenced by carr_pushBack().

carr_pushFront()

CARRError carr_pushFront	(	CARR *	vec,
		void *	item )

Inserts an element at the beginning of the vector.

Stores item at index zero and shifts existing elements as necessary.

Parameters

[in,out]	vec	Pointer to the vector to modify.
[in]	item	Pointer to the element to insert.

Returns

CARR_VEC_OK if successful.

CARR_VEC_NULL if a required pointer is NULL.

CARR_VEC_ResizeError if the required resize cannot be performed.

CARR_VEC_OOM if memory allocation fails.

References carr_pushFront().

Referenced by carr_pushFront().

carr_replaceIndex()

CARRError carr_replaceIndex	(	CARR *	vec,
		void *	item,
		const size_t	idx )

Replaces an element at a specified index.

Assigns a new pointer to the element at idx.

Parameters

[in,out]	vec	Pointer to the vector to modify.
[in]	item	Pointer to the replacement element.
[in]	idx	Index of the element to replace.

Returns

CARR_VEC_OK if successful.

CARR_VEC_OutOfBounds if idx is invalid.

CARR_VEC_NULL if a required pointer is NULL.

Note

This function replaces the stored pointer. Ownership and cleanup of the previous element are determined by the implementation.

References carr_replaceIndex().

Referenced by carr_replaceIndex().

carr_resize()

CARRError carr_resize	(	CARR *	vec,
		const size_t	newCap )

Changes the capacity of a vector.

Requests a new capacity for the vector's underlying pointer array.

Parameters

[in,out]	vec	Pointer to the vector to resize.
[in]	newCap	Desired capacity.

Returns

CARR_VEC_OK if successful.

CARR_VEC_NULL if a required pointer is NULL.

CARR_VEC_ResizeError if resizing fails or is not permitted.

CARR_VEC_OOM if memory allocation fails.

Note

The exact behavior when newCap is smaller than the current size depends on the implementation.

References carr_resize().

Referenced by carr_resize().

carr_reverse()

CARRError carr_reverse

(

CARR *

vec

)

Reverses the order of elements in the vector.

Reorders the stored pointers so that the first element becomes the last, the second becomes the second-to-last, and so on.

Parameters

[in,out]

vec

Pointer to the vector to reverse.

Returns

CARR_VEC_OK if successful.

CARR_VEC_NULL if a required pointer is NULL.

Note

The elements themselves are not copied or modified; only their positions in the vector are changed.

References carr_reverse().

Referenced by carr_reverse().