/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.collections.primitives;

import java.util.EmptyStackException;

import org.apache.commons.collections.primitives.ArrayIntList;

/**
 * A primitive int based Stack.
 *
 * @author Apache Directory Project
 * @since Commons Primitives 1.1
 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
 */
public class IntStack
{
    /** the underlying dynamic primitive backing store */
    private ArrayIntList list = new ArrayIntList() ;
    
    
    public IntStack()
    {
    }
    
    
    public IntStack( int[] numbas )
    {
        for ( int ii = 0; ii < numbas.length; ii++ )
        {    
            list.add( numbas[ii] ) ;
        }
    }
    

    /**
     * Tests if this stack is empty.
     * 
     * @return true if and only if this stack contains no ints; false otherwise
     */
    public boolean empty()
    {
        return list.isEmpty() ;
    }

    
    /**
     * Looks at the int at the top of this stack without removing it from 
     * the stack.
     * 
     * @return int at the top of this stack (last int in ArrayIntList)
     * @throws EmptyStackException if this stack is empty
     */
    public int peek()
    {
        if ( list.isEmpty() )
        {
            throw new EmptyStackException() ;
        }
        
        return list.get( list.size() - 1 ) ;
    }

    
    /**
     * Return the n'th int down the stack, where 0 is the top element and
     * [size()-1] is the bottom element.
     *
     * @param n the element index
     * @return the element at the index
     * @throws EmptyStackException if the stack is empty
     * @throws IndexOutOfBoundsException if the index is out of bounds
     */
    public int peek( int n )
    {
        if ( list.isEmpty() )
        {
            throw new EmptyStackException() ;
        }

        return list.get( list.size() - n - 1 ) ;
    }


    /**
     * Removes the int at the top of this stack and returns that object as the 
     * value of this function.
     * 
     * @return int at the top of this stack (last int in ArrayIntList)
     * @throws EmptyStackException if this stack is empty
     */
    public int pop()
    {
        if ( list.isEmpty() )
        {
            throw new EmptyStackException() ;
        }
        
        return list.removeElementAt( list.size() - 1 ) ;
    }

    
    /**
     * Pushes an int item onto the top of this stack.
     * 
     * @param item the int item to push onto this stack
     * @return the item argument for call chaining
     */
    public int push( int item )
    {
        list.add( item ) ;
        return item ;
    }
    

    /**
     * Returns the 1-based position where an int is on this stack. If the int 
     * occurs as an item in this stack, this method returns the distance from 
     * the top of the stack of the occurrence nearest the top of the stack; the 
     * topmost item on the stack is considered to be at distance 1. 
     * 
     * @param item the int to search for from the top down
     * @return the 1-based position from the top of the stack where the int is 
     *  located; the return value -1 indicates that the int is not on the stack
     */
    public int search( int item )
    {
        for ( int ii = list.size() - 1; ii >= 0; ii-- )
        {
            if ( list.get( ii ) == item )
            {
                return list.size() - ii ;
            }
        }
        
        
        return -1 ;
    }
    
    
    /**
     * Gets items from the stack where the index is zero based and the top of
     * the stack is at an index of size()-1 with the bottom of the stack at an
     * index of 0.
     * 
     * @param index the index into the stack treated as a list
     * @return the int value at the index
     */
    public int get( int index )
    {
        return list.get( index ) ;
    }
    
    
    /**
     * Gets the size of this stack.
     * 
     * @return the size of this stack
     */
    public int size()
    {
        return list.size() ;
    }
    

    /**
     * Empties the contents of the stack.
     */
    public void clear()
    {
        list.clear() ;
    }
}