KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > primitives > ByteStack


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 JavaDoc;
20
21 import org.apache.commons.collections.primitives.ArrayByteList;
22
23 /**
24  * A primitive byte based Stack. The underlying backing store is an
25  * ArrayByteList 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 00:14:21 -0800 (Wed, 29 Nov 2006) $
31  */
32 public class ByteStack
33 {
34     /** the underlying dynamic primitive backing store */
35     private ArrayByteList list = new ArrayByteList() ;
36
37
38     /**
39      * Creates an empty primitive stack.
40      */
41     public ByteStack()
42     {
43     }
44
45
46     /**
47      * Creates a stack prepopulating it with values.
48      *
49      * @param numbas the array to add
50      */
51     public ByteStack( byte[] numbas )
52     {
53         for ( int ii = 0; ii < numbas.length; ii++ )
54         {
55             list.add( numbas[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 byte peek()
78     {
79         if ( list.isEmpty() )
80         {
81             throw new EmptyStackException JavaDoc() ;
82         }
83         
84         return list.get( list.size() - 1 ) ;
85     }
86
87     
88     /**
89      * Return the n'th byte 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 byte peek( int n )
98     {
99         if ( list.isEmpty() )
100         {
101             throw new EmptyStackException JavaDoc() ;
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 byte pop()
115     {
116         if ( list.isEmpty() )
117         {
118             throw new EmptyStackException JavaDoc() ;
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 byte push( byte 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( byte 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 byte 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 }
196
Popular Tags