KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sosnoski > util > stack > IntStack


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 /**
26  * Growable <code>int</code> stack with type specific access methods. This
27  * implementation is unsynchronized in order to provide the best possible
28  * performance for typical usage scenarios, so explicit synchronization must
29  * be implemented by a wrapper class or directly by the application in cases
30  * where instances are modified in a multithreaded environment. See the base
31  * classes for other details of the implementation.
32  *
33  * @author Dennis M. Sosnoski
34  * @version 1.0
35  */
36
37 public class IntStack extends StackBase
38 {
39     /** The underlying array used for storing the data. */
40     protected int[] m_baseArray;
41
42     /**
43      * Constructor with full specification.
44      *
45      * @param size number of <code>int</code> values initially allowed in
46      * stack
47      * @param growth maximum size increment for growing stack
48      */
49
50     public IntStack(int size, int growth) {
51         super(size, growth, int.class);
52     }
53
54     /**
55      * Constructor with initial size specified.
56      *
57      * @param size number of <code>int</code> values initially allowed in
58      * stack
59      */
60
61     public IntStack(int size) {
62         super(size, int.class);
63     }
64
65     /**
66      * Default constructor.
67      */
68
69     public IntStack() {
70         this(DEFAULT_SIZE);
71     }
72
73     /**
74      * Copy (clone) constructor.
75      *
76      * @param base instance being copied
77      */
78
79     public IntStack(IntStack base) {
80         super(base);
81     }
82
83     /**
84      * Get the backing array. This method is used by the type-agnostic base
85      * class code to access the array used for type-specific storage.
86      *
87      * @return backing array object
88      */
89
90     protected Object JavaDoc getArray() {
91         return m_baseArray;
92     }
93
94     /**
95      * Set the backing array. This method is used by the type-agnostic base
96      * class code to set the array used for type-specific storage.
97      *
98      * @param backing array object
99      */
100
101     protected void setArray(Object JavaDoc array) {
102         m_baseArray = (int[]) array;
103     }
104
105     /**
106      * Push a value on the stack.
107      *
108      * @param value value to be added
109      */
110
111     public void push(int value) {
112         int index = getAddIndex();
113         m_baseArray[index] = value;
114     }
115
116     /**
117      * Pop a value from the stack.
118      *
119      * @return value from top of stack
120      * @exception ArrayIndexOutOfBoundsException on attempt to pop empty stack
121      */
122
123     public int pop() {
124         if (m_countPresent > 0) {
125             return m_baseArray[--m_countPresent];
126         } else {
127             throw new ArrayIndexOutOfBoundsException JavaDoc
128                 ("Attempt to pop empty stack");
129         }
130     }
131
132     /**
133      * Pop multiple values from the stack. The last value popped is the
134      * one returned.
135      *
136      * @param count number of values to pop from stack (must be strictly
137      * positive)
138      * @return value from top of stack
139      * @exception ArrayIndexOutOfBoundsException on attempt to pop past end of
140      * stack
141      */
142
143     public int pop(int count) {
144         if (count <= 0) {
145             throw new IllegalArgumentException JavaDoc("Count must be greater than 0");
146         } else if (m_countPresent >= count) {
147             m_countPresent -= count;
148             return m_baseArray[m_countPresent];
149         } else {
150             throw new ArrayIndexOutOfBoundsException JavaDoc
151                 ("Attempt to pop past end of stack");
152         }
153     }
154
155     /**
156      * Copy a value from the stack. This returns a value from within
157      * the stack without modifying the stack.
158      *
159      * @param depth depth of value to be returned
160      * @return value from stack
161      * @exception ArrayIndexOutOfBoundsException on attempt to peek past end of
162      * stack
163      */
164
165     public int peek(int depth) {
166         if (m_countPresent > depth) {
167             return m_baseArray[m_countPresent - depth - 1];
168         } else {
169             throw new ArrayIndexOutOfBoundsException JavaDoc
170                 ("Attempt to peek past end of stack");
171         }
172     }
173
174     /**
175      * Copy top value from the stack. This returns the top value without
176      * removing it from the stack.
177      *
178      * @return value at top of stack
179      * @exception ArrayIndexOutOfBoundsException on attempt to peek empty stack
180      */
181
182     public int peek() {
183         return peek(0);
184     }
185
186     /**
187      * Constructs and returns a simple array containing the same data as held
188      * in this stack. Note that the items will be in reverse pop order, with
189      * the last item to be popped from the stack as the first item in the
190      * array.
191      *
192      * @return array containing a copy of the data
193      */
194
195     public int[] toArray() {
196         return (int[]) buildArray(int.class);
197     }
198
199     /**
200      * Duplicates the object with the generic call.
201      *
202      * @return a copy of the object
203      */
204
205     public Object JavaDoc clone() {
206         return new IntStack(this);
207     }
208 }
209
Popular Tags