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>
impl<'a, T> Stack<'a, T>
Sourcepub const EMPTY_REF: &'a Self
pub const EMPTY_REF: &'a Self
A reference to an empty stack, intended as a terminator for advanced usage.
Sourcepub const fn new() -> Self
pub const fn new() -> Self
Create a new empty stack.
let stack = Stack::<&str>::new();
assert!(stack.is_empty());
Sourcepub const fn of(item: T) -> Self
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"));
Sourcepub const fn pushed(&'a self, item: T) -> Self
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);
Sourcepub const fn len(&self) -> usize
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);
Sourcepub const fn is_empty(&self) -> bool
pub const fn is_empty(&self) -> bool
Returns true
if there are no items in the stack.
assert!(Stack::<&str>::new().is_empty());
Sourcepub const fn get(&self, ix: usize) -> Option<&T>
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);
Sourcepub const fn first(&self) -> Option<&T>
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"));
Sourcepub const fn last(&self) -> Option<&T>
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"));
Sourcepub fn last_mut(&mut self) -> Option<&mut T>
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"));
Sourcepub fn split_last(&self) -> Option<(&T, &'a Self)>
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())));
Sourcepub fn into_split_last(self) -> Option<(T, &'a Self)>
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())));
Sourcepub fn iter(&'a self) -> Iter<'a, T> ⓘ
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"]));
Sourcepub fn with<R>(&self, item: T, f: impl FnOnce(&Stack<'_, T>) -> R) -> R
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"])
})
Sourcepub fn with_all<R>(
&self,
items: impl IntoIterator<Item = T>,
f: impl FnOnce(&Stack<'_, T>) -> R,
) -> R
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"])
})
Sourcepub fn chained(
&'a self,
iter: impl IntoIterator<Item = &'a mut Self>,
) -> &'a Self
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"]);