Java源码学习1—Stack

源码版本JDK1.8

---

I.类文件注释

/**
* The Stack class represents a last-in-first-out(LIFO) stack of objects. 
* It extends class Vector with five operations that allow a vector to be 
* treated as a stack. The usual push and pop operations are provided, as
* well as a method to peek at the top item on the stack, a method to test
* for whether the stack is empty, and a method to search the stack for
*  an item and discover how far it is from the top.

  栈类体现了一个对象后进先出的栈。它继承自Vector类，并实现了5个栈的方法。它提供了基本的push和pop操作。一个查看栈顶元素的方法、一个查看栈是否为空的方法和一个查找元素并确定它和栈顶距离的方法。

* When a stack is first created, it contains no items.

 当一个栈被新建时，它是空的。

 * A more complete and consistent set of LIFO stack operations is
 * provided by the Deque interface and its implementations, which
 * should be used in preference to this class.  For example:
 * Deque<Integer> stack = new ArrayDeque<Integer>();

 Deque接口和它的实现类提供了一个更完整并且一致的集合栈操作，我们更偏向于用下面这个实现类：

Deque<Integer> stack = new ArrayDeque<Integer>();

II.源码解读

• Stack定义

class Stack<E> extends Vector<E>  // 继承自Vector

• 域

/** use serialVersionUID from JDK 1.0.2 for interoperability */
    private static final long serialVersionUID = 1224463164541339165L;

• 方法

 /**
     * Creates an empty Stack.
     */
    public Stack() { // 构造方法
    }

/**
    * Pushes an item onto the top of this stack. This has exactly
    * the same effect as:
    * addElement(item)
    *
    * @param   item   the item to be pushed onto this stack.
    * @return  the item argument.
    * @see     java.util.Vector#addElement
    */
   public E push(E item) {
       addElement(item);

       return item;
   }

 push()方法，往栈顶添加一个元素，其作用和addElement()是一样的。参数是往栈顶添加的元素，返回值也是改元素。
 可参考java.util.Vector类的addElement方法。

/**
     * Removes the object at the top of this stack and returns that
     * object as the value of this function.
     *
     * @return  The object at the top of this stack (the last item
     *          of the Vector object).
     * @throws  EmptyStackException if this stack is empty.
     */
    public synchronized E pop() {
        E       obj;
        int     len = size();

        obj = peek();
        removeElementAt(len - 1);

        return obj;
    }

 pop()方法，移除栈顶的元素，并返回该元素的值。如果该栈为空会抛出异常。
 由方法体可知，该方法先通过peek()方法获取到栈顶与元素，然后移除该元素，然后返回该元素。

/**
    * Looks at the object at the top of this stack without removing it
    * from the stack.
    *
    * @return  the object at the top of this stack (the last item
    *          of the Vector object).
    * @throws  EmptyStackException  if this stack is empty.
    */
   public synchronized E peek() {
       int     len = size();

       if (len == 0)
           throw new EmptyStackException();
       return elementAt(len - 1);
   }

 查看栈顶的元素但不移除。该方法也会抛出空栈异常。

 /**
     * Tests if this stack is empty.
     *
     * @return  true if and only if this stack contains no items; false otherwise.
     */
    public boolean empty() {
        return size() == 0;
    }

 栈为空返回true，否则返回false。

/**
     * Returns the 1-based position where an object is on this stack.
     * If the object o occurs as an item in this stack, this
     * method returns the distance from the top of the stack of the
     * occurrence nearest the top of the stack; the topmost item on the
     * stack is considered to be at distance 1. The equals
     * method is used to compare o to the
     * items in this stack.
     *
     * @param   o   the desired object.
     * @return  the 1-based position from the top of the stack where
     *          the object is located; the return value -1
     *          indicates that the object is not on the stack.
     */
    public synchronized int search(Object o) {
        int i = lastIndexOf(o);

        if (i >= 0) {
            return size() - i;
        }
        return -1;
    }

 该方法返回元素基于1（栈顶元素离栈顶距离为1）的距离。如果一个元素在栈内，那么该方法返回该元素到栈顶的距离。栈顶的元素被认为其距栈顶的距离为1.如果返回-1则表明该元素不在栈中。