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"]);

Trait Implementations§

Source§

impl<'a, T: Clone> Clone for Stack<'a, T>

Source§

fn clone(&self) -> Stack<'a, T>

Returns a copy of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<T> Debug for Stack<'_, T>
where T: Debug,

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

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

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl<T> Hash for Stack<'_, T>
where T: Hash,

Source§

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl<'a, T> IntoIterator for &'a Stack<'a, T>

Source§

type Item = &'a T

The type of the elements being iterated over.
Source§

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?
Source§

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value. Read more
Source§

impl<T> Ord for Stack<'_, T>
where T: Ord,

Source§

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other. Read more
1.21.0 · Source§

fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · Source§

fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · Source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized,

Restrict a value to a certain interval. Read more
Source§

impl<T, O> PartialEq<[O]> for Stack<'_, T>
where T: PartialEq<O>,

As a convenience, you may directly compare Stacks with slices.

Source§

fn eq(&self, other: &[O]) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl<const N: usize, T, O> PartialEq<[O; N]> for Stack<'_, T>
where T: PartialEq<O>,

As a convenience, you may directly compare Stacks with arrays.

Source§

fn eq(&self, other: &[O; N]) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl<T, O> PartialEq<Stack<'_, O>> for [T]
where T: PartialEq<O>,

As a convenience, you may directly compare Stacks with slices.

Source§

fn eq(&self, other: &Stack<'_, O>) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl<const N: usize, T, O> PartialEq<Stack<'_, O>> for [T; N]
where T: PartialEq<O>,

As a convenience, you may directly compare Stacks with arrays.

Source§

fn eq(&self, other: &Stack<'_, O>) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl<T, O> PartialEq<Stack<'_, O>> for Stack<'_, T>
where T: PartialEq<O>,

Source§

fn eq(&self, other: &Stack<'_, O>) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl<T, O> PartialOrd<Stack<'_, O>> for Stack<'_, T>
where T: PartialOrd<O>,

Source§

fn partial_cmp(&self, other: &Stack<'_, O>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · Source§

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · Source§

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · Source§

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · Source§

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator. Read more
Source§

impl<'a, T: Copy> Copy for Stack<'a, T>

Source§

impl<T> Eq for Stack<'_, T>
where T: Eq,

Auto Trait Implementations§

§

impl<'a, T> Freeze for Stack<'a, T>
where T: Freeze,

§

impl<'a, T> RefUnwindSafe for Stack<'a, T>
where T: RefUnwindSafe,

§

impl<'a, T> Send for Stack<'a, T>
where T: Send + Sync,

§

impl<'a, T> Sync for Stack<'a, T>
where T: Sync,

§

impl<'a, T> Unpin for Stack<'a, T>
where T: Unpin,

§

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

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.