Trait midenc_hir::Stack

pub trait Stack: IndexMut<usize, Output = Self::Element> {
    type Element: StackElement;

    // Required methods
    fn stack(&self) -> &Vec<Self::Element>;
    fn stack_mut(&mut self) -> &mut Vec<Self::Element>;
    fn clear(&mut self);

    // Provided methods
    fn debug(&self) -> DebugStack<'_, Self> { ... }
    fn is_empty(&self) -> bool { ... }
    fn len(&self) -> usize { ... }
    fn peek(&self) -> Option<Self::Element> { ... }
    fn peekw(&self) -> Option<[Self::Element; 4]> { ... }
    fn padw(&mut self) { ... }
    fn push(&mut self, value: Self::Element) { ... }
    fn pushw(&mut self, word: [Self::Element; 4]) { ... }
    fn pop(&mut self) -> Option<Self::Element> { ... }
    fn popw(&mut self) -> Option<[Self::Element; 4]> { ... }
    fn drop(&mut self) { ... }
    fn dropw(&mut self) { ... }
    fn dropn(&mut self, n: usize) { ... }
    fn dup(&mut self, n: usize) { ... }
    fn dupw(&mut self, n: usize) { ... }
    fn swap(&mut self, n: usize) { ... }
    fn swapw(&mut self, n: usize) { ... }
    fn swapdw(&mut self) { ... }
    fn movup(&mut self, n: usize) { ... }
    fn movupw(&mut self, n: usize) { ... }
    fn movdn(&mut self, n: usize) { ... }
    fn movdnw(&mut self, n: usize) { ... }
}

This trait is used to represent the basic plumbing of the operand stack in Miden Assembly.

Implementations of this trait may attach different semantics to the meaning of elements on the stack. As a result, certain operations which are contingent on the specific value of an element, may behave differently depending on the specific implementation.

In general however, it is expected that use of this trait in a generic context will be rare, if ever the case. As mentioned above, it is meant to handle the common plumbing of an operand stack implementation, but in practice users will be working with a concrete implementation with this trait in scope to provide access to the basic functionality of the stack.

It is expected that implementations will override functions in this trait as necessary to implement custom behavior above and beyond what is provided by the default implementation.

Required Associated Types

type Element: StackElement

Required Methods

fn stack(&self) -> &Vec<Self::Element>

Return a reference to the underlying “raw” stack data structure, a vector

fn stack_mut(&mut self) -> &mut Vec<Self::Element>

Return a mutable reference to the underlying “raw” stack data structure, a vector

fn clear(&mut self)

Clear the contents of this stack while keeping the underlying memory allocated for reuse.

Provided Methods

fn debug(&self) -> DebugStack<'_, Self>

Display this stack using its debugging representation

fn is_empty(&self) -> bool

Returns true if the operand stack is empty

fn len(&self) -> usize

Returns the number of elements on the stack

fn peek(&self) -> Option<Self::Element>

Returns the value on top of the stack, without consuming it

fn peekw(&self) -> Option<[Self::Element; 4]>

Returns the word on top of the stack, without consuming it

The top of the stack will be the first element of the word

fn padw(&mut self)

Pushes a word of zeroes on top of the stack

fn push(&mut self, value: Self::Element)

Pushes value on top of the stac

fn pushw(&mut self, word: [Self::Element; 4])

Pushes word on top of the stack

The first element of word will be on top of the stack

fn pop(&mut self) -> Option<Self::Element>

Pops the value on top of the stack

fn popw(&mut self) -> Option<[Self::Element; 4]>

Pops the first word on top of the stack

The top of the stack will be the first element in the result

fn drop(&mut self)

Drops the top item on the stack

fn dropw(&mut self)

Drops the top word on the stack

fn dropn(&mut self, n: usize)

fn dup(&mut self, n: usize)

Duplicates the value in the nth position on the stack

If n is 0, duplicates the top of the stack.

fn dupw(&mut self, n: usize)

Duplicates the nth word on the stack, to the top of the stack.

Valid values for n are 0, 1, 2, or 3.

If n is 0, duplicates the top word of the stack.

fn swap(&mut self, n: usize)

Swaps the nth value from the top of the stack, with the top of the stack

If n is 1, it swaps the first two elements on the stack.

NOTE: This function will panic if n is 0, or out of bounds.

fn swapw(&mut self, n: usize)

Swaps the nth word from the top of the stack, with the word on top of the stack

If n is 1, it swaps the first two words on the stack.

Valid values for n are: 1, 2, 3.

fn swapdw(&mut self)

Swaps the top two and bottom two words on the stack.

fn movup(&mut self, n: usize)

Moves the nth value to the top of the stack

If n is 1, this is equivalent to swap(1).

NOTE: This function will panic if n is 0, or out of bounds.

fn movupw(&mut self, n: usize)

Moves the nth word to the top of the stack

If n is 1, this is equivalent to swapw(1).

Valid values for n are: 1, 2, 3

fn movdn(&mut self, n: usize)

Makes the value on top of the stack, the nth value on the stack

If n is 1, this is equivalent to swap(1).

NOTE: This function will panic if n is 0, or out of bounds.

fn movdnw(&mut self, n: usize)

Makes the word on top of the stack, the nth word on the stack

If n is 1, this is equivalent to swapw(1).

Valid values for n are: 1, 2, 3

Object Safety

This trait is not object safe.

Implementors

impl<T: StackElement> Stack for OperandStack<T>

type Element = T