Package org.apache.pivot.collections

Class ArrayStack<T>

  • Type Parameters:
    T - The type of elements stored in this stack.
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<T>, Collection<T>, Stack<T>
    public class ArrayStack<T>
extends java.lang.Object
implements Stack<T>, java.io.Serializable
    Implementation of the Stack interface that is backed by an ArrayList.

    Note: a stack with a comparator set is more like a priority queue than a stack because it no longer maintains the LIFO (last-in, first-out) ordering of a normal stack.

    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      ArrayStack()
      Construct an empty stack, with all defaults.
      ArrayStack​(int capacity)
      Construct an empty stack with the given initial capacity.
      ArrayStack​(int capacity, int depth)
      Construct an empty stack with the given initial capacity and maximum depth.
      ArrayStack​(int capacity, int depth, java.util.Comparator<T> comparator)
      Construct an empty stack with the given initial capacity, maximum stack depth, and comparator used to order the stack elements.
      ArrayStack​(java.util.Comparator<T> comparator)
      Construct an empty stack with the given comparator used to order the elemnts in it.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clear()
      Removes all elements from the collection.
      void ensureCapacity​(int capacity)
      Ensure that the stack has sufficient internal capacity to satisfy the given number of elements.
      java.util.Comparator<T> getComparator()
      Returns the collection's sort order.
      int getDepth()  
      int getMaxDepth()  
      ListenerList<StackListener<T>> getStackListeners()  
      boolean isEmpty()
      Tests the emptiness of the stack.
      java.util.Iterator<T> iterator()  
      T peek()
      Returns the item on top of the stack without removing it from the stack.
      T pop()
      Removes the top item from the stack and returns it.
      void push​(T item)
      "Pushes" an item onto the stack.
      void setComparator​(java.util.Comparator<T> comparator)
      Set/remove the comparator for this stack.
      void setMaxDepth​(int depth)
      Set the maximum depth permitted for this stack, 0 means unlimited.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Constructor Detail

      • ArrayStack

        public ArrayStack()
        Construct an empty stack, with all defaults.

      • ArrayStack

        public ArrayStack​(java.util.Comparator<T> comparator)
        Construct an empty stack with the given comparator used to order the elemnts in it.
        Parameters:
        comparator - A comparator used to sort the elements in the stack as they are pushed.

      • ArrayStack

        public ArrayStack​(int capacity)
        Construct an empty stack with the given initial capacity.
        Parameters:
        capacity - The initial capacity for the stack.

      • ArrayStack

        public ArrayStack​(int capacity,
                  int depth)
        Construct an empty stack with the given initial capacity and maximum depth.
        Parameters:
        capacity - The initial capacity for the stack.
        depth - The maximum depth to enforce for this stack (0 = unlimited).

      • ArrayStack

        public ArrayStack​(int capacity,
                  int depth,
                  java.util.Comparator<T> comparator)
        Construct an empty stack with the given initial capacity, maximum stack depth, and comparator used to order the stack elements.
        Parameters:
        capacity - The initial stack capacity.
        depth - The maximum stack depth to enforce (0 = unlimited).
        comparator - The comparator to use to order the stack elements.

    • Method Detail

      • getMaxDepth

        public int getMaxDepth()
        Specified by:
        getMaxDepth in interface Stack<T>
        Returns:
        The maximum depth this stack is permitted to reach, where 0 means unlimited.

      • setMaxDepth

        public void setMaxDepth​(int depth)
        Set the maximum depth permitted for this stack, 0 means unlimited.
        Specified by:
        setMaxDepth in interface Stack<T>
        Parameters:
        depth - The new maximum depth for this stack.

      • push

        public void push​(T item)
        Description copied from interface: Stack
        "Pushes" an item onto the stack. If the stack is unsorted, the item is added at the top of the stack (getLength()). Otherwise, it is inserted at the appropriate index.

        If there is a maximum stack depth defined and the stack goes past this maximum depth, the deepest item (which could be this new item, depending on the comparator) will be removed.

        Specified by:
        push in interface Stack<T>
        Parameters:
        item - The item to push onto the stack.

      • pop

        public T pop()
        Description copied from interface: Stack
        Removes the top item from the stack and returns it.
        Specified by:
        pop in interface Stack<T>
        Returns:
        The top item from the stack (removed from it).

      • peek

        public T peek()
        Description copied from interface: Stack
        Returns the item on top of the stack without removing it from the stack. Returns null if the stack contains no items. Will also return null if the top item in the stack is null. getLength() can be used to distinguish between these two cases.
        Specified by:
        peek in interface Stack<T>
        Returns:
        The top item from the stack (which remains there).

      • clear

        public void clear()
        Description copied from interface: Collection
        Removes all elements from the collection.
        Specified by:
        clear in interface Collection<T>

      • isEmpty

        public boolean isEmpty()
        Description copied from interface: Stack
        Tests the emptiness of the stack.
        Specified by:
        isEmpty in interface Collection<T>
        Specified by:
        isEmpty in interface Stack<T>
        Returns:
        true if the stack contains no items; false, otherwise.

      • getDepth

        public int getDepth()
        Specified by:
        getDepth in interface Stack<T>
        Returns:
        The stack depth.

      • ensureCapacity

        public void ensureCapacity​(int capacity)
        Ensure that the stack has sufficient internal capacity to satisfy the given number of elements.
        Parameters:
        capacity - The capacity to ensure (to make sure no further allocations are done to accommodate this number of elements).

      • getComparator

        public java.util.Comparator<T> getComparator()
        Description copied from interface: Collection
        Returns the collection's sort order.
        Specified by:
        getComparator in interface Collection<T>
        Returns:
        The comparator used to order elements in the collection, or null if the sort order is undefined.
        See Also:
        Collection.setComparator(Comparator)

      • setComparator

        public void setComparator​(java.util.Comparator<T> comparator)
        Set/remove the comparator for this stack.

        Setting a non-null comparator changes this stack to a priority queue, because LIFO ordering is no longer maintained.

        If a new comparator is set the stack will be reordered if it contains any elements. Removing the comparator will not reorder any elements.

        Calls the StackListener.comparatorChanged(org.apache.pivot.collections.Stack<T>, java.util.Comparator<T>) method for each registered listener after setting the new comparator.

        Specified by:
        setComparator in interface Collection<T>
        Parameters:
        comparator - The new comparator used to order the elements in the stack. Can be null to remove the existing comparator.

      • iterator

        public java.util.Iterator<T> iterator()
        Specified by:
        iterator in interface java.lang.Iterable<T>