01: package it.unimi.dsi.fastutil;
02:
03: /*
04: * fastutil: Fast & compact type-specific collections for Java
05: *
06: * Copyright (C) 2002-2008 Sebastiano Vigna
07: *
08: * This library is free software; you can redistribute it and/or
09: * 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: }
|