1. /*
  2. * @(#)Stack.java 1.26 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.util;
  8. /**
  9. * The <code>Stack</code> class represents a last-in-first-out
  10. * (LIFO) stack of objects. It extends class <tt>Vector</tt> with five
  11. * operations that allow a vector to be treated as a stack. The usual
  12. * <tt>push</tt> and <tt>pop</tt> operations are provided, as well as a
  13. * method to <tt>peek</tt> at the top item on the stack, a method to test
  14. * for whether the stack is <tt>empty</tt>, and a method to <tt>search</tt>
  15. * the stack for an item and discover how far it is from the top.
  16. * <p>
  17. * When a stack is first created, it contains no items.
  18. *
  19. * @author Jonathan Payne
  20. * @version 1.26, 01/23/03
  21. * @since JDK1.0
  22. */
  23. public
  24. class Stack extends Vector {
  25. /**
  26. * Creates an empty Stack.
  27. */
  28. public Stack() {
  29. }
  30. /**
  31. * Pushes an item onto the top of this stack. This has exactly
  32. * the same effect as:
  33. * <blockquote><pre>
  34. * addElement(item)</pre></blockquote>
  35. *
  36. * @param item the item to be pushed onto this stack.
  37. * @return the <code>item</code> argument.
  38. * @see java.util.Vector#addElement
  39. */
  40. public Object push(Object item) {
  41. addElement(item);
  42. return item;
  43. }
  44. /**
  45. * Removes the object at the top of this stack and returns that
  46. * object as the value of this function.
  47. *
  48. * @return The object at the top of this stack (the last item
  49. * of the <tt>Vector</tt> object).
  50. * @exception EmptyStackException if this stack is empty.
  51. */
  52. public synchronized Object pop() {
  53. Object obj;
  54. int len = size();
  55. obj = peek();
  56. removeElementAt(len - 1);
  57. return obj;
  58. }
  59. /**
  60. * Looks at the object at the top of this stack without removing it
  61. * from the stack.
  62. *
  63. * @return the object at the top of this stack (the last item
  64. * of the <tt>Vector</tt> object).
  65. * @exception EmptyStackException if this stack is empty.
  66. */
  67. public synchronized Object peek() {
  68. int len = size();
  69. if (len == 0)
  70. throw new EmptyStackException();
  71. return elementAt(len - 1);
  72. }
  73. /**
  74. * Tests if this stack is empty.
  75. *
  76. * @return <code>true</code> if and only if this stack contains
  77. * no items; <code>false</code> otherwise.
  78. */
  79. public boolean empty() {
  80. return size() == 0;
  81. }
  82. /**
  83. * Returns the 1-based position where an object is on this stack.
  84. * If the object <tt>o</tt> occurs as an item in this stack, this
  85. * method returns the distance from the top of the stack of the
  86. * occurrence nearest the top of the stack; the topmost item on the
  87. * stack is considered to be at distance <tt>1</tt>. The <tt>equals</tt>
  88. * method is used to compare <tt>o</tt> to the
  89. * items in this stack.
  90. *
  91. * @param o the desired object.
  92. * @return the 1-based position from the top of the stack where
  93. * the object is located; the return value <code>-1</code>
  94. * indicates that the object is not on the stack.
  95. */
  96. public synchronized int search(Object o) {
  97. int i = lastIndexOf(o);
  98. if (i >= 0) {
  99. return size() - i;
  100. }
  101. return -1;
  102. }
  103. /** use serialVersionUID from JDK 1.0.2 for interoperability */
  104. private static final long serialVersionUID = 1224463164541339165L;
  105. }