tr_stack.h File Reference

Public API for the stack data structure. More...

#include "tr_datastructures/tr_export.h"
#include "tr_datastructures/tr_result.h"
#include "tr_datastructures/tr_types.h"

Go to the source code of this file.

Typedefs
typedef enum tr_stack_type	tr_stack_type_t
	Selects the underlying implementation used by the stack.

Enumerations
enum	tr_stack_type { TR_STACK_ARRAY_DYNAMIC = 0 , TR_STACK_ARRAY_FIXED = 1 , TR_STACK_LL = 2 }
	Selects the underlying implementation used by the stack. More...

Functions
tr_result_t	tr_stack_create (size_t size_of_datatype, size_t elements_to_allocate, tr_stack_type_t stack_type, struct stack **id_of_stack)
	Allocates and initialises a new stack instance.
tr_result_t	tr_stack_destroy (struct stack **id_of_stack)
	Frees all memory associated with the stack instance.
tr_result_t	tr_stack_push (struct stack *id_of_stack, const void *data_to_push)
	Pushes a deep copy of the data onto the top of the stack.
tr_result_t	tr_stack_pop (struct stack *id_of_stack)
	Removes the element at the top of the stack.
tr_result_t	tr_stack_top (const struct stack *id_of_stack, void *data_at_top)
	Copies the element at the top of the stack into the provided buffer.
tr_result_t	tr_stack_size (const struct stack *id_of_stack, size_t *size)
	Returns the current number of elements in the stack.
tr_result_t	tr_stack_is_empty (const struct stack *id_of_stack, bool *is_empty)
	Checks whether the stack contains no elements.
tr_result_t	tr_stack_capacity (const struct stack *id_of_stack, size_t *capacity)
	Returns the total allocated capacity of the stack.

Detailed Description

Public API for the stack data structure.

Provides a generic stack implementation supporting multiple underlying storage strategies selectable at runtime via tr_stack_type_t.

Typical usage:

struct stack *p_stack = NULL;
tr_result_t   res     = TR_OK;
int           val     = 42;
int           out     = 0;
 
res = tr_stack_create(sizeof(int), 10, TR_STACK_ARRAY_DYNAMIC, &p_stack);
if (TR_OK != res) { return res; }
 
res = tr_stack_push(p_stack, &val);
if (TR_OK != res) { return res; }
 
res = tr_stack_top(p_stack, &out);
if (TR_OK != res) { return res; }
 
res = tr_stack_pop(p_stack);
if (TR_OK != res) { return res; }
 
tr_stack_destroy(&p_stack);

Typedef Documentation

tr_stack_type_t

typedef enum tr_stack_type tr_stack_type_t

Selects the underlying implementation used by the stack.

Passed to tr_stack_create to select which implementation to use. The choice affects memory layout, growth behaviour and performance characteristics.

Type	Memory	Growth	Best for
TR_STACK_ARRAY_DYNAMIC	Contiguous	Automatic	General purpose
TR_STACK_ARRAY_FIXED	Contiguous	None	Bounded/embedded use
TR_STACK_LL	Per node	Automatic	Unpredictable size

Enumeration Type Documentation

tr_stack_type

enum tr_stack_type

Selects the underlying implementation used by the stack.

Passed to tr_stack_create to select which implementation to use. The choice affects memory layout, growth behaviour and performance characteristics.

Type	Memory	Growth	Best for
TR_STACK_ARRAY_DYNAMIC	Contiguous	Automatic	General purpose
TR_STACK_ARRAY_FIXED	Contiguous	None	Bounded/embedded use
TR_STACK_LL	Per node	Automatic	Unpredictable size

Enumerator
TR_STACK_ARRAY_DYNAMIC	Array based - grows automatically by factor of 2
TR_STACK_ARRAY_FIXED	Array based - fixed capacity, returns TR_ERR_FULL
TR_STACK_LL	Linked list based - dynamic node allocation

Function Documentation

tr_stack_capacity()

tr_result_t tr_stack_capacity	(	const struct stack *	id_of_stack,
		size_t *	capacity
	)

Returns the total allocated capacity of the stack.

For TR_STACK_ARRAY_DYNAMIC stacks capacity grows automatically and may be larger than the current size. For TR_STACK_ARRAY_FIXED stacks capacity is fixed at creation time and never changes. For TR_STACK_LL stacks capacity equals the current size since nodes are allocated individually.

Parameters

[in]	id_of_stack	Pointer to the stack to query
[out]	capacity	Pointer to receive the capacity

Returns

TR_OK Capacity retrieved successfully

TR_ERR_NULL id_of_stack or capacity is NULL

Example:

size_t      capacity = 0u;
size_t      size     = 0u;
tr_result_t res      = TR_OK;
 
tr_stack_size(p_stack, &size);
res = tr_stack_capacity(p_stack, &capacity);
if (TR_OK == res)
{
    printf("Using %zu of %zu slots\n", size, capacity);
}

tr_stack_create()

tr_result_t tr_stack_create	(	size_t	size_of_datatype,
		size_t	elements_to_allocate,
		tr_stack_type_t	stack_type,
		struct stack **	id_of_stack
	)

Allocates and initialises a new stack instance.

Parameters

[in]	size_of_datatype	Byte size of the datatype to store
[in]	elements_to_allocate	Initial number of elements to allocate
[in]	stack_type	Implementation type to use
[out]	id_of_stack	Pointer to receive the created stack

Returns

TR_OK Stack created successfully

TR_ERR_NULL id_of_stack is NULL

TR_ERR_INVALID size_of_datatype or elements_to_allocate is 0

TR_ERR_ALLOC Memory allocation failed

tr_stack_destroy()

tr_result_t tr_stack_destroy

(

struct stack **

id_of_stack

)

Frees all memory associated with the stack instance.

Destroys the stack and sets the pointer to NULL to prevent use after free. Both the implementation data and the stack handle are freed.

Parameters

[in,out]

id_of_stack

Pointer to pointer to the stack to destroy. Set to NULL after destruction

Returns

TR_OK Stack destroyed successfully

TR_ERR_NULL id_of_stack or *id_of_stack is NULL

Example:

struct stack *p_stack = NULL;
 
tr_stack_create(sizeof(int), 10, TR_STACK_ARRAY_DYNAMIC, &p_stack);
 
tr_stack_destroy(&p_stack);
// p_stack is now NULL

tr_stack_is_empty()

tr_result_t tr_stack_is_empty	(	const struct stack *	id_of_stack,
		bool *	is_empty
	)

Checks whether the stack contains no elements.

Parameters

[in]	id_of_stack	Pointer to the stack to check
[out]	is_empty	Set to true if the stack is empty, false otherwise

Returns

TR_OK Check completed successfully

TR_ERR_NULL id_of_stack or is_empty is NULL

Example:

bool        is_empty = false;
tr_result_t res      = TR_OK;
 
res = tr_stack_is_empty(p_stack, &is_empty);
if (TR_OK == res && is_empty)
{
    printf("Stack is empty\n");
}

tr_stack_pop()

tr_result_t tr_stack_pop

(

struct stack *

id_of_stack

)

Removes the element at the top of the stack.

Decrements the stack size by one. The data is not returned — call tr_stack_top first if you need the value before removing it.

Parameters

[in,out]

id_of_stack

Pointer to the stack to pop from

Returns

TR_OK Element removed successfully

TR_ERR_NULL id_of_stack is NULL

TR_ERR_EMPTY Stack is empty

Example:

int         out = 0;
tr_result_t res = TR_OK;
 
res = tr_stack_top(p_stack, &out);
if (TR_OK == res)
{
    tr_stack_pop(p_stack);
}

tr_stack_push()

tr_result_t tr_stack_push	(	struct stack *	id_of_stack,
		const void *	data_to_push
	)

Pushes a deep copy of the data onto the top of the stack.

Copies size_of_datatype bytes from data_to_push into the stack. The caller retains ownership of the original data.

For TR_STACK_ARRAY_DYNAMIC stacks the array grows automatically by a factor of 2 when full. For TR_STACK_ARRAY_FIXED stacks TR_ERR_FULL is returned when capacity is reached.

Parameters

[in,out]	id_of_stack	Pointer to the stack to push onto
[in]	data_to_push	Pointer to the data to copy onto the stack

Returns

TR_OK Data pushed successfully

TR_ERR_NULL id_of_stack or data_to_push is NULL

TR_ERR_ALLOC Memory reallocation failed (dynamic only)

TR_ERR_FULL Stack is at capacity (fixed only)

Example:

int         val = 42;
tr_result_t res = TR_OK;
 
res = tr_stack_push(p_stack, &val);
if (TR_OK != res)
{
    // handle error
}

tr_stack_size()

tr_result_t tr_stack_size	(	const struct stack *	id_of_stack,
		size_t *	size
	)

Returns the current number of elements in the stack.

Parameters

[in]	id_of_stack	Pointer to the stack to query
[out]	size	Pointer to receive the current element count

Returns

TR_OK Size retrieved successfully

TR_ERR_NULL id_of_stack or size is NULL

Example:

size_t      size = 0u;
tr_result_t res  = TR_OK;
 
res = tr_stack_size(p_stack, &size);
if (TR_OK == res)
{
    printf("Stack has %zu elements\n", size);
}

tr_stack_top()

tr_result_t tr_stack_top	(	const struct stack *	id_of_stack,
		void *	data_at_top
	)

Copies the element at the top of the stack into the provided buffer.

Copies size_of_datatype bytes from the top of the stack into data_at_top. The element is not removed — call tr_stack_pop afterwards if removal is needed.

The buffer pointed to by data_at_top must be at least size_of_datatype bytes large.

Parameters

[in]	id_of_stack	Pointer to the stack to peek at
[out]	data_at_top	Buffer to copy the top element into

Returns

TR_OK Data copied successfully

TR_ERR_NULL id_of_stack or data_at_top is NULL

TR_ERR_EMPTY Stack is empty

Example:

int         out = 0;
tr_result_t res = TR_OK;
 
res = tr_stack_top(p_stack, &out);
if (TR_OK == res)
{
    printf("Top value: %d\n", out);
}