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.ArrayDoubleList;
022    
023    /**
024     * A primitive double based Stack.  The underlying backing store is an
025     * ArrayDoubleList 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 DoubleStack
033    {
034        /** the underlying dynamic primitive backing store */
035        private ArrayDoubleList list = new ArrayDoubleList() ;
036    
037    
038        /**
039         * Creates an empty primitive stack.
040         */
041        public DoubleStack()
042        {
043        }
044    
045    
046        /**
047         * Creates a stack prepopulating it with values.
048         *
049         * @param numbas the array to add
050         */
051        public DoubleStack( double[] numbas )
052        {
053            for ( int ii = 0; ii < numbas.length; ii++ )
054            {    
055                list.add( numbas[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 double 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 double 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 double 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 double 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 double push( double 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( double 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 double 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    }