/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.tomcat.util.digester;

import java.io.Serial;
import java.util.ArrayList;
import java.util.EmptyStackException;

/**
 * <p>
 * Imported copy of the <code>ArrayStack</code> class from Commons Collections, which was the only direct dependency
 * from Digester.
 * </p>
 * <p>
 * <strong>WARNING</strong> - This class is public solely to allow it to be used from subpackages of
 * <code>org.apache.commons.digester</code>. It should not be considered part of the public API of Commons Digester. If
 * you want to use such a class yourself, you should use the one from Commons Collections directly.
 * </p>
 * <p>
 * An implementation of the {@link java.util.Stack} API that is based on an <code>ArrayList</code> instead of a
 * <code>Vector</code>, so it is not synchronized to protect against multi-threaded access. The implementation is
 * therefore operates faster in environments where you do not need to worry about multiple thread contention.
 * </p>
 * <p>
 * Unlike <code>Stack</code>, <code>ArrayStack</code> accepts null entries.
 * </p>
 *
 * @param <E> Type of object in this stack
 *
 * @see java.util.Stack
 *
 * @since Digester 1.6 (from Commons Collections 1.0)
 */
public class ArrayStack<E> extends ArrayList<E> {

    /** Ensure serialization compatibility */
    @Serial
    private static final long serialVersionUID = 2130079159931574599L;

    /**
     * Constructs a new empty <code>ArrayStack</code>. The initial size is controlled by <code>ArrayList</code> and is
     * currently 10.
     */
    public ArrayStack() {
        super();
    }

    /**
     * Constructs a new empty <code>ArrayStack</code> with an initial size.
     *
     * @param initialSize the initial size to use
     *
     * @throws IllegalArgumentException if the specified initial size is negative
     */
    public ArrayStack(int initialSize) {
        super(initialSize);
    }

    /**
     * Return <code>true</code> if this stack is currently empty.
     * <p>
     * This method exists for compatibility with <code>java.util.Stack</code>. New users of this class should use
     * <code>isEmpty</code> instead.
     *
     * @return true if the stack is currently empty
     */
    public boolean empty() {
        return isEmpty();
    }

    /**
     * Returns the top item off of this stack without removing it.
     *
     * @return the top item on the stack
     *
     * @throws EmptyStackException if the stack is empty
     */
    public E peek() throws EmptyStackException {
        int n = size();
        if (n == 0) {
            throw new EmptyStackException();
        } else {
            return get(n - 1);
        }
    }

    /**
     * Returns the n'th item down (zero-relative) from the top of this stack without removing it.
     *
     * @param n the number of items down to go
     *
     * @return the n'th item on the stack, zero relative
     *
     * @throws EmptyStackException if there are not enough items on the stack to satisfy this request
     */
    public E peek(int n) throws EmptyStackException {
        int m = (size() - n) - 1;
        if (m < 0) {
            throw new EmptyStackException();
        } else {
            return get(m);
        }
    }

    /**
     * Pops the top item off of this stack and return it.
     *
     * @return the top item on the stack
     *
     * @throws EmptyStackException if the stack is empty
     */
    public E pop() throws EmptyStackException {
        int n = size();
        if (n == 0) {
            throw new EmptyStackException();
        } else {
            return remove(n - 1);
        }
    }

    /**
     * Pushes a new item onto the top of this stack. The pushed item is also returned. This is equivalent to calling
     * <code>add</code>.
     *
     * @param item the item to be added
     *
     * @return the item just pushed
     */
    public E push(E item) {
        add(item);
        return item;
    }
}