Struct Stack

Source

pub struct Stack<'a, T> { /* private fields */ }

Expand description

A stack of items, where each item is stored on a program stack frame.

Implemented as a singly linked list.

See module documentation for more.

Implementations§

Source §

impl<'a, T> Stack<'a, T>

Source

pub const EMPTY_REF: &'a Self

A reference to an empty stack, intended as a terminator for advanced usage.

Source

pub const fn new() -> Self

Create a new empty stack.

let stack = Stack::<&str>::new();
assert!(stack.is_empty());

Source

pub const fn of(item: T) -> Self

Create a stack with a single element.

let stack = Stack::of("a");
assert_eq!(stack.len(), 1);
assert_eq!(stack.get(0), Some(&"a"));

Source

pub const fn pushed(&'a self, item: T) -> Self

Return a new stack, with the given item at the top, which follows from self.

let a = Stack::of("a");
let ab = a.pushed("b");

assert_eq!(a.len(), 1);
assert_eq!(ab.len(), 2);

Source

pub const fn len(&self) -> usize

Returns the number of items in the stack.

assert_eq!(Stack::<&str>::new().len(), 0);
assert_eq!(Stack::of("a").len(), 1);

Source

pub const fn is_empty(&self) -> bool

Returns true if there are no items in the stack.

assert!(Stack::<&str>::new().is_empty());

Source

pub const fn get(&self, ix: usize) -> Option<&T>

Get an item by 0-based index, starting at the bottom of the stack.

let mut storage;
let abcd = stack!(["a", "b", "c", "d"] in storage);
assert_eq!(abcd.get(0), Some(&"a"));
assert_eq!(abcd.get(3), Some(&"d"));
assert_eq!(abcd.get(4), None);

Source

pub const fn first(&self) -> Option<&T>

Get the item at the bottom of the stack, or None if it is empty.

assert_eq!(Stack::<&str>::new().first(), None);
assert_eq!(Stack::of("a").pushed("b").first(), Some(&"a"));

Source

pub const fn last(&self) -> Option<&T>

Get the item at the top of the stack, or None if it is empty.

assert_eq!(Stack::<&str>::new().last(), None);
assert_eq!(Stack::of("a").pushed("b").last(), Some(&"b"));

Source

pub fn last_mut(&mut self) -> Option<&mut T>

Get a mutable reference to the item at the top of the stack, or None if it is empty.

let mut stack = Stack::of("a");
*stack.last_mut().unwrap() = "b";
assert_eq!(stack.last(), Some(&"b"));

Source

pub fn split_last(&self) -> Option<(&T, &'a Self)>

Return the top of the stack, and the rest, or None if it is empty.

assert_eq!(Stack::<&str>::new().split_last(), None);
assert_eq!(Stack::of("a").split_last(), Some((&"a", &Stack::new())));

Source

pub fn into_split_last(self) -> Option<(T, &'a Self)>

Consumes the stack, returning the top item and its predecessor (or None if it was empty.)

assert_eq!(Stack::<&str>::new().into_split_last(), None);
assert_eq!(Stack::of("a").into_split_last(), Some(("a", &Stack::new())));

Source

pub fn iter(&'a self) -> Iter<'a, T> ⓘ

Return an Iterator of items in the stack, from the bottom to the top.

Note that the returned item implements DoubleEndedIterator.

let mut storage;
let abcd = stack!(["a", "b", "c", "d"] in storage);
assert!(abcd.iter().eq(&["a", "b", "c", "d"]));
assert!(abcd.iter().rev().eq(&["d", "c", "b", "a"]));

Source

pub fn with<R>(&self, item: T, f: impl FnOnce(&Stack<'_, T>) -> R) -> R

Execute the given closure on the current list with the given item appended.

Stack::of("a").with("b", |ab| {
    assert_eq!(ab, &["a", "b"])
})

Source

pub fn with_all<R>( &self, items: impl IntoIterator<Item = T>, f: impl FnOnce(&Stack<'_, T>) -> R, ) -> R

Extend the current stack with each item from the given iterator, calling the given closure on the result.

This creates a program stack frame for each item in the iterator - beware when using with long iterators.

use stackstack::Stack;
let a = Stack::of("a");
a.with_all(["b", "c", "d"], |abcd| {
    assert_eq!(abcd, &["a", "b", "c", "d"])
})

Source

pub fn chained( &'a self, iter: impl IntoIterator<Item = &'a mut Self>, ) -> &'a Self

Edit all the non-empty stacks in the given iterator to follow from self, returning the new head of the stack.

Note that only the last items are chained together.

This is useful for appending items in some scratch space.

let mut scratch = ["b", "c", "d"].map(Stack::of);
let a = Stack::of("a");
let abcd = a.chained(&mut scratch);
assert_eq!(abcd, &["a", "b", "c", "d"]);

let e = Stack::of("f");
let mut ef = e.pushed("f");
//           ^~ will be ignored because it's not the last item
let abcdf = abcd.chained([&mut ef]);
assert_eq!(abcdf, &["a", "b", "c", "d", /* e */ "f"]);