View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.collections.primitives;
18  
19  import java.util.EmptyStackException;
20  
21  import org.apache.commons.collections.primitives.ArrayIntList;
22  
23  /**
24   * A primitive int based Stack.
25   *
26   * @author Apache Directory Project
27   * @since Commons Primitives 1.1
28   * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
29   */
30  public class IntStack
31  {
32      /** the underlying dynamic primitive backing store */
33      private ArrayIntList list = new ArrayIntList() ;
34      
35      
36      public IntStack()
37      {
38      }
39      
40      
41      public IntStack( int[] numbas )
42      {
43          for ( int ii = 0; ii < numbas.length; ii++ )
44          {    
45              list.add( numbas[ii] ) ;
46          }
47      }
48      
49  
50      /**
51       * Tests if this stack is empty.
52       * 
53       * @return true if and only if this stack contains no ints; false otherwise
54       */
55      public boolean empty()
56      {
57          return list.isEmpty() ;
58      }
59  
60      
61      /**
62       * Looks at the int at the top of this stack without removing it from 
63       * the stack.
64       * 
65       * @return int at the top of this stack (last int in ArrayIntList)
66       * @throws EmptyStackException if this stack is empty
67       */
68      public int peek()
69      {
70          if ( list.isEmpty() )
71          {
72              throw new EmptyStackException() ;
73          }
74          
75          return list.get( list.size() - 1 ) ;
76      }
77  
78      
79      /**
80       * Return the n'th int down the stack, where 0 is the top element and
81       * [size()-1] is the bottom element.
82       *
83       * @param n the element index
84       * @return the element at the index
85       * @throws EmptyStackException if the stack is empty
86       * @throws IndexOutOfBoundsException if the index is out of bounds
87       */
88      public int peek( int n )
89      {
90          if ( list.isEmpty() )
91          {
92              throw new EmptyStackException() ;
93          }
94  
95          return list.get( list.size() - n - 1 ) ;
96      }
97  
98  
99      /**
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 }