Generic dynamic stack interface. More...

#include <stddef.h>

Include dependency graph for stack.h:

Functions
void	rdesc_stack_init (struct rdesc_stack **stack, size_t element_size)
	Initializes a new stack with the specified element size.

void	rdesc_stack_destroy (struct rdesc_stack *stack)
	Frees all memory allocated by the stack.

void	rdesc_stack_reset (struct rdesc_stack **stack)
	Clears the stack and resets capacity to initial size.

void *	rdesc_stack_at (struct rdesc_stack *stack, size_t index)
	Returns pointer to the element at the specified index.

void *	rdesc_stack_multipush (struct rdesc_stack *stack, void elements, size_t count)
	Pushes multiple elements onto the stack.

void *	rdesc_stack_push (struct rdesc_stack *stack, void element)
	Pushes a single element onto the stack.

void *	rdesc_stack_multipop (struct rdesc_stack **stack, size_t count)
	Pops multiple elements from the stack, and returns pointer to the element that was at the bottom of the popped range.

void *	rdesc_stack_pop (struct rdesc_stack **stack)
	Removes and returns the top element from the stack.

void *	rdesc_stack_top (struct rdesc_stack *stack)
	Returns the top element without removing it.

size_t	rdesc_stack_len (const struct rdesc_stack *stack)
	Returns the current number of elements in the stack.

Detailed Description

Generic dynamic stack interface.

This header defines the function signatures required to manipulate the parser's stack. The stack is a generic, type-agnostic container that stores fixed-size elements and provides dynamic growth/shrink capabilities.

Custom Implementations

If you have defined a custom struct rdesc_stack, you must provide implementations for all functions declared in this file. The parser engine relies on these exact signatures.

Memory Management

The stack owns all memory it allocates. Pointers returned by stack operations (push, pop, top, at) remain valid until the next stack-modifying operation (push, pop, reset, destroy).

Function Documentation

◆ rdesc_stack_at()

void * rdesc_stack_at	(	struct rdesc_stack *	stack,
		size_t	index
	)

Returns pointer to the element at the specified index.

Returns: Pointer to element at index i

Precondition: i < rdesc_stack_len(stack)

Note: Index 0 is the bottom of the stack.

◆ rdesc_stack_destroy()

void rdesc_stack_destroy ( struct rdesc_stack * stack )

Frees all memory allocated by the stack.

Postcondition: All memory is released. Stack pointer becomes invalid.

◆ rdesc_stack_init()

void rdesc_stack_init	(	struct rdesc_stack **	stack,
		size_t	element_size
	)

Initializes a new stack with the specified element size.

Parameters

stack	Pointer to stack pointer (will be allocated)
element_size	Size of each element in bytes

Postcondition: Stack is allocated with initial capacity and zero length.

Note: *stack is set to NULL if allocation fails.

◆ rdesc_stack_multipop()

void * rdesc_stack_multipop	(	struct rdesc_stack **	stack,
		size_t	count
	)

Pops multiple elements from the stack, and returns pointer to the element that was at the bottom of the popped range.

Note: This may trigger realloc. The stack implementation should handle allocation errors and hide them from upper layers.; If count is 0, this is a no-op and returns current top.

◆ rdesc_stack_multipush()

void * rdesc_stack_multipush	(	struct rdesc_stack **	stack,
		void *	elements,
		size_t	count
	)

Pushes multiple elements onto the stack.

elements is array of elements to copy, or NULL to allocate uninitialized space.

Returns: Pointer to the first pushed element in the stack, i.e., pointer to allocated space for manual initialization.

Note: If count is 0, this is a no-op and returns a pointer at current top.; Returns NULL if memory allocation fails. Elements are not pushed in case of failure.

Warning: As this function may trigger realloc, element SHALL NOT point to the stack.

◆ rdesc_stack_pop()

void * rdesc_stack_pop ( struct rdesc_stack ** stack )

Removes and returns the top element from the stack.

Equivalent to rdesc_stack_multipop(stack, 1).

See also: rdesc_stack_multipop

◆ rdesc_stack_push()

void * rdesc_stack_push	(	struct rdesc_stack **	stack,
		void *	element
	)

Pushes a single element onto the stack.

Equivalent to rdesc_stack_multipush(stack, element, 1).

See also: rdesc_stack_multipush

◆ rdesc_stack_reset()

void rdesc_stack_reset ( struct rdesc_stack ** stack )

Clears the stack and resets capacity to initial size.

Postcondition: Stack length is zero, capacity is reset to initial value.

Note: *stack is set to NULL if allocation fails.

Functions