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.ArrayBooleanList;
022
023/**
024 * A primitive boolean based Stack.  The underlying backing store is an
025 * ArrayBooleanList where the front of the list is the bottom of the stack
026 * and the tail of the list is the top of the stack.
027 *
028 * @author Apache Directory Project
029 * @since Commons Primitives 1.1
030 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
031 */
032public class BooleanStack
033{
034    /** the underlying dynamic primitive backing store */
035    private ArrayBooleanList list = new ArrayBooleanList() ;
036
037
038    /**
039     * Creates an empty primitive stack.
040     */
041    public BooleanStack()
042    {
043    }
044
045
046    /**
047     * Creates a stack prepopulating it with values.
048     *
049     * @param bits the array to add
050     */
051    public BooleanStack( boolean[] bits )
052    {
053        for ( int ii = 0; ii < bits.length; ii++ )
054        {    
055            list.add( bits[ii] ) ;
056        }
057    }
058    
059
060    /**
061     * Tests if this stack is empty.
062     * 
063     * @return true if and only if this stack is empty; false otherwise
064     */
065    public boolean empty()
066    {
067        return list.isEmpty() ;
068    }
069
070    
071    /**
072     * Looks at the top of this stack without removing it.
073     * 
074     * @return the value at the top of this stack
075     * @throws java.util.EmptyStackException if this stack is empty
076     */
077    public boolean peek()
078    {
079        if ( list.isEmpty() )
080        {
081            throw new EmptyStackException() ;
082        }
083        
084        return list.get( list.size() - 1 ) ;
085    }
086
087    
088    /**
089     * Return the n'th boolean down the stack, where 0 is the top element and
090     * [size()-1] is the bottom element.
091     *
092     * @param n the element index
093     * @return the element at the index
094     * @throws EmptyStackException if the stack is empty
095     * @throws IndexOutOfBoundsException if the index is out of bounds
096     */
097    public boolean peek( int n )
098    {
099        if ( list.isEmpty() )
100        {
101            throw new EmptyStackException() ;
102        }
103
104        return list.get( list.size() - n - 1 ) ;
105    }
106
107
108    /**
109     * Removes the value at the top of this stack and returns it.
110     * 
111     * @return value at the top of this stack
112     * @throws java.util.EmptyStackException if this stack is empty
113     */
114    public boolean pop()
115    {
116        if ( list.isEmpty() )
117        {
118            throw new EmptyStackException() ;
119        }
120        
121        return list.removeElementAt( list.size() - 1 ) ;
122    }
123
124    
125    /**
126     * Pushes a value onto the top of this stack.
127     * 
128     * @param item the value to push onto this stack
129     * @return the item argument for call chaining
130     */
131    public boolean push( boolean item )
132    {
133        list.add( item ) ;
134        return item ;
135    }
136    
137
138    /**
139     * Returns the 1-based position where a value is on this stack. If the value
140     * occurs as an item in this stack, this method returns the distance from 
141     * the top of the stack of the occurrence nearest the top of the stack; the 
142     * topmost item on the stack is considered to be at distance 1. 
143     * 
144     * @param item the value to search for from the top down
145     * @return the 1-based position from the top of the stack where the int is 
146     *  located; the return value -1 indicates that the int is not on the stack
147     */
148    public int search( boolean item )
149    {
150        for ( int ii = list.size() - 1; ii >= 0; ii-- )
151        {
152            if ( list.get( ii ) == item )
153            {
154                return list.size() - ii ;
155            }
156        }
157        
158        
159        return -1 ;
160    }
161    
162    
163    /**
164     * Gets items from the stack where the index is zero based and the top of
165     * the stack is at an index of size()-1 with the bottom of the stack at an
166     * index of 0.
167     * 
168     * @param index the index into the stack treated as a list
169     * @return the value at the index
170     */
171    public boolean get( int index )
172    {
173        return list.get( index ) ;
174    }
175    
176    
177    /**
178     * Gets the size of this stack.
179     * 
180     * @return the size of this stack
181     */
182    public int size()
183    {
184        return list.size() ;
185    }
186    
187
188    /**
189     * Empties the contents of the stack.
190     */
191    public void clear()
192    {
193        list.clear() ;
194    }
195}