ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/jsr166x/ArrayDeque.java

Comparing jsr166/src/jsr166x/ArrayDeque.java (file contents):
Revision 1.9 by jsr166, Tue Feb 21 01:54:03 2012 UTC vs.
Revision 1.13 by jsr166, Sun Jan 18 20:17:33 2015 UTC

#	Line 4 | Line 4
4		*/
5
6		package jsr166x;    // XXX This belongs in java.util!!! XXX
7	+
8		import java.util.*; // XXX This import goes away        XXX
9		import java.io.*;
10
#	Line 16 | Line 17 | import java.io.*;
17		* {@link Stack} when used as a stack, and faster than {@link LinkedList}
18		* when used as a queue.
19		*
20	<	* <p>Most <tt>ArrayDeque</tt> operations run in amortized constant time.
20	>	* <p>Most {@code ArrayDeque} operations run in amortized constant time.
21		* Exceptions include {@link #remove(Object) remove}, {@link
22		* #removeFirstOccurrence removeFirstOccurrence}, {@link #removeLastOccurrence
23		* removeLastOccurrence}, {@link #contains contains }, {@link #iterator
24		* iterator.remove()}, and the bulk operations, all of which run in linear
25		* time.
26		*
27	<	* <p>The iterators returned by this class's <tt>iterator</tt> method are
27	>	* <p>The iterators returned by this class's {@code iterator} method are
28		* <i>fail-fast</i>: If the deque is modified at any time after the iterator
29		* is created, in any way except through the iterator's own remove method, the
30		* iterator will generally throw a {@link ConcurrentModificationException}.
#	Line 34 | Line 35 | import java.io.*;
35		* <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
36		* as it is, generally speaking, impossible to make any hard guarantees in the
37		* presence of unsynchronized concurrent modification.  Fail-fast iterators
38	<	* throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
38	>	* throw {@code ConcurrentModificationException} on a best-effort basis.
39		* Therefore, it would be wrong to write a program that depended on this
40		* exception for its correctness: <i>the fail-fast behavior of iterators
41		* should be used only to detect bugs.</i>
#	Line 88 | Line 89 | public class ArrayDeque<E> extends Abstr
89		/**
90		* Allocates empty array to hold the given number of elements.
91		*
92	<	* @param numElements  the number of elements to hold.
92	>	* @param numElements  the number of elements to hold
93		*/
94		private void allocateElements(int numElements) {
95		int initialCapacity = MIN_INITIAL_CAPACITY;
#	Line 188 | Line 189 | public class ArrayDeque<E> extends Abstr
189		* Inserts the specified element to the front this deque.
190		*
191		* @param e the element to insert
192	<	* @throws NullPointerException if <tt>e</tt> is null
192	>	* @throws NullPointerException if {@code e} is null
193		*/
194		public void addFirst(E e) {
195		if (e == null)
#	Line 204 | Line 205 | public class ArrayDeque<E> extends Abstr
205		* {@link #push}.
206		*
207		* @param e the element to insert
208	<	* @throws NullPointerException if <tt>e</tt> is null
208	>	* @throws NullPointerException if {@code e} is null
209		*/
210		public void addLast(E e) {
211		if (e == null)
#	Line 216 | Line 217 | public class ArrayDeque<E> extends Abstr
217
218		/**
219		* Retrieves and removes the first element of this deque, or
220	<	* <tt>null</tt> if this deque is empty.
220	>	* {@code null} if this deque is empty.
221		*
222	<	* @return the first element of this deque, or <tt>null</tt> if
222	>	* @return the first element of this deque, or {@code null} if
223		*     this deque is empty
224		*/
225		public E pollFirst() {
#	Line 233 | Line 234 | public class ArrayDeque<E> extends Abstr
234
235		/**
236		* Retrieves and removes the last element of this deque, or
237	<	* <tt>null</tt> if this deque is empty.
237	>	* {@code null} if this deque is empty.
238		*
239	<	* @return the last element of this deque, or <tt>null</tt> if
239	>	* @return the last element of this deque, or {@code null} if
240		*     this deque is empty
241		*/
242		public E pollLast() {
#	Line 252 | Line 253 | public class ArrayDeque<E> extends Abstr
253		* Inserts the specified element to the front this deque.
254		*
255		* @param e the element to insert
256	<	* @return <tt>true</tt> (as per the spec for {@link Deque#offerFirst})
257	<	* @throws NullPointerException if <tt>e</tt> is null
256	>	* @return {@code true} (as per the spec for {@link Deque#offerFirst})
257	>	* @throws NullPointerException if {@code e} is null
258		*/
259		public boolean offerFirst(E e) {
260		addFirst(e);
#	Line 264 | Line 265 | public class ArrayDeque<E> extends Abstr
265		* Inserts the specified element to the end this deque.
266		*
267		* @param e the element to insert
268	<	* @return <tt>true</tt> (as per the spec for {@link Deque#offerLast})
269	<	* @throws NullPointerException if <tt>e</tt> is null
268	>	* @return {@code true} (as per the spec for {@link Deque#offerLast})
269	>	* @throws NullPointerException if {@code e} is null
270		*/
271		public boolean offerLast(E e) {
272		addLast(e);
#	Line 274 | Line 275 | public class ArrayDeque<E> extends Abstr
275
276		/**
277		* Retrieves and removes the first element of this deque.  This method
278	<	* differs from the <tt>pollFirst</tt> method in that it throws an
278	>	* differs from the {@code pollFirst} method in that it throws an
279		* exception if this deque is empty.
280		*
281		* @return the first element of this deque
#	Line 289 | Line 290 | public class ArrayDeque<E> extends Abstr
290
291		/**
292		* Retrieves and removes the last element of this deque.  This method
293	<	* differs from the <tt>pollLast</tt> method in that it throws an
293	>	* differs from the {@code pollLast} method in that it throws an
294		* exception if this deque is empty.
295		*
296		* @return the last element of this deque
#	Line 304 | Line 305 | public class ArrayDeque<E> extends Abstr
305
306		/**
307		* Retrieves, but does not remove, the first element of this deque,
308	<	* returning <tt>null</tt> if this deque is empty.
308	>	* returning {@code null} if this deque is empty.
309		*
310	<	* @return the first element of this deque, or <tt>null</tt> if
310	>	* @return the first element of this deque, or {@code null} if
311		*     this deque is empty
312		*/
313		public E peekFirst() {
#	Line 315 | Line 316 | public class ArrayDeque<E> extends Abstr
316
317		/**
318		* Retrieves, but does not remove, the last element of this deque,
319	<	* returning <tt>null</tt> if this deque is empty.
319	>	* returning {@code null} if this deque is empty.
320		*
321	<	* @return the last element of this deque, or <tt>null</tt> if this deque
321	>	* @return the last element of this deque, or {@code null} if this deque
322		*     is empty
323		*/
324		public E peekLast() {
#	Line 326 | Line 327 | public class ArrayDeque<E> extends Abstr
327
328		/**
329		* Retrieves, but does not remove, the first element of this
330	<	* deque.  This method differs from the <tt>peek</tt> method only
330	>	* deque.  This method differs from the {@code peek} method only
331		* in that it throws an exception if this deque is empty.
332		*
333		* @return the first element of this deque
#	Line 341 | Line 342 | public class ArrayDeque<E> extends Abstr
342
343		/**
344		* Retrieves, but does not remove, the last element of this
345	<	* deque.  This method differs from the <tt>peek</tt> method only
345	>	* deque.  This method differs from the {@code peek} method only
346		* in that it throws an exception if this deque is empty.
347		*
348		* @return the last element of this deque
#	Line 360 | Line 361 | public class ArrayDeque<E> extends Abstr
361		* does not contain the element, it is unchanged.
362		*
363		* @param e element to be removed from this deque, if present
364	<	* @return <tt>true</tt> if the deque contained the specified element
364	>	* @return {@code true} if the deque contained the specified element
365		*/
366		public boolean removeFirstOccurrence(Object e) {
367		if (e == null)
#	Line 384 | Line 385 | public class ArrayDeque<E> extends Abstr
385		* does not contain the element, it is unchanged.
386		*
387		* @param e element to be removed from this deque, if present
388	<	* @return <tt>true</tt> if the deque contained the specified element
388	>	* @return {@code true} if the deque contained the specified element
389		*/
390		public boolean removeLastOccurrence(Object e) {
391		if (e == null)
#	Line 410 | Line 411 | public class ArrayDeque<E> extends Abstr
411		* <p>This method is equivalent to {@link #offerLast}.
412		*
413		* @param e the element to insert
414	<	* @return <tt>true</tt> (as per the spec for {@link Queue#offer})
415	<	* @throws NullPointerException if <tt>e</tt> is null
414	>	* @return {@code true} (as per the spec for {@link Queue#offer})
415	>	* @throws NullPointerException if {@code e} is null
416		*/
417		public boolean offer(E e) {
418		return offerLast(e);
#	Line 423 | Line 424 | public class ArrayDeque<E> extends Abstr
424		* <p>This method is equivalent to {@link #addLast}.
425		*
426		* @param e the element to insert
427	<	* @return <tt>true</tt> (as per the spec for {@link Collection#add})
428	<	* @throws NullPointerException if <tt>e</tt> is null
427	>	* @return {@code true} (as per the spec for {@link Collection#add})
428	>	* @throws NullPointerException if {@code e} is null
429		*/
430		public boolean add(E e) {
431		addLast(e);
#	Line 433 | Line 434 | public class ArrayDeque<E> extends Abstr
434
435		/**
436		* Retrieves and removes the head of the queue represented by
437	<	* this deque, or <tt>null</tt> if this deque is empty.  In other words,
438	<	* retrieves and removes the first element of this deque, or <tt>null</tt>
437	>	* this deque, or {@code null} if this deque is empty.  In other words,
438	>	* retrieves and removes the first element of this deque, or {@code null}
439		* if this deque is empty.
440		*
441		* <p>This method is equivalent to {@link #pollFirst}.
442		*
443	<	* @return the first element of this deque, or <tt>null</tt> if
443	>	* @return the first element of this deque, or {@code null} if
444		*     this deque is empty
445		*/
446		public E poll() {
#	Line 448 | Line 449 | public class ArrayDeque<E> extends Abstr
449
450		/**
451		* Retrieves and removes the head of the queue represented by this deque.
452	<	* This method differs from the <tt>poll</tt> method in that it throws an
452	>	* This method differs from the {@code poll} method in that it throws an
453		* exception if this deque is empty.
454		*
455		* <p>This method is equivalent to {@link #removeFirst}.
#	Line 462 | Line 463 | public class ArrayDeque<E> extends Abstr
463
464		/**
465		* Retrieves, but does not remove, the head of the queue represented by
466	<	* this deque, returning <tt>null</tt> if this deque is empty.
466	>	* this deque, returning {@code null} if this deque is empty.
467		*
468	<	* <p>This method is equivalent to {@link #peekFirst}
468	>	* <p>This method is equivalent to {@link #peekFirst}.
469		*
470		* @return the head of the queue represented by this deque, or
471	<	*     <tt>null</tt> if this deque is empty
471	>	*     {@code null} if this deque is empty
472		*/
473		public E peek() {
474		return peekFirst();
#	Line 475 | Line 476 | public class ArrayDeque<E> extends Abstr
476
477		/**
478		* Retrieves, but does not remove, the head of the queue represented by
479	<	* this deque.  This method differs from the <tt>peek</tt> method only in
479	>	* this deque.  This method differs from the {@code peek} method only in
480		* that it throws an exception if this deque is empty.
481		*
482	<	* <p>This method is equivalent to {@link #getFirst}
482	>	* <p>This method is equivalent to {@link #getFirst}.
483		*
484		* @return the head of the queue represented by this deque
485		* @throws NoSuchElementException if this deque is empty
#	Line 496 | Line 497 | public class ArrayDeque<E> extends Abstr
497		* <p>This method is equivalent to {@link #addFirst}.
498		*
499		* @param e the element to push
500	<	* @throws NullPointerException if <tt>e</tt> is null
500	>	* @throws NullPointerException if {@code e} is null
501		*/
502		public void push(E e) {
503		addFirst(e);
#	Line 555 | Line 556 | public class ArrayDeque<E> extends Abstr
556		}
557
558		/**
559	<	* Returns <tt>true</tt> if this collection contains no elements.<p>
559	>	* Returns {@code true} if this collection contains no elements.
560		*
561	<	* @return <tt>true</tt> if this collection contains no elements.
561	>	* @return {@code true} if this collection contains no elements
562		*/
563		public boolean isEmpty() {
564		return head == tail;
#	Line 569 | Line 570 | public class ArrayDeque<E> extends Abstr
570		* order that elements would be dequeued (via successive calls to
571		* {@link #remove} or popped (via successive calls to {@link #pop}).
572		*
573	<	* @return an <tt>Iterator</tt> over the elements in this deque
573	>	* @return an {@code Iterator} over the elements in this deque
574		*/
575		public Iterator<E> iterator() {
576		return new DeqIterator();
#	Line 621 | Line 622 | public class ArrayDeque<E> extends Abstr
622		}
623
624		/**
625	<	* Returns <tt>true</tt> if this deque contains the specified
626	<	* element.  More formally, returns <tt>true</tt> if and only if this
627	<	* deque contains at least one element <tt>e</tt> such that
628	<	* <tt>e.equals(o)</tt>.
625	>	* Returns {@code true} if this deque contains the specified
626	>	* element.  More formally, returns {@code true} if and only if this
627	>	* deque contains at least one element {@code e} such that
628	>	* {@code e.equals(o)}.
629		*
630		* @param o object to be checked for containment in this deque
631	<	* @return <tt>true</tt> if this deque contains the specified element
631	>	* @return {@code true} if this deque contains the specified element
632		*/
633		public boolean contains(Object o) {
634		if (o == null)
#	Line 648 | Line 649 | public class ArrayDeque<E> extends Abstr
649		* This method is equivalent to {@link #removeFirstOccurrence}.
650		*
651		* @param e element to be removed from this deque, if present
652	<	* @return <tt>true</tt> if this deque contained the specified element
652	>	* @return {@code true} if this deque contained the specified element
653		*/
654		public boolean remove(Object e) {
655		return removeFirstOccurrence(e);
#	Line 691 | Line 692 | public class ArrayDeque<E> extends Abstr
692		*
693		* <p>If the deque fits in the specified array with room to spare (i.e.,
694		* the array has more elements than the deque), the element in the array
695	<	* immediately following the end of the collection is set to <tt>null</tt>.
695	>	* immediately following the end of the collection is set to {@code null}.
696		*
697		* @param a the array into which the elements of the deque are to
698		*          be stored, if it is big enough; otherwise, a new array of the
#	Line 739 | Line 740 | public class ArrayDeque<E> extends Abstr
740		/**
741		* Serializes this deque.
742		*
743	<	* @serialData The current size (<tt>int</tt>) of the deque,
743	>	* @serialData The current size ({@code int}) of the deque,
744		* followed by all of its elements (each an object reference) in
745		* first-to-last order.
746		*/

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines