Interface ValueStack<V>

Type Parameters:
V - the type of the value objects
All Superinterfaces:
Iterable<V>
All Known Implementing Classes:
DebuggingValueStack, DefaultValueStack

public interface ValueStack<V> extends Iterable<V>
A ValueStack is a stack implementation for parser values. The current state of the stack can be saved and restored with the methods takeSnapshot() and restoreSnapshot(Object) ()}, whose implementations should be super efficient since they are being used extensively during a parsing run. A ValueStack also serves as an Iterable over the current stack values (the values are being provided with the last value (on top of the stack) first).
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Clears all values.
    void
    dup()
    Duplicates the top value.
    boolean
    Determines whether the stack is empty.
    Returns the value at the top of the stack without removing it.
    peek(int down)
    Returns the value the given number of elements below the top of the stack without removing it.
    void
    poke(int down, V value)
    Replaces the element the given number of elements below the current top of the stack.
    void
    poke(V value)
    Replaces the current top value with the given value.
    pop()
    Removes the value at the top of the stack and returns it.
    pop(int down)
    Removes the value the given number of elements below the top of the stack.
    void
    push(int down, V value)
    Inserts the given value a given number of elements below the current top of the stack.
    void
    push(V value)
    Pushes the given value onto the stack.
    void
    pushAll(Iterable<V> values)
    Pushes all given elements onto the stack (in the order as given).
    void
    pushAll(V firstValue, V... moreValues)
    Pushes all given elements onto the stack (in the order as given).
    void
    Restores the stack state as previously returned by takeSnapshot().
    int
    Returns the number of elements currently on the stack.
    void
    Swaps the top two stack values.
    void
    Reverses the order of the top 3 stack values.
    void
    Reverses the order of the top 4 stack values.
    void
    Reverses the order of the top 5 stack values.
    void
    Reverses the order of the top 5 stack values.
    Returns an object representing the current state of the stack.

    Methods inherited from interface java.lang.Iterable

    forEach, iterator, spliterator
  • Method Details

    • isEmpty

      boolean isEmpty()
      Determines whether the stack is empty.
      Returns:
      true if empty
    • size

      int size()
      Returns the number of elements currently on the stack.
      Returns:
      the number of elements
    • clear

      void clear()
      Clears all values.
    • takeSnapshot

      Object takeSnapshot()
      Returns an object representing the current state of the stack. This cost of running this operation is negligible and independent from the size of the stack.
      Returns:
      an object representing the current state of the stack
    • restoreSnapshot

      void restoreSnapshot(Object snapshot)
      Restores the stack state as previously returned by takeSnapshot(). This cost of running this operation is negligible and independent from the size of the stack.
      Parameters:
      snapshot - a snapshot object previously returned by takeSnapshot()
    • push

      void push(V value)
      Pushes the given value onto the stack. Equivalent to push(0, value).
      Parameters:
      value - the value
    • push

      void push(int down, V value)
      Inserts the given value a given number of elements below the current top of the stack.
      Parameters:
      down - the number of elements to skip before inserting the value (0 being equivalent to push(value))
      value - the value
      Throws:
      IllegalArgumentException - if the stack does not contain enough elements to perform this operation
    • pushAll

      void pushAll(V firstValue, V... moreValues)
      Pushes all given elements onto the stack (in the order as given).
      Parameters:
      firstValue - the first value
      moreValues - the other values
    • pushAll

      void pushAll(Iterable<V> values)
      Pushes all given elements onto the stack (in the order as given).
      Parameters:
      values - the values
    • pop

      V pop()
      Removes the value at the top of the stack and returns it.
      Returns:
      the current top value
      Throws:
      IllegalArgumentException - if the stack is empty
    • pop

      V pop(int down)
      Removes the value the given number of elements below the top of the stack.
      Parameters:
      down - the number of elements to skip before removing the value (0 being equivalent to pop())
      Returns:
      the value
      Throws:
      IllegalArgumentException - if the stack does not contain enough elements to perform this operation
    • peek

      V peek()
      Returns the value at the top of the stack without removing it.
      Returns:
      the current top value
      Throws:
      IllegalArgumentException - if the stack is empty
    • peek

      V peek(int down)
      Returns the value the given number of elements below the top of the stack without removing it.
      Parameters:
      down - the number of elements to skip (0 being equivalent to peek())
      Returns:
      the value
      Throws:
      IllegalArgumentException - if the stack does not contain enough elements to perform this operation
    • poke

      void poke(V value)
      Replaces the current top value with the given value. Equivalent to poke(0, value).
      Parameters:
      value - the value
      Throws:
      IllegalArgumentException - if the stack is empty
    • poke

      void poke(int down, V value)
      Replaces the element the given number of elements below the current top of the stack.
      Parameters:
      down - the number of elements to skip before replacing the value (0 being equivalent to poke(value))
      value - the value to replace with
      Throws:
      IllegalArgumentException - if the stack does not contain enough elements to perform this operation
    • dup

      void dup()
      Duplicates the top value. Equivalent to push(peek()).
      Throws:
      IllegalArgumentException - if the stack is empty
    • swap

      void swap()
      Swaps the top two stack values.
      Throws:
      GrammarException - if the stack does not contain at least two elements
    • swap3

      void swap3()
      Reverses the order of the top 3 stack values.
      Throws:
      GrammarException - if the stack does not contain at least 3 elements
    • swap4

      void swap4()
      Reverses the order of the top 4 stack values.
      Throws:
      GrammarException - if the stack does not contain at least 4 elements
    • swap5

      void swap5()
      Reverses the order of the top 5 stack values.
      Throws:
      GrammarException - if the stack does not contain at least 5 elements
    • swap6

      void swap6()
      Reverses the order of the top 5 stack values.
      Throws:
      GrammarException - if the stack does not contain at least 5 elements