View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.collections.primitives;
18  
19  import java.util.EmptyStackException;
20  
21  import org.apache.commons.collections.primitives.ArrayBooleanList;
22  
23  /**
24   * A primitive boolean based Stack.  The underlying backing store is an
25   * ArrayBooleanList where the front of the list is the bottom of the stack
26   * and the tail of the list is the top of the stack.
27   *
28   * @author Apache Directory Project
29   * @since Commons Primitives 1.1
30   * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
31   */
32  public class BooleanStack
33  {
34      /** the underlying dynamic primitive backing store */
35      private ArrayBooleanList list = new ArrayBooleanList() ;
36  
37  
38      /**
39       * Creates an empty primitive stack.
40       */
41      public BooleanStack()
42      {
43      }
44  
45  
46      /**
47       * Creates a stack prepopulating it with values.
48       *
49       * @param bits the array to add
50       */
51      public BooleanStack( boolean[] bits )
52      {
53          for ( int ii = 0; ii < bits.length; ii++ )
54          {    
55              list.add( bits[ii] ) ;
56          }
57      }
58      
59  
60      /**
61       * Tests if this stack is empty.
62       * 
63       * @return true if and only if this stack is empty; false otherwise
64       */
65      public boolean empty()
66      {
67          return list.isEmpty() ;
68      }
69  
70      
71      /**
72       * Looks at the top of this stack without removing it.
73       * 
74       * @return the value at the top of this stack
75       * @throws java.util.EmptyStackException if this stack is empty
76       */
77      public boolean peek()
78      {
79          if ( list.isEmpty() )
80          {
81              throw new EmptyStackException() ;
82          }
83          
84          return list.get( list.size() - 1 ) ;
85      }
86  
87      
88      /**
89       * Return the n'th boolean down the stack, where 0 is the top element and
90       * [size()-1] is the bottom element.
91       *
92       * @param n the element index
93       * @return the element at the index
94       * @throws EmptyStackException if the stack is empty
95       * @throws IndexOutOfBoundsException if the index is out of bounds
96       */
97      public boolean peek( int n )
98      {
99          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 }