hay 0.1.0

A growable and shrinkable stack array type.
Documentation 
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
    }
}