diff --git a/src/interpreter/stack.rs b/src/interpreter/stack.rs index 324c94a..7877da5 100644 --- a/src/interpreter/stack.rs +++ b/src/interpreter/stack.rs @@ -1,18 +1,39 @@ +//! A very light and generic stack implementation, exposing only the +//! operations required by the interpreter. + +/// The `Stackable` trait represents a small basic set of operations +/// required by the interpreter. pub trait Stackable { + /// The kind of item the stack holds. type Item; + /// Checks whether the stack is empty. fn is_empty(&self) -> bool; + + /// Extracts a slice containing the entire stack. fn as_slice(&self) -> &[Self::Item]; + + /// Appends one item to the end of the stack. fn push(&mut self, item: Self::Item); + + /// Removes the last item of the stack and returns it, `None` if + /// the stack is empty. fn pop1(&mut self) -> Option; + + /// Removes `n` elements from the end of the stack, `None` if the + /// stack doesn't contain enough elements. + /// Returned items are ordered by FIFO: the last element comes + /// first in the list. fn pop(&mut self, n: usize) -> Option>; } +/// A stack implementation of the `Stackable` trait, based on a vector. #[derive(Debug, Default)] pub struct Stack where T: Default + Clone, { + /// Inner structure holding the items. inner: Vec, } @@ -20,6 +41,7 @@ impl Stack where T: Default + Clone, { + /// Creates a new empty stack. pub fn new() -> Self { Self { ..Default::default()