astack offers a [Stack] data structure with fixed capacity aimed at fast LIFO operations.

The crate contains:

• A [Stack] struct, the object used to perform stack operations such as [push][Stack::push] and [pop][Stack::pop].
• A [stack] macro, used to conveniently construct a new [Stack].
• A [StackOverflowError], emitted by [Stack] if an operation would have resulted in a stack overflow.

astack may be used in both std and non-std environments, and is therefore considered platform-agnostic.

Examples

Creating an empty Stack.

use astack::{stack, Stack};

// Through the Stack::new() method
let stack = Stack::<u64, 10>::new();

// Through the stack! macro
let stack = stack![u64; 10];

Creating a Stack with already some items inside.

use astack::stack;

// Through the stack! macro
let stack = stack! {
[u64; 10] = [1, 2, 3]
};

Creating a Stack filled with items.

use astack::Stack;

// A Stack filled with one single Copy item.
let stack_of_44 = Stack::<u64, 10>::fill_with_copy(44);

// A Stack filled with the Default implementation of `T`.
let stack_of_default = Stack::<u64, 10>::fill_with_default();

// A Stack filled with a value based on the result of a function.
let stack = Stack::<String, 10>::fill_with_fn(|i| {
format!("Value n. {}", i)
});

Common Stack operations

use astack::stack;

// Create a new Stack.
let mut stack = stack! {
[i32; 4] = [10, 20, 30]
};

// Add an item as TOS. This returns Err if the stack if full.
stack.push(40).unwrap();

// Pop TOS. This returns None if the stack is empty.
let last_value = stack.pop().unwrap();

// Get a reference to TOS. This returns None if the stack is empty.
let top_of_the_stack = stack.tos().unwrap();

// Get a mutable reference to TOS. This returns None if the stack is empty.
let top_of_the_stack_mut = stack.tos_mut().unwrap();