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 */
017package org.apache.commons.collections.primitives;
018
019import java.util.EmptyStackException;
020
021import 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 03:14:21 -0500 (Wed, 29 Nov 2006) $
029 */
030public 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}