001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.collections.primitives;
018
019 import java.util.EmptyStackException;
020
021 import org.apache.commons.collections.primitives.ArrayIntList;
022
023 /**
024 * A primitive int based Stack.
025 *
026 * @author Apache Directory Project
027 * @since Commons Primitives 1.1
028 * @version $Revision: 480460 $ $Date: 2006-11-29 09:14:21 +0100 (Wed, 29 Nov 2006) $
029 */
030 public class IntStack
031 {
032 /** the underlying dynamic primitive backing store */
033 private ArrayIntList list = new ArrayIntList() ;
034
035
036 public IntStack()
037 {
038 }
039
040
041 public IntStack( int[] numbas )
042 {
043 for ( int ii = 0; ii < numbas.length; ii++ )
044 {
045 list.add( numbas[ii] ) ;
046 }
047 }
048
049
050 /**
051 * Tests if this stack is empty.
052 *
053 * @return true if and only if this stack contains no ints; false otherwise
054 */
055 public boolean empty()
056 {
057 return list.isEmpty() ;
058 }
059
060
061 /**
062 * Looks at the int at the top of this stack without removing it from
063 * the stack.
064 *
065 * @return int at the top of this stack (last int in ArrayIntList)
066 * @throws EmptyStackException if this stack is empty
067 */
068 public int peek()
069 {
070 if ( list.isEmpty() )
071 {
072 throw new EmptyStackException() ;
073 }
074
075 return list.get( list.size() - 1 ) ;
076 }
077
078
079 /**
080 * Return the n'th int down the stack, where 0 is the top element and
081 * [size()-1] is the bottom element.
082 *
083 * @param n the element index
084 * @return the element at the index
085 * @throws EmptyStackException if the stack is empty
086 * @throws IndexOutOfBoundsException if the index is out of bounds
087 */
088 public int peek( int n )
089 {
090 if ( list.isEmpty() )
091 {
092 throw new EmptyStackException() ;
093 }
094
095 return list.get( list.size() - n - 1 ) ;
096 }
097
098
099 /**
100 * Removes the int at the top of this stack and returns that object as the
101 * value of this function.
102 *
103 * @return int at the top of this stack (last int in ArrayIntList)
104 * @throws EmptyStackException if this stack is empty
105 */
106 public int pop()
107 {
108 if ( list.isEmpty() )
109 {
110 throw new EmptyStackException() ;
111 }
112
113 return list.removeElementAt( list.size() - 1 ) ;
114 }
115
116
117 /**
118 * Pushes an int item onto the top of this stack.
119 *
120 * @param item the int item to push onto this stack
121 * @return the item argument for call chaining
122 */
123 public int push( int item )
124 {
125 list.add( item ) ;
126 return item ;
127 }
128
129
130 /**
131 * Returns the 1-based position where an int is on this stack. If the int
132 * occurs as an item in this stack, this method returns the distance from
133 * the top of the stack of the occurrence nearest the top of the stack; the
134 * topmost item on the stack is considered to be at distance 1.
135 *
136 * @param item the int to search for from the top down
137 * @return the 1-based position from the top of the stack where the int is
138 * located; the return value -1 indicates that the int is not on the stack
139 */
140 public int search( int item )
141 {
142 for ( int ii = list.size() - 1; ii >= 0; ii-- )
143 {
144 if ( list.get( ii ) == item )
145 {
146 return list.size() - ii ;
147 }
148 }
149
150
151 return -1 ;
152 }
153
154
155 /**
156 * Gets items from the stack where the index is zero based and the top of
157 * the stack is at an index of size()-1 with the bottom of the stack at an
158 * index of 0.
159 *
160 * @param index the index into the stack treated as a list
161 * @return the int value at the index
162 */
163 public int get( int index )
164 {
165 return list.get( index ) ;
166 }
167
168
169 /**
170 * Gets the size of this stack.
171 *
172 * @return the size of this stack
173 */
174 public int size()
175 {
176 return list.size() ;
177 }
178
179
180 /**
181 * Empties the contents of the stack.
182 */
183 public void clear()
184 {
185 list.clear() ;
186 }
187 }