fstack.h File Reference

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

#include "paste.h"
#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	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.

Functions
static fstack_type *	fstack_init (fstack_type *self, const uint32_t capacity)
	Initialize a stack struct, given a capacity.
static fstack_type *	fstack_create (const uint32_t capacity)
	Create an stack struct with a given capacity with malloc().
static void	fstack_destroy (fstack_type *self)
	Destroy an stack struct and free the underlying memory with free().
static bool	fstack_is_empty (const fstack_type *self)
	Return whether the stack is empty.
static bool	fstack_is_full (const fstack_type *self)
	Return whether the stack is full.
static VALUE_TYPE	fstack_at (const fstack_type *self, const uint32_t index)
	Get the value at index.
static VALUE_TYPE	fstack_get_top (const fstack_type *self)
	Get the value from the top of a non-empty stack.
static VALUE_TYPE	fstack_get_bottom (const fstack_type *self)
	Get the value from the bottom of a non-empty stack.
static VALUE_TYPE	fstack_peek (const fstack_type *self)
	Peek a non-empty stack and get it's next to-be-popped value.
static void	fstack_push (fstack_type *self, const VALUE_TYPE value)
	Push a value onto a non-full stack.
static VALUE_TYPE	fstack_pop (fstack_type *self)
	Pop a value away from a non-empty stack.
static void	fstack_clear (fstack_type *self)
	Clear the elements in the stack.
static 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.

The following macros must be defined:

• NAME
• VALUE_TYPE

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.

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.

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.

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.

Function Documentation

fstack_at()

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

inlinestatic

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()

static void fstack_clear ( fstack_type * self )

inlinestatic

Clear the elements in the stack.

Parameters

[in]

self

The stack pointer.

fstack_copy()

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

inlinestatic

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()

static fstack_type * fstack_create ( const uint32_t capacity )

inlinestatic

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()

static void fstack_destroy ( fstack_type * self )

inlinestatic

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()

static VALUE_TYPE fstack_get_bottom ( const fstack_type * self )

inlinestatic

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

Parameters

[in]

self

The stack pointer.

Returns

The bottom value.

fstack_get_top()

static VALUE_TYPE fstack_get_top ( const fstack_type * self )

inlinestatic

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

Parameters

[in]

self

The stack pointer.

Returns

The top value.

fstack_init()

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

inlinestatic

Initialize a stack struct, given a capacity.

Parameters

[in]	self	Stack pointer
[in]	capacity	Capacity

fstack_is_empty()

static bool fstack_is_empty ( const fstack_type * self )

inlinestatic

Return whether the stack is empty.

Parameters

[in]

self

The stack pointer.

Returns

Whether the stack is empty.

fstack_is_full()

static bool fstack_is_full ( const fstack_type * self )

inlinestatic

Return whether the stack is full.

Parameters

[in]

self

The stack pointer.

Returns

Whether the stack is full.

fstack_peek()

static VALUE_TYPE fstack_peek ( const fstack_type * self )

inlinestatic

Peek a non-empty stack and get it's next to-be-popped value.

Parameters

[in]

self

The stack pointer.

Returns

The next to-be-popped value.

fstack_pop()

static VALUE_TYPE fstack_pop ( fstack_type * self )

inlinestatic

Pop a value away from a non-empty stack.

Parameters

[in]

self

The stack pointer.

Returns

The top value.

fstack_push()

static void fstack_push ( fstack_type * self, const VALUE_TYPE value )

inlinestatic

Push a value onto a non-full stack.

Parameters

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