1 package it.unimi.dsi.fastutil; 2 3 /* 4 * fastutil: Fast & compact type-specific collections for Java 5 * 6 * Copyright (C) 2002, 2003, 2004, 2005, 2006 Sebastiano Vigna 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library; if not, write to the Free Software 20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 21 * 22 */ 23 24 import java.util.NoSuchElementException; 25 26 /** A stack. 27 * 28 * <P>A stack must provide the classical {@link #push(Object)} and 29 * {@link #pop()} operations, but may be also <em>peekable</em> 30 * to some extent: it may provide just the {@link #top()} function, 31 * or even a more powerful {@link #peek(int)} method that provides 32 * access to all elements on the stack (indexed from the top, which 33 * has index 0). 34 */ 35 36 public interface Stack<K> { 37 38 /** Pushes the given object on the stack. 39 * 40 * @param o the object that will become the new top of the stack. 41 */ 42 43 void push( K o ); 44 45 /** Pops the top off the stack. 46 * 47 * @return the top of the stack. 48 * @throws NoSuchElementException if the stack is empty. 49 */ 50 51 K pop(); 52 53 /** Checks whether the stack is empty. 54 * 55 * @return true if the stack is empty. 56 */ 57 58 boolean isEmpty(); 59 60 /** Peeks at the top of the stack (optional operation). 61 * 62 * @return the top of the stack. 63 * @throws NoSuchElementException if the stack is empty. 64 */ 65 66 K top(); 67 68 /** Peeks at an element on the stack (optional operation). 69 * 70 * @return the <code>i</code>-th element on the stack; 0 represents the top. 71 * @throws IndexOutOfBoundsException if the designated element does not exist.. 72 */ 73 74 K peek( int i ); 75 76 } 77