StackBase


1   /*
2    * Copyright (c) 2000-2001 Sosnoski Software Solutions, Inc.
3    *
4    * Permission is hereby granted, free of charge, to any person obtaining a copy
5    * of this software and associated documentation files (the "Software"), to deal
6    * in the Software without restriction, including without limitation the rights 
7    * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
8    * copies of the Software, and to permit persons to whom the Software is 
9    * furnished to do so, subject to the following conditions:
10   *
11   * The above copyright notice and this permission notice shall be included in 
12   * all copies or substantial portions of the Software.
13   *
14   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
15   * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
16   * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
17   * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
18   * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
19   * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 
20   * IN THE SOFTWARE.
21   */
22  
23  package com.sosnoski.util.stack;
24  
25  import com.sosnoski.util.*;
26  
27  /**
28   * Base class for type-specific stack classes with any type of values 
29   * (including primitive types). This class builds on the basic structure 
30   * provided by <code>GrowableBase</code>, specializing it for usage as a
31   * stack. See the base class description for details of the implementation.<p>
32   *
33   * Stacks based on this class are unsynchronized in order to provide the
34   * best possible performance for typical usage scenarios, so explicit
35   * synchronization must be implemented by the subclass or the application in
36   * cases where they are to be modified in a multithreaded environment.<p>
37   *
38   * Subclasses need to implement the abstract methods defined by the base class
39   * for working with the data array, as well as the actual data access methods
40   * (at least the basic <code>push()</code>, <code>pop()</code>, and
41   * <code>peek()</code> methods).
42   * 
43   * @author Dennis M. Sosnoski
44   * @version 1.0
45   */
46  
47  public abstract class StackBase extends GrowableBase
48  {
49      /** The number of values currently present in the stack. */
50      protected int m_countPresent;
51  
52      /**
53       * Constructor with full specification.
54       * 
55       * @param size number of elements initially allowed in stack
56       * @param growth maximum size increment for growing stack
57       * @param type stack element type
58       */
59      
60      public StackBase(int size, int growth, Class   type) {
61          super(size, growth, type);
62      }
63  
64      /**
65       * Constructor with partial specification.
66       * 
67       * @param size number of elements initially allowed in stack
68       * @param type stack element type
69       */
70      
71      public StackBase(int size, Class   type) {
72          this(size, Integer.MAX_VALUE, type);
73      }
74  
75      /**
76       * Copy (clone) constructor.
77       * 
78       * @param base instance being copied
79       */
80      
81      public StackBase(StackBase base) {
82          super(base);
83          System.arraycopy(base.getArray(), 0, getArray(), 0, 
84              base.m_countPresent);
85          m_countPresent = base.m_countPresent;
86      }
87  
88      /**
89       * Gets the array offset for appending a value to those in the stack.
90       * If the underlying array is full, it is grown by the appropriate size
91       * increment so that the index value returned is always valid for the 
92       * array in use by the time of the return.
93       * 
94       * @return index position for added element
95       */
96      
97      protected int getAddIndex() {
98          int index = m_countPresent++;
99          if (m_countPresent > m_countLimit) {
100             growArray(m_countPresent);
101         }
102         return index;
103     }
104 
105     /**
106      * Get the number of values currently present in the stack.
107      * 
108      * @return count of values present
109      */
110     
111     public int size() {
112         return m_countPresent;
113     }
114 
115     /**
116      * Check if stack is empty.
117      * 
118      * @return <code>true</code> if stack empty, <code>false</code> if not
119      */
120     
121     public boolean isEmpty() {
122         return m_countPresent == 0;
123     }
124 
125     /**
126      * Set the stack to the empty state.
127      */
128     
129     public void clear() {
130         discardValues(0, m_countPresent);
131         m_countPresent = 0;
132     }
133 
134     /**
135      * Constructs and returns a simple array containing the same data as held 
136      * in this stack. Note that the items will be in reverse pop order, with 
137      * the last item to be popped from the stack as the first item in the 
138      * array.
139      * 
140      * @param type element type for constructed array
141      * @return array containing a copy of the data
142      */
143     
144     protected Object   buildArray(Class   type) {
145         return super.buildArray(type, 0, m_countPresent);
146     }
147 }
148
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags