hay/lib.rs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
//! A growable and shrinkable stack array type.
#![cfg_attr(not(test), no_std)]
#![warn(missing_docs)]
extern crate alloc;
use alloc::vec::Vec;
/// A growable and shrinkable stack array type.
///
/// # Example
/// ```
/// use hay::Stack;
/// let mut stack = Stack::new();
/// stack.push(1);
/// stack.push(2);
/// assert_eq!(stack.len(), 2);
/// assert_eq!(stack.pop(), Some(2));
/// assert_eq!(stack.pop(), Some(1));
/// assert_eq!(stack.pop(), None);
/// ```
/// <b> ~24 bytes on the stack!!! </b>
#[derive(Clone, Debug, Default, Hash, PartialEq, Eq, PartialOrd, Ord)]
pub struct Stack<T> {
vec: Vec<T>,
}
impl<T> Stack<T> {
/// Constructs a new, empty `Stack<T>`.
///
/// The stack will not allocate until elements are pushed onto it.
/// # Example
/// ```
/// use hay::Stack;
/// let mut stack: Stack<i32> = Stack::<i32>::new();
/// ```
#[inline(always)]
pub const fn new() -> Self {
Self { vec: Vec::new() }
}
/// Appends an element to the top of the stack.
/// # Panics
/// Panics if the new capacity exceeds `isize::MAX`.
/// # Example
/// ```
/// use hay::Stack;
/// let mut stack = Stack::new();
/// stack.push(1);
/// assert_eq!(stack.pop(), Some(1));
/// ```
#[inline(always)]
pub fn push(&mut self, value: T) {
self.vec.push(value);
}
/// Removes the element at the top of the stack and returns it, or [None] if it is empty.
/// # Example
/// ```
/// use hay::Stack;
/// let mut stack = Stack::new();
/// stack.push(1);
/// assert_eq!(stack.pop(), Some(1));
/// ```
#[inline(always)]
pub fn pop(&mut self) -> Option<T> {
self.vec.pop()
}
/// Clears the stack, popping all values.
///
/// Note that this method has no effect on the allocated capacity of the stack.
/// # Example
/// ```
/// use hay::Stack;
/// let mut stack = Stack::new();
/// stack.push(1);
/// stack.push(2);
/// stack.push(3);
/// stack.clear();
/// assert_eq!(stack.pop(), None);
/// ```
#[inline(always)]
pub fn clear(&mut self) {
self.vec.clear();
}
/// Returns the number of elements on the stack, also referred to as it's 'length'.
/// # Example
/// ```
/// use hay::Stack;
/// let mut stack = Stack::new();
/// stack.push(1);
/// stack.push(2);
/// assert_eq!(stack.len(), 2);
/// ```
#[inline(always)]
pub fn len(&self) -> usize {
self.vec.len()
}
/// Extracts a vector containing the entire stack.
/// # Example
/// ```
/// use hay::Stack;
/// let mut stack = Stack::new();
/// stack.push(0);
/// stack.push(1);
/// stack.push(2);
/// let slice = unsafe { stack.as_vec().as_slice() };
/// assert_eq!(slice, &[0, 1, 2]);
/// ```
#[inline(always)]
pub const fn as_vec(&self) -> &Vec<T> {
&self.vec
}
/// Extracts a mutable vector containing the entire stack.
/// # Example
/// ```
/// use hay::Stack;
/// let mut stack = Stack::new();
/// stack.push(2);
/// unsafe { stack.as_mut_vec().insert(0, 1) };
/// assert_eq!(stack.len(), 2);
/// assert_eq!(stack.pop(), Some(2));
/// assert_eq!(stack.pop(), Some(1));
/// assert_eq!(stack.pop(), None);
/// ```
#[inline(always)]
pub fn as_mut_vec(&mut self) -> &mut Vec<T> {
&mut self.vec
}
}