176 * elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
177 * {@link #removeLastOccurrence removeLastOccurrence}.
178 *
179 * <p>Unlike the {@link List} interface, this interface does not
180 * provide support for indexed access to elements.
181 *
182 * <p>While {@code Deque} implementations are not strictly required
183 * to prohibit the insertion of null elements, they are strongly
184 * encouraged to do so. Users of any {@code Deque} implementations
185 * that do allow null elements are strongly encouraged <i>not</i> to
186 * take advantage of the ability to insert nulls. This is so because
187 * {@code null} is used as a special return value by various methods
188 * to indicate that the deque is empty.
189 *
190 * <p>{@code Deque} implementations generally do not define
191 * element-based versions of the {@code equals} and {@code hashCode}
192 * methods, but instead inherit the identity-based versions from class
193 * {@code Object}.
194 *
195 * <p>This interface is a member of the
196 * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
197 * Java Collections Framework</a>.
198 *
199 * @author Doug Lea
200 * @author Josh Bloch
201 * @since 1.6
202 * @param <E> the type of elements held in this deque
203 */
204 public interface Deque<E> extends Queue<E> {
205 /**
206 * Inserts the specified element at the front of this deque if it is
207 * possible to do so immediately without violating capacity restrictions,
208 * throwing an {@code IllegalStateException} if no space is currently
209 * available. When using a capacity-restricted deque, it is generally
210 * preferable to use method {@link #offerFirst}.
211 *
212 * @param e the element to add
213 * @throws IllegalStateException if the element cannot be added at this
214 * time due to capacity restrictions
215 * @throws ClassCastException if the class of the specified element
216 * prevents it from being added to this deque
346 /**
347 * Retrieves, but does not remove, the last element of this deque,
348 * or returns {@code null} if this deque is empty.
349 *
350 * @return the tail of this deque, or {@code null} if this deque is empty
351 */
352 E peekLast();
353
354 /**
355 * Removes the first occurrence of the specified element from this deque.
356 * If the deque does not contain the element, it is unchanged.
357 * More formally, removes the first element {@code e} such that
358 * {@code Objects.equals(o, e)} (if such an element exists).
359 * Returns {@code true} if this deque contained the specified element
360 * (or equivalently, if this deque changed as a result of the call).
361 *
362 * @param o element to be removed from this deque, if present
363 * @return {@code true} if an element was removed as a result of this call
364 * @throws ClassCastException if the class of the specified element
365 * is incompatible with this deque
366 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
367 * @throws NullPointerException if the specified element is null and this
368 * deque does not permit null elements
369 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
370 */
371 boolean removeFirstOccurrence(Object o);
372
373 /**
374 * Removes the last occurrence of the specified element from this deque.
375 * If the deque does not contain the element, it is unchanged.
376 * More formally, removes the last element {@code e} such that
377 * {@code Objects.equals(o, e)} (if such an element exists).
378 * Returns {@code true} if this deque contained the specified element
379 * (or equivalently, if this deque changed as a result of the call).
380 *
381 * @param o element to be removed from this deque, if present
382 * @return {@code true} if an element was removed as a result of this call
383 * @throws ClassCastException if the class of the specified element
384 * is incompatible with this deque
385 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
386 * @throws NullPointerException if the specified element is null and this
387 * deque does not permit null elements
388 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
389 */
390 boolean removeLastOccurrence(Object o);
391
392 // *** Queue methods ***
393
394 /**
395 * Inserts the specified element into the queue represented by this deque
396 * (in other words, at the tail of this deque) if it is possible to do so
397 * immediately without violating capacity restrictions, returning
398 * {@code true} upon success and throwing an
399 * {@code IllegalStateException} if no space is currently available.
400 * When using a capacity-restricted deque, it is generally preferable to
401 * use {@link #offer(Object) offer}.
402 *
403 * <p>This method is equivalent to {@link #addLast}.
404 *
405 * @param e the element to add
406 * @return {@code true} (as specified by {@link Collection#add})
407 * @throws IllegalStateException if the element cannot be added at this
408 * time due to capacity restrictions
548 */
549 E pop();
550
551
552 // *** Collection methods ***
553
554 /**
555 * Removes the first occurrence of the specified element from this deque.
556 * If the deque does not contain the element, it is unchanged.
557 * More formally, removes the first element {@code e} such that
558 * {@code Objects.equals(o, e)} (if such an element exists).
559 * Returns {@code true} if this deque contained the specified element
560 * (or equivalently, if this deque changed as a result of the call).
561 *
562 * <p>This method is equivalent to {@link #removeFirstOccurrence(Object)}.
563 *
564 * @param o element to be removed from this deque, if present
565 * @return {@code true} if an element was removed as a result of this call
566 * @throws ClassCastException if the class of the specified element
567 * is incompatible with this deque
568 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
569 * @throws NullPointerException if the specified element is null and this
570 * deque does not permit null elements
571 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
572 */
573 boolean remove(Object o);
574
575 /**
576 * Returns {@code true} if this deque contains the specified element.
577 * More formally, returns {@code true} if and only if this deque contains
578 * at least one element {@code e} such that {@code Objects.equals(o, e)}.
579 *
580 * @param o element whose presence in this deque is to be tested
581 * @return {@code true} if this deque contains the specified element
582 * @throws ClassCastException if the class of the specified element
583 * is incompatible with this deque
584 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
585 * @throws NullPointerException if the specified element is null and this
586 * deque does not permit null elements
587 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
588 */
589 boolean contains(Object o);
590
591 /**
592 * Returns the number of elements in this deque.
593 *
594 * @return the number of elements in this deque
595 */
596 int size();
597
598 /**
599 * Returns an iterator over the elements in this deque in proper sequence.
600 * The elements will be returned in order from first (head) to last (tail).
601 *
602 * @return an iterator over the elements in this deque in proper sequence
603 */
604 Iterator<E> iterator();
605
606 /**
607 * Returns an iterator over the elements in this deque in reverse
|
176 * elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
177 * {@link #removeLastOccurrence removeLastOccurrence}.
178 *
179 * <p>Unlike the {@link List} interface, this interface does not
180 * provide support for indexed access to elements.
181 *
182 * <p>While {@code Deque} implementations are not strictly required
183 * to prohibit the insertion of null elements, they are strongly
184 * encouraged to do so. Users of any {@code Deque} implementations
185 * that do allow null elements are strongly encouraged <i>not</i> to
186 * take advantage of the ability to insert nulls. This is so because
187 * {@code null} is used as a special return value by various methods
188 * to indicate that the deque is empty.
189 *
190 * <p>{@code Deque} implementations generally do not define
191 * element-based versions of the {@code equals} and {@code hashCode}
192 * methods, but instead inherit the identity-based versions from class
193 * {@code Object}.
194 *
195 * <p>This interface is a member of the
196 * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
197 * Java Collections Framework</a>.
198 *
199 * @author Doug Lea
200 * @author Josh Bloch
201 * @since 1.6
202 * @param <E> the type of elements held in this deque
203 */
204 public interface Deque<E> extends Queue<E> {
205 /**
206 * Inserts the specified element at the front of this deque if it is
207 * possible to do so immediately without violating capacity restrictions,
208 * throwing an {@code IllegalStateException} if no space is currently
209 * available. When using a capacity-restricted deque, it is generally
210 * preferable to use method {@link #offerFirst}.
211 *
212 * @param e the element to add
213 * @throws IllegalStateException if the element cannot be added at this
214 * time due to capacity restrictions
215 * @throws ClassCastException if the class of the specified element
216 * prevents it from being added to this deque
346 /**
347 * Retrieves, but does not remove, the last element of this deque,
348 * or returns {@code null} if this deque is empty.
349 *
350 * @return the tail of this deque, or {@code null} if this deque is empty
351 */
352 E peekLast();
353
354 /**
355 * Removes the first occurrence of the specified element from this deque.
356 * If the deque does not contain the element, it is unchanged.
357 * More formally, removes the first element {@code e} such that
358 * {@code Objects.equals(o, e)} (if such an element exists).
359 * Returns {@code true} if this deque contained the specified element
360 * (or equivalently, if this deque changed as a result of the call).
361 *
362 * @param o element to be removed from this deque, if present
363 * @return {@code true} if an element was removed as a result of this call
364 * @throws ClassCastException if the class of the specified element
365 * is incompatible with this deque
366 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
367 * @throws NullPointerException if the specified element is null and this
368 * deque does not permit null elements
369 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
370 */
371 boolean removeFirstOccurrence(Object o);
372
373 /**
374 * Removes the last occurrence of the specified element from this deque.
375 * If the deque does not contain the element, it is unchanged.
376 * More formally, removes the last element {@code e} such that
377 * {@code Objects.equals(o, e)} (if such an element exists).
378 * Returns {@code true} if this deque contained the specified element
379 * (or equivalently, if this deque changed as a result of the call).
380 *
381 * @param o element to be removed from this deque, if present
382 * @return {@code true} if an element was removed as a result of this call
383 * @throws ClassCastException if the class of the specified element
384 * is incompatible with this deque
385 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
386 * @throws NullPointerException if the specified element is null and this
387 * deque does not permit null elements
388 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
389 */
390 boolean removeLastOccurrence(Object o);
391
392 // *** Queue methods ***
393
394 /**
395 * Inserts the specified element into the queue represented by this deque
396 * (in other words, at the tail of this deque) if it is possible to do so
397 * immediately without violating capacity restrictions, returning
398 * {@code true} upon success and throwing an
399 * {@code IllegalStateException} if no space is currently available.
400 * When using a capacity-restricted deque, it is generally preferable to
401 * use {@link #offer(Object) offer}.
402 *
403 * <p>This method is equivalent to {@link #addLast}.
404 *
405 * @param e the element to add
406 * @return {@code true} (as specified by {@link Collection#add})
407 * @throws IllegalStateException if the element cannot be added at this
408 * time due to capacity restrictions
548 */
549 E pop();
550
551
552 // *** Collection methods ***
553
554 /**
555 * Removes the first occurrence of the specified element from this deque.
556 * If the deque does not contain the element, it is unchanged.
557 * More formally, removes the first element {@code e} such that
558 * {@code Objects.equals(o, e)} (if such an element exists).
559 * Returns {@code true} if this deque contained the specified element
560 * (or equivalently, if this deque changed as a result of the call).
561 *
562 * <p>This method is equivalent to {@link #removeFirstOccurrence(Object)}.
563 *
564 * @param o element to be removed from this deque, if present
565 * @return {@code true} if an element was removed as a result of this call
566 * @throws ClassCastException if the class of the specified element
567 * is incompatible with this deque
568 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
569 * @throws NullPointerException if the specified element is null and this
570 * deque does not permit null elements
571 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
572 */
573 boolean remove(Object o);
574
575 /**
576 * Returns {@code true} if this deque contains the specified element.
577 * More formally, returns {@code true} if and only if this deque contains
578 * at least one element {@code e} such that {@code Objects.equals(o, e)}.
579 *
580 * @param o element whose presence in this deque is to be tested
581 * @return {@code true} if this deque contains the specified element
582 * @throws ClassCastException if the class of the specified element
583 * is incompatible with this deque
584 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
585 * @throws NullPointerException if the specified element is null and this
586 * deque does not permit null elements
587 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
588 */
589 boolean contains(Object o);
590
591 /**
592 * Returns the number of elements in this deque.
593 *
594 * @return the number of elements in this deque
595 */
596 int size();
597
598 /**
599 * Returns an iterator over the elements in this deque in proper sequence.
600 * The elements will be returned in order from first (head) to last (tail).
601 *
602 * @return an iterator over the elements in this deque in proper sequence
603 */
604 Iterator<E> iterator();
605
606 /**
607 * Returns an iterator over the elements in this deque in reverse
|