fstack_template.h File Reference

Fixed-size array-based stack. More...

#include <assert.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>

Go to the source code of this file.

Classes
struct	fstack
	Generated stack struct type for a given VALUE_TYPE. More...

Macros
#define	PASTE(a, b)
	Paste two tokens together.
#define	XPASTE(a, b)
	First expand tokens, then paste them together.
#define	JOIN(a, b)
	First expand tokens, then paste them together with a _ in between.
#define	FSTACK_FOR_EACH(self, index, value)
	Iterate over the values in the stack from the top to bottom.
#define	FSTACK_FOR_EACH_REVERSE(self, index, value)
	Iterate over the values in the stack from the bottom to top.
#define	FSTACK_CALC_SIZEOF(fstack_name, capacity)
	Calculate the size of the stack struct. No overflow checks.
#define	FSTACK_CALC_SIZEOF_OVERFLOWS(fstack_name, capacity)
	Check for a given capacity, if the equivalent size of the stack struct overflows.
#define	NAME   fstack
	Prefix to stack type and operations. This must be manually defined before including this header file.
#define	VALUE_TYPE   int
	Stack value type. This must be manually defined before including this header file.
#define	FUNCTION_DEFINITIONS
	Define the functions.
#define	TYPE_DEFINITIONS
	Define the types.
#define	FUNCTION_LINKAGE
	Specify function linkage e.g. static inline.

Functions
fstack_type *	fstack_init (fstack_type *self, const uint32_t capacity)
	Initialize a stack struct, given a capacity.
fstack_type *	fstack_create (const uint32_t capacity)
	Create an stack struct with a given capacity with malloc().
void	fstack_destroy (fstack_type *self)
	Destroy an stack struct and free the underlying memory with free().
bool	fstack_is_empty (const fstack_type *self)
	Return whether the stack is empty.
bool	fstack_is_full (const fstack_type *self)
	Return whether the stack is full.
VALUE_TYPE	fstack_at (const fstack_type *self, const uint32_t index)
	Get the value at index.
VALUE_TYPE	fstack_get_top (const fstack_type *self)
	Get the value from the top of a non-empty stack.
VALUE_TYPE	fstack_get_bottom (const fstack_type *self)
	Get the value from the bottom of a non-empty stack.
VALUE_TYPE	fstack_peek (const fstack_type *self)
	Return whether the stack is empty.
void	fstack_push (fstack_type *self, const VALUE_TYPE value)
	Push a value onto a non-full stack.
VALUE_TYPE	fstack_pop (fstack_type *self)
	Pop a value away from a non-empty stack.
void	fstack_clear (fstack_type *self)
	Clear the elements in the stack.
void	fstack_copy (fstack_type *restrict dest_ptr, const fstack_type *restrict src_ptr)
	Copy the values from a source stack to a destination stack.

Detailed Description

Fixed-size array-based stack.

Macro Definition Documentation

FSTACK_CALC_SIZEOF

#define FSTACK_CALC_SIZEOF	(		fstack_name,
			capacity )

Value:

    (uint32_t)(offsetof(struct fstack_name, values) + capacity * sizeof(((struct fstack_name *)0)->values[0]))

Calculate the size of the stack struct. No overflow checks.

Parameters

[in]	fstack_name	Defined stack NAME.
[in]	capacity	Capacity input.

Returns

The equivalent size.

FSTACK_CALC_SIZEOF_OVERFLOWS

#define FSTACK_CALC_SIZEOF_OVERFLOWS	(		fstack_name,
			capacity )

Value:

    (capacity > (UINT32_MAX - offsetof(struct fstack_name, values)) / sizeof(((struct fstack_name *)0)->values[0]))

Check for a given capacity, if the equivalent size of the stack struct overflows.

Parameters

[in]	fstack_name	Defined stack NAME.
[in]	capacity	Capacity input.

Returns

Whether the equivalent size overflows.

FSTACK_FOR_EACH

#define FSTACK_FOR_EACH	(		self,
			index,
			value )

Value:

    for ((index) = (self)->count; (index) > 0 && ((value) = (self)->values[(index) - 1], true); (index)--)

Iterate over the values in the stack from the top to bottom.

Warning

Modifying the stack under the iteration may result in errors.

Parameters

[in]	self	Stack pointer.
[in]	index	Temporary indexing variable. Should be uint32_t.
[out]	value	Current value. Should be VALUE_TYPE.

Examples

fstack_example.c.

FSTACK_FOR_EACH_REVERSE

#define FSTACK_FOR_EACH_REVERSE	(		self,
			index,
			value )

Value:

    for ((index) = 0; (index) < (self)->count && ((value) = (self)->values[(index)], true); (index)++)

Iterate over the values in the stack from the bottom to top.

Warning

Modifying the stack under the iteration may result in errors.

Parameters

[in]	self	Stack pointer.
[in]	index	Temporary indexing variable. Should be uint32_t.
[out]	value	Current value. Should be VALUE_TYPE.

Examples

fstack_example.c.

JOIN

#define JOIN	(		a,
			b )

Value:

XPASTE(a, XPASTE(_, b))

First expand tokens, then paste them together with a _ in between.

NAME

#define NAME   fstack

Prefix to stack type and operations. This must be manually defined before including this header file.

Is undefined after header is included.

PASTE

#define PASTE	(		a,
			b )

Value:

a##b

Paste two tokens together.

VALUE_TYPE

#define VALUE_TYPE   int

Stack value type. This must be manually defined before including this header file.

Is undefined after header is included.

XPASTE

#define XPASTE	(		a,
			b )

Value:

PASTE(a, b)

First expand tokens, then paste them together.

Function Documentation

fstack_at()

VALUE_TYPE fstack_at	(	const fstack_type *	self,
		const uint32_t	index )

Get the value at index.

Note

Index starts from the top as 0 and is counted upward to count - 1 as bottom.

Parameters

[in]	self	The stack pointer.
[in]	index	The index to retrieve to value from.

Returns

The value at index.

fstack_clear()

void fstack_clear

(

fstack_type *

self

)

Clear the elements in the stack.

Parameters

[in]

self

The stack pointer.

fstack_copy()

void fstack_copy	(	fstack_type *restrict	dest_ptr,
		const fstack_type *restrict	src_ptr )

Copy the values from a source stack to a destination stack.

Parameters

[in,out]	dest_ptr	The destination stack.
[in]	src_ptr	The source stack.

fstack_create()

fstack_type * fstack_create

(

const uint32_t

capacity

)

Create an stack struct with a given capacity with malloc().

Parameters

[in]

capacity

Maximum number of elements.

Returns

A pointer to the stack.

Return values

NULL	If capacity is 0 or the equivalent size overflows If malloc fails.

fstack_destroy()

void fstack_destroy

(

fstack_type *

self

)

Destroy an stack struct and free the underlying memory with free().

Warning

May not be called twice in a row on the same object.

Parameters

[in]

self

The stack pointer.

fstack_get_bottom()

VALUE_TYPE fstack_get_bottom

(

const fstack_type *

self

)

Get the value from the bottom of a non-empty stack.

Parameters

[in]

self

The stack pointer.

Returns

The bottom value.

fstack_get_top()

VALUE_TYPE fstack_get_top

(

const fstack_type *

self

)

Get the value from the top of a non-empty stack.

Parameters

[in]

self

The stack pointer.

Returns

The top value.

fstack_init()

fstack_type * fstack_init	(	fstack_type *	self,
		const uint32_t	capacity )

Initialize a stack struct, given a capacity.

Parameters

[in]	self	Stack pointer
[in]	capacity	Capacity

fstack_is_empty()

bool fstack_is_empty

(

const fstack_type *

self

)

Return whether the stack is empty.

Parameters

[in]

self

The stack pointer.

Returns

Whether the stack is empty.

fstack_is_full()

bool fstack_is_full

(

const fstack_type *

self

)

Return whether the stack is full.

Parameters

[in]

self

The stack pointer.

Returns

Whether the stack is full.

fstack_peek()

VALUE_TYPE fstack_peek

(

const fstack_type *

self

)

Return whether the stack is empty.

Parameters

[in]

self

The stack pointer.

Returns

Whether the stack is empty.

fstack_pop()

VALUE_TYPE fstack_pop

(

fstack_type *

self

)

Pop a value away from a non-empty stack.

Parameters

[in]

self

The stack pointer.

Returns

The top value.

fstack_push()

void fstack_push	(	fstack_type *	self,
		const VALUE_TYPE	value )

Push a value onto a non-full stack.

Parameters

[in]	self	The stack pointer.
[in]	value	The value.