hay/
lib.rs

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

hay/
lib.rs
