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.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 09:14:21 +0100 (Wed, 29 Nov 2006) $
031 */
032 public 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 }