4 |
|
*/ |
5 |
|
|
6 |
|
package java.util; |
7 |
+ |
import java.util.*; // for javadoc (till 6280605 is fixed) |
8 |
|
import java.io.*; |
9 |
|
|
10 |
|
/** |
203 |
|
|
204 |
|
/** |
205 |
|
* Inserts the specified element at the end of this deque. |
206 |
< |
* This method is equivalent to {@link #add} and {@link #push}. |
206 |
> |
* |
207 |
> |
* <p>This method is equivalent to {@link #add}. |
208 |
|
* |
209 |
|
* @param e the element to add |
210 |
|
* @throws NullPointerException if the specified element is null |
221 |
|
* Inserts the specified element at the front of this deque. |
222 |
|
* |
223 |
|
* @param e the element to add |
224 |
< |
* @return <tt>true</tt> (as per the spec for {@link Deque#offerFirst}) |
224 |
> |
* @return <tt>true</tt> (as specified by {@link Deque#offerFirst}) |
225 |
|
* @throws NullPointerException if the specified element is null |
226 |
|
*/ |
227 |
|
public boolean offerFirst(E e) { |
233 |
|
* Inserts the specified element at the end of this deque. |
234 |
|
* |
235 |
|
* @param e the element to add |
236 |
< |
* @return <tt>true</tt> (as per the spec for {@link Deque#offerLast}) |
236 |
> |
* @return <tt>true</tt> (as specified by {@link Deque#offerLast}) |
237 |
|
* @throws NullPointerException if the specified element is null |
238 |
|
*/ |
239 |
|
public boolean offerLast(E e) { |
315 |
|
* If the deque does not contain the element, it is unchanged. |
316 |
|
* More formally, removes the first element <tt>e</tt> such that |
317 |
|
* <tt>o.equals(e)</tt> (if such an element exists). |
318 |
< |
* Returns true if this deque contained the specified element (or |
319 |
< |
* equivalently, if this deque changed as a result of the call). |
318 |
> |
* Returns <tt>true</tt> if this deque contained the specified element |
319 |
> |
* (or equivalently, if this deque changed as a result of the call). |
320 |
|
* |
321 |
|
* @param o element to be removed from this deque, if present |
322 |
|
* @return <tt>true</tt> if the deque contained the specified element |
343 |
|
* If the deque does not contain the element, it is unchanged. |
344 |
|
* More formally, removes the last element <tt>e</tt> such that |
345 |
|
* <tt>o.equals(e)</tt> (if such an element exists). |
346 |
< |
* Returns true if this deque contained the specified element (or |
347 |
< |
* equivalently, if this deque changed as a result of the call). |
346 |
> |
* Returns <tt>true</tt> if this deque contained the specified element |
347 |
> |
* (or equivalently, if this deque changed as a result of the call). |
348 |
|
* |
349 |
|
* @param o element to be removed from this deque, if present |
350 |
|
* @return <tt>true</tt> if the deque contained the specified element |
373 |
|
* <p>This method is equivalent to {@link #addLast}. |
374 |
|
* |
375 |
|
* @param e the element to add |
376 |
< |
* @return <tt>true</tt> (as per the spec for {@link Collection#add}) |
376 |
> |
* @return <tt>true</tt> (as specified by {@link Collection#add}) |
377 |
|
* @throws NullPointerException if the specified element is null |
378 |
|
*/ |
379 |
|
public boolean add(E e) { |
387 |
|
* <p>This method is equivalent to {@link #offerLast}. |
388 |
|
* |
389 |
|
* @param e the element to add |
390 |
< |
* @return <tt>true</tt> (as per the spec for {@link Queue#offer}) |
390 |
> |
* @return <tt>true</tt> (as specified by {@link Queue#offer}) |
391 |
|
* @throws NullPointerException if the specified element is null |
392 |
|
*/ |
393 |
|
public boolean offer(E e) { |
396 |
|
|
397 |
|
/** |
398 |
|
* Retrieves and removes the head of the queue represented by this deque. |
399 |
< |
* This method differs from {@link #poll} only in that it throws an |
399 |
> |
* |
400 |
> |
* This method differs from {@link #poll poll} only in that it throws an |
401 |
|
* exception if this deque is empty. |
402 |
|
* |
403 |
|
* <p>This method is equivalent to {@link #removeFirst}. |
425 |
|
|
426 |
|
/** |
427 |
|
* Retrieves, but does not remove, the head of the queue represented by |
428 |
< |
* this deque. This method differs from {@link #peek} only in that it |
429 |
< |
* throws an exception if this deque is empty. |
428 |
> |
* this deque. This method differs from {@link #peek peek} only in |
429 |
> |
* that it throws an exception if this deque is empty. |
430 |
|
* |
431 |
|
* <p>This method is equivalent to {@link #getFirst}. |
432 |
|
* |
490 |
|
* @return true if elements moved backwards |
491 |
|
*/ |
492 |
|
private boolean delete(int i) { |
493 |
+ |
final E[] elements = this.elements; |
494 |
+ |
final int mask = elements.length - 1; |
495 |
+ |
final int h = head; |
496 |
+ |
final int t = tail; |
497 |
+ |
final int front = (i - h) & mask; |
498 |
+ |
final int back = (t - i) & mask; |
499 |
+ |
|
500 |
+ |
// Invariant: head <= i < tail mod circularity |
501 |
+ |
if (front >= ((t - h) & mask)) |
502 |
+ |
throw new ConcurrentModificationException(); |
503 |
+ |
|
504 |
+ |
// Optimize for least element motion |
505 |
+ |
if (front < back) { |
506 |
+ |
if (h <= i) { |
507 |
+ |
System.arraycopy(elements, h, elements, h + 1, front); |
508 |
+ |
} else { // Wrap around |
509 |
+ |
System.arraycopy(elements, 0, elements, 1, i); |
510 |
+ |
elements[0] = elements[mask]; |
511 |
+ |
System.arraycopy(elements, h, elements, h + 1, mask - h); |
512 |
+ |
} |
513 |
+ |
elements[h] = null; |
514 |
+ |
head = (h + 1) & mask; |
515 |
+ |
return false; |
516 |
+ |
} else { |
517 |
+ |
if (i < t) { // Copy the null tail as well |
518 |
+ |
System.arraycopy(elements, i + 1, elements, i, back); |
519 |
+ |
tail = t - 1; |
520 |
+ |
} else { // Wrap around |
521 |
+ |
System.arraycopy(elements, i + 1, elements, i, mask - i); |
522 |
+ |
elements[mask] = elements[0]; |
523 |
+ |
System.arraycopy(elements, 1, elements, 0, t); |
524 |
+ |
tail = (t - 1) & mask; |
525 |
+ |
} |
526 |
+ |
return true; |
527 |
+ |
} |
528 |
+ |
} |
529 |
+ |
|
530 |
+ |
private boolean xdelete(int i) { |
531 |
|
int mask = elements.length - 1; |
532 |
+ |
int front = (i - head) & mask; |
533 |
+ |
int back = (tail - i) & mask; |
534 |
|
|
535 |
|
// Invariant: head <= i < tail mod circularity |
536 |
< |
if (((i - head) & mask) >= ((tail - head) & mask)) |
536 |
> |
if (front >= ((tail - head) & mask)) |
537 |
|
throw new ConcurrentModificationException(); |
538 |
|
|
539 |
< |
// Case 1: Deque doesn't wrap |
540 |
< |
// Case 2: Deque does wrap and removed element is in the head portion |
541 |
< |
if (i >= head) { |
542 |
< |
System.arraycopy(elements, head, elements, head + 1, i - head); |
543 |
< |
elements[head] = null; |
544 |
< |
head = (head + 1) & mask; |
539 |
> |
// Optimize for least element motion |
540 |
> |
if (front < back) { |
541 |
> |
if (head <= i) { |
542 |
> |
System.arraycopy(elements, head, elements, head + 1, front); |
543 |
> |
} else { // Wrap around |
544 |
> |
System.arraycopy(elements, 0, elements, 1, i); |
545 |
> |
elements[0] = elements[mask]; |
546 |
> |
System.arraycopy(elements, head, elements, head + 1, mask - head); |
547 |
> |
} |
548 |
> |
elements[head] = null; |
549 |
> |
head = (head + 1) & mask; |
550 |
|
return false; |
551 |
< |
} |
552 |
< |
|
553 |
< |
// Case 3: Deque wraps and removed element is in the tail portion |
554 |
< |
tail--; |
555 |
< |
System.arraycopy(elements, i + 1, elements, i, tail - i); |
556 |
< |
elements[tail] = null; |
557 |
< |
return true; |
551 |
> |
} else { |
552 |
> |
int t = tail; |
553 |
> |
tail = (tail - 1) & mask; |
554 |
> |
if (i < t) { // Copy the null tail as well |
555 |
> |
System.arraycopy(elements, i + 1, elements, i, back); |
556 |
> |
} else { // Wrap around |
557 |
> |
System.arraycopy(elements, i + 1, elements, i, mask - i); |
558 |
> |
elements[mask] = elements[0]; |
559 |
> |
System.arraycopy(elements, 1, elements, 0, t); |
560 |
> |
} |
561 |
> |
return true; |
562 |
> |
} |
563 |
|
} |
564 |
|
|
565 |
|
// *** Collection Methods *** |
588 |
|
* order that elements would be dequeued (via successive calls to |
589 |
|
* {@link #remove} or popped (via successive calls to {@link #pop}). |
590 |
|
* |
591 |
< |
* @return an <tt>Iterator</tt> over the elements in this deque |
591 |
> |
* @return an iterator over the elements in this deque |
592 |
|
*/ |
593 |
|
public Iterator<E> iterator() { |
594 |
|
return new DeqIterator(); |
595 |
|
} |
596 |
|
|
597 |
+ |
public Iterator<E> descendingIterator() { |
598 |
+ |
return new DescendingIterator(); |
599 |
+ |
} |
600 |
+ |
|
601 |
|
private class DeqIterator implements Iterator<E> { |
602 |
|
/** |
603 |
|
* Index of element to be returned by subsequent call to next. |
636 |
|
public void remove() { |
637 |
|
if (lastRet < 0) |
638 |
|
throw new IllegalStateException(); |
639 |
< |
if (delete(lastRet)) |
640 |
< |
cursor--; |
639 |
> |
if (delete(lastRet)) // if left-shifted, undo increment in next() |
640 |
> |
cursor = (cursor - 1) & (elements.length - 1); |
641 |
|
lastRet = -1; |
642 |
|
fence = tail; |
643 |
|
} |
644 |
|
} |
645 |
|
|
646 |
+ |
|
647 |
+ |
private class DescendingIterator implements Iterator<E> { |
648 |
+ |
/* |
649 |
+ |
* This class is nearly a mirror-image of DeqIterator, using |
650 |
+ |
* (tail-1) instead of head for initial cursor, (head-1) |
651 |
+ |
* instead of tail for fence, and elements.length instead of -1 |
652 |
+ |
* for sentinel. It shares the same structure, but not many |
653 |
+ |
* actual lines of code. |
654 |
+ |
*/ |
655 |
+ |
private int cursor = (tail - 1) & (elements.length - 1); |
656 |
+ |
private int fence = (head - 1) & (elements.length - 1); |
657 |
+ |
private int lastRet = elements.length; |
658 |
+ |
|
659 |
+ |
public boolean hasNext() { |
660 |
+ |
return cursor != fence; |
661 |
+ |
} |
662 |
+ |
|
663 |
+ |
public E next() { |
664 |
+ |
E result; |
665 |
+ |
if (cursor == fence) |
666 |
+ |
throw new NoSuchElementException(); |
667 |
+ |
if (((head - 1) & (elements.length - 1)) != fence || |
668 |
+ |
(result = elements[cursor]) == null) |
669 |
+ |
throw new ConcurrentModificationException(); |
670 |
+ |
lastRet = cursor; |
671 |
+ |
cursor = (cursor - 1) & (elements.length - 1); |
672 |
+ |
return result; |
673 |
+ |
} |
674 |
+ |
|
675 |
+ |
public void remove() { |
676 |
+ |
if (lastRet >= elements.length) |
677 |
+ |
throw new IllegalStateException(); |
678 |
+ |
if (!delete(lastRet)) |
679 |
+ |
cursor = (cursor + 1) & (elements.length - 1); |
680 |
+ |
lastRet = elements.length; |
681 |
+ |
fence = (head - 1) & (elements.length - 1); |
682 |
+ |
} |
683 |
+ |
} |
684 |
+ |
|
685 |
|
/** |
686 |
|
* Returns <tt>true</tt> if this deque contains the specified element. |
687 |
|
* More formally, returns <tt>true</tt> if and only if this deque contains |
709 |
|
* If the deque does not contain the element, it is unchanged. |
710 |
|
* More formally, removes the first element <tt>e</tt> such that |
711 |
|
* <tt>o.equals(e)</tt> (if such an element exists). |
712 |
< |
* Returns true if this deque contained the specified element (or |
713 |
< |
* equivalently, if this deque changed as a result of the call). |
712 |
> |
* Returns <tt>true</tt> if this deque contained the specified element |
713 |
> |
* (or equivalently, if this deque changed as a result of the call). |
714 |
|
* |
715 |
|
* <p>This method is equivalent to {@link #removeFirstOccurrence}. |
716 |
|
* |
746 |
|
* <p>The returned array will be "safe" in that no references to it are |
747 |
|
* maintained by this deque. (In other words, this method must allocate |
748 |
|
* a new array). The caller is thus free to modify the returned array. |
749 |
< |
* |
749 |
> |
* |
750 |
|
* <p>This method acts as bridge between array-based and collection-based |
751 |
|
* APIs. |
752 |
|
* |
840 |
|
s.defaultWriteObject(); |
841 |
|
|
842 |
|
// Write out size |
843 |
< |
int size = size(); |
748 |
< |
s.writeInt(size); |
843 |
> |
s.writeInt(size()); |
844 |
|
|
845 |
|
// Write out elements in order. |
751 |
– |
int i = head; |
846 |
|
int mask = elements.length - 1; |
847 |
< |
for (int j = 0; j < size; j++) { |
847 |
> |
for (int i = head; i != tail; i = (i + 1) & mask) |
848 |
|
s.writeObject(elements[i]); |
755 |
– |
i = (i + 1) & mask; |
756 |
– |
} |
849 |
|
} |
850 |
|
|
851 |
|
/** |