Class ObjectStack


  • public class ObjectStack
    extends java.lang.Object
    Growable Object stack with type specific access methods. This implementation is unsynchronized in order to provide the best possible performance for typical usage scenarios, so explicit synchronization must be implemented by a wrapper class or directly by the application in cases where instances are modified in a multithreaded environment.
    Author:
    Dennis M. Sosnoski
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int DEFAULT_SIZE
      Default initial array size.
      protected java.lang.Object[] m_baseArray
      The underlying array used for storing the data.
      protected int m_countLimit
      Size of the current array.
      protected int m_countPresent
      The number of values currently present in the stack.
      protected int m_maximumGrowth
      Maximum size increment for growing array.
    • Constructor Summary

      Constructors 
      Constructor Description
      ObjectStack()
      Default constructor.
      ObjectStack​(int size)
      Constructor with initial size specified.
      ObjectStack​(int size, int growth)
      Constructor with full specification.
      ObjectStack​(java.lang.Object[] strings)
      Constructor from array of strings.
      ObjectStack​(ObjectStack base)
      Copy (clone) constructor.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clear()
      Set the stack to the empty state.
      java.lang.Object clone()
      Duplicates the object with the generic call.
      private void discardValues​(int from, int to)
      Discards values for a range of indices in the array.
      void ensureCapacity​(int min)
      Ensure that the array has the capacity for at least the specified number of values.
      private int getAddIndex()
      Gets the array offset for appending a value to those in the stack.
      private void growArray​(int required)
      Increase the size of the array to at least a specified size.
      boolean isEmpty()
      Check if stack is empty.
      java.lang.Object peek()
      Copy top value from the stack.
      java.lang.Object peek​(int depth)
      Copy a value from the stack.
      java.lang.Object pop()
      Pop a value from the stack.
      java.lang.Object pop​(int count)
      Pop multiple values from the stack.
      void push​(java.lang.Object value)
      Push a value on the stack.
      private void resizeCopy​(java.lang.Object base, java.lang.Object grown)
      Copy data after array resize.
      int size()
      Get the number of values currently present in the stack.
      java.lang.Object[] toArray()
      Constructs and returns a simple array containing the same data as held in this stack.
      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • DEFAULT_SIZE

        public static final int DEFAULT_SIZE
        Default initial array size.
        See Also:
        Constant Field Values
      • m_countLimit

        protected int m_countLimit
        Size of the current array.
      • m_countPresent

        protected int m_countPresent
        The number of values currently present in the stack.
      • m_maximumGrowth

        protected int m_maximumGrowth
        Maximum size increment for growing array.
      • m_baseArray

        protected java.lang.Object[] m_baseArray
        The underlying array used for storing the data.
    • Constructor Detail

      • ObjectStack

        public ObjectStack​(int size,
                           int growth)
        Constructor with full specification.
        Parameters:
        size - number of Object values initially allowed in stack
        growth - maximum size increment for growing stack
      • ObjectStack

        public ObjectStack​(int size)
        Constructor with initial size specified.
        Parameters:
        size - number of Object values initially allowed in stack
      • ObjectStack

        public ObjectStack()
        Default constructor.
      • ObjectStack

        public ObjectStack​(ObjectStack base)
        Copy (clone) constructor.
        Parameters:
        base - instance being copied
      • ObjectStack

        public ObjectStack​(java.lang.Object[] strings)
        Constructor from array of strings.
        Parameters:
        strings - array of strings for initial contents
    • Method Detail

      • resizeCopy

        private void resizeCopy​(java.lang.Object base,
                                java.lang.Object grown)
        Copy data after array resize. This just copies the entire contents of the old array to the start of the new array. It should be overridden in cases where data needs to be rearranged in the array after a resize.
        Parameters:
        base - original array containing data
        grown - resized array for data
      • discardValues

        private void discardValues​(int from,
                                   int to)
        Discards values for a range of indices in the array. Checks if the values stored in the array are object references, and if so clears them. If the values are primitives, this method does nothing.
        Parameters:
        from - index of first value to be discarded
        to - index past last value to be discarded
      • growArray

        private void growArray​(int required)
        Increase the size of the array to at least a specified size. The array will normally be at least doubled in size, but if a maximum size increment was specified in the constructor and the value is less than the current size of the array, the maximum increment will be used instead. If the requested size requires more than the default growth, the requested size overrides the normal growth and determines the size of the replacement array.
        Parameters:
        required - new minimum size required
      • ensureCapacity

        public final void ensureCapacity​(int min)
        Ensure that the array has the capacity for at least the specified number of values.
        Parameters:
        min - minimum capacity to be guaranteed
      • push

        public void push​(java.lang.Object value)
        Push a value on the stack.
        Parameters:
        value - value to be added
      • pop

        public java.lang.Object pop()
        Pop a value from the stack.
        Returns:
        value from top of stack
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - on attempt to pop empty stack
      • pop

        public java.lang.Object pop​(int count)
        Pop multiple values from the stack. The last value popped is the one returned.
        Parameters:
        count - number of values to pop from stack (must be strictly positive)
        Returns:
        value from top of stack
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - on attempt to pop past end of stack
      • peek

        public java.lang.Object peek​(int depth)
        Copy a value from the stack. This returns a value from within the stack without modifying the stack.
        Parameters:
        depth - depth of value to be returned
        Returns:
        value from stack
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - on attempt to peek past end of stack
      • peek

        public java.lang.Object peek()
        Copy top value from the stack. This returns the top value without removing it from the stack.
        Returns:
        value at top of stack
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - on attempt to peek empty stack
      • toArray

        public java.lang.Object[] toArray()
        Constructs and returns a simple array containing the same data as held in this stack. Note that the items will be in reverse pop order, with the last item to be popped from the stack as the first item in the array.
        Returns:
        array containing a copy of the data
      • clone

        public java.lang.Object clone()
        Duplicates the object with the generic call.
        Overrides:
        clone in class java.lang.Object
        Returns:
        a copy of the object
      • getAddIndex

        private int getAddIndex()
        Gets the array offset for appending a value to those in the stack. If the underlying array is full, it is grown by the appropriate size increment so that the index value returned is always valid for the array in use by the time of the return.
        Returns:
        index position for added element
      • size

        public int size()
        Get the number of values currently present in the stack.
        Returns:
        count of values present
      • isEmpty

        public boolean isEmpty()
        Check if stack is empty.
        Returns:
        true if stack empty, false if not
      • clear

        public void clear()
        Set the stack to the empty state.