1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections4;
18
19 import java.util.ArrayDeque;
20 import java.util.ArrayList;
21 import java.util.EmptyStackException;
22 import java.util.Stack;
23
24 /**
25 * An implementation of the {@link Stack} API that is based on an
26 * {@code ArrayList} instead of a {@code Vector}, so it is not
27 * synchronized to protect against multithreaded access. The implementation
28 * is therefore operates faster in environments where you do not need to
29 * worry about multiple thread contention.
30 * <p>
31 * The removal order of an {@code ArrayStack} is based on insertion
32 * order: The most recently added element is removed first. The iteration
33 * order is <em>not</em> the same as the removal order. The iterator returns
34 * elements from the bottom up.
35 * </p>
36 * <p>
37 * Unlike {@code Stack}, {@code ArrayStack} accepts null entries.
38 * <p>
39 * <strong>Note:</strong> From version 4.0 onwards, this class does not implement the
40 * removed {@code Buffer} interface anymore.
41 * </p>
42 *
43 * @param <E> The type of elements in this list
44 * @see java.util.Stack
45 * @since 1.0
46 * @deprecated Use {@link ArrayDeque} instead (available from Java 1.6)
47 */
48 @Deprecated
49 public class ArrayStack<E> extends ArrayList<E> {
50
51 /** Ensure serialization compatibility */
52 private static final long serialVersionUID = 2130079159931574599L;
53
54 /**
55 * Constructs a new empty {@code ArrayStack}. The initial size
56 * is controlled by {@code ArrayList} and is currently 10.
57 */
58 public ArrayStack() {
59 }
60
61 /**
62 * Constructs a new empty {@code ArrayStack} with an initial size.
63 *
64 * @param initialSize The initial size to use
65 * @throws IllegalArgumentException if the specified initial size
66 * is negative
67 */
68 public ArrayStack(final int initialSize) {
69 super(initialSize);
70 }
71
72 /**
73 * Return {@code true} if this stack is currently empty.
74 * <p>
75 * This method exists for compatibility with {@link Stack}.
76 * New users of this class should use {@code isEmpty} instead.
77 * </p>
78 *
79 * @return true if the stack is currently empty
80 */
81 public boolean empty() {
82 return isEmpty();
83 }
84
85 /**
86 * Returns the top item off of this stack without removing it.
87 *
88 * @return The top item on the stack
89 * @throws EmptyStackException if the stack is empty
90 */
91 public E peek() throws EmptyStackException {
92 final int n = size();
93 if (n <= 0) {
94 throw new EmptyStackException();
95 }
96 return get(n - 1);
97 }
98
99 /**
100 * Returns the n'th item down (zero-relative) from the top of this
101 * stack without removing it.
102 *
103 * @param n The number of items down to go
104 * @return The n'th item on the stack, zero relative
105 * @throws EmptyStackException if there are not enough items on the
106 * stack to satisfy this request
107 */
108 public E peek(final int n) throws EmptyStackException {
109 final int m = size() - n - 1;
110 if (m < 0) {
111 throw new EmptyStackException();
112 }
113 return get(m);
114 }
115
116 /**
117 * Pops the top item off of this stack and return it.
118 *
119 * @return The top item on the stack
120 * @throws EmptyStackException if the stack is empty
121 */
122 public E pop() throws EmptyStackException {
123 final int n = size();
124 if (n <= 0) {
125 throw new EmptyStackException();
126 }
127 return remove(n - 1);
128 }
129
130 /**
131 * Pushes a new item onto the top of this stack. The pushed item is also
132 * returned. This is equivalent to calling {@code add}.
133 *
134 * @param item The item to be added
135 * @return The item just pushed
136 */
137 public E push(final E item) {
138 add(item);
139 return item;
140 }
141
142 /**
143 * Returns the one-based position of the distance from the top that the
144 * specified object exists on this stack, where the top-most element is
145 * considered to be at distance {@code 1}. If the object is not
146 * present on the stack, return {@code -1} instead. The
147 * {@code equals()} method is used to compare to the items
148 * in this stack.
149 *
150 * @param object The object to be searched for
151 * @return The 1-based depth into the stack of the object, or -1 if not found
152 */
153 public int search(final Object object) {
154 int i = size() - 1; // Current index
155 int n = 1; // Current distance
156 while (i >= 0) {
157 final Object current = get(i);
158 if (object == null && current == null ||
159 object != null && object.equals(current)) {
160 return n;
161 }
162 i--;
163 n++;
164 }
165 return -1;
166 }
167
168 }