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    }