GNU Classpath (0.98) | |
Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
First Element (Head) | Last Element (Tail) | |||
Throws exception | Special value | Throws exception | Special value | |
Insert | addFirst(e) | offerFirst(e) | addLast(e) | offerLast(e) |
Remove | removeFirst() | pollFirst() | removeLast() | pollLast() |
Examine | getFirst() | peekFirst() | getLast() | peekLast() |
Queue
interface. When a deque is
used as a queue, FIFO (First-In-First-Out) behavior results. Elements are
added at the end of the deque and removed from the beginning. The methods
inherited from the Queue interface are precisely equivalent to
Deque methods as indicated in the following table:
Queue Method | Equivalent Deque Method |
add(e) | addLast(e) |
offer(e) | offerLast(e) |
remove() | removeFirst() |
poll() | pollFirst() |
element() | getFirst() |
peek() | peekFirst() |
Stack
class.
When a deque is used as a stack, elements are pushed and popped from the
beginning of the deque. Stack methods are precisely equivalent to
Deque methods as indicated in the table below:
Stack Method | Equivalent Deque Method |
push(e) | addFirst(e) |
pop() | removeFirst() |
peek() | peekFirst() |
peek
method works equally well when
a deque is used as a queue or a stack; in either case, elements are
drawn from the beginning of the deque.
This interface provides two methods to remove interior
elements, removeFirstOccurrence
and
removeLastOccurrence
.
Unlike the List
interface, this interface does not
provide support for indexed access to elements.
While Deque implementations are not strictly required
to prohibit the insertion of null elements, they are strongly
encouraged to do so. Users of any Deque implementations
that do allow null elements are strongly encouraged not to
take advantage of the ability to insert nulls. This is so because
null is used as a special return value by various methods
to indicated that the deque is empty.
Deque implementations generally do not define
element-based versions of the equals and hashCode
methods, but instead inherit the identity-based versions from class
Object.
This interface is a member of the ../../../technotes/guides/collections/index.html"> Java Collections
Framework.
Method Summary | |
boolean |
|
void |
|
void |
|
boolean | |
Iterator |
|
E |
|
E |
|
E |
|
Iterator |
|
boolean |
|
boolean |
|
boolean |
|
E |
|
E |
|
E |
|
E |
|
E |
|
E |
|
E |
|
void |
|
E |
|
boolean | |
E |
|
boolean |
|
E |
|
boolean |
|
int |
|
Methods inherited from interface java.util.Collection<E> | |
T[] toArray , add , addAll , clear , contains , containsAll , equals , hashCode , isEmpty , iterator , remove , removeAll , retainAll , size , toArray |
Methods inherited from interface java.lang.Iterable<E> | |
iterator |
public boolean add(E e)
Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returning true upon success and throwing an IllegalStateException if no space is currently available. When using a capacity-restricted deque, it is generally preferable to useoffer
. This method is equivalent toaddLast(E)
.
- Specified by:
- add in interface Queue<E>
- add in interface Collection<E>
- Parameters:
e
- the element to add
- Returns:
- true (as specified by
Collection.add(E)
)
- Throws:
IllegalStateException
- if the element cannot be added at this time due to capacity restrictionsClassCastException
- if the class of the specified element prevents it from being added to this dequeNullPointerException
- if the specified element is null and this deque does not permit null elementsIllegalArgumentException
- if some property of the specified element prevents it from being added to this deque
public void addFirst(E e)
Inserts the specified element at the front of this deque if it is possible to do so immediately without violating capacity restrictions. When using a capacity-restricted deque, it is generally preferable to use methodofferFirst(E)
.
- Parameters:
e
- the element to add
- Throws:
IllegalStateException
- if the element cannot be added at this time due to capacity restrictionsClassCastException
- if the class of the specified element prevents it from being added to this dequeNullPointerException
- if the specified element is null and this deque does not permit null elementsIllegalArgumentException
- if some property of the specified element prevents it from being added to this deque
public void addLast(E e)
Inserts the specified element at the end of this deque if it is possible to do so immediately without violating capacity restrictions. When using a capacity-restricted deque, it is generally preferable to use methodofferLast(E)
. This method is equivalent toadd(E)
.
- Parameters:
e
- the element to add
- Throws:
IllegalStateException
- if the element cannot be added at this time due to capacity restrictionsClassCastException
- if the class of the specified element prevents it from being added to this dequeNullPointerException
- if the specified element is null and this deque does not permit null elementsIllegalArgumentException
- if some property of the specified element prevents it from being added to this deque
public boolean contains(Object o)
Returns true if this deque contains the specified element. More formally, returns true if and only if this deque contains at least one element e such that (o==null ? e==null : o.equals(e)).
- Specified by:
- contains in interface Collection<E>
- Parameters:
o
- element whose presence in this deque is to be tested
- Returns:
- true if this deque contains the specified element
- Throws:
ClassCastException
- if the type of the specified element is incompatible with this deque (optional)NullPointerException
- if the specified element is null and this deque does not permit null elements (optional)
public IteratordescendingIterator()
Returns an iterator over the elements in this deque in reverse sequential order. The elements will be returned in order from last (tail) to first (head).
- Returns:
- an iterator over the elements in this deque in reverse sequence
public E element()
Retrieves, but does not remove, the head of the queue represented by this deque (in other words, the first element of this deque). This method differs frompeek
only in that it throws an exception if this deque is empty. This method is equivalent togetFirst()
.
- Returns:
- the head of the queue represented by this deque
- Throws:
NoSuchElementException
- if this deque is empty
public E getFirst()
Retrieves, but does not remove, the first element of this deque. This method differs frompeekFirst
only in that it throws an exception if this deque is empty.
- Returns:
- the head of this deque
- Throws:
NoSuchElementException
- if this deque is empty
public E getLast()
Retrieves, but does not remove, the last element of this deque. This method differs frompeekLast
only in that it throws an exception if this deque is empty.
- Returns:
- the tail of this deque
- Throws:
NoSuchElementException
- if this deque is empty
public Iteratoriterator()
Returns an iterator over the elements in this deque in proper sequence. The elements will be returned in order from first (head) to last (tail).
- Specified by:
- iterator in interface Collection<E>
- iterator in interface Iterable<E>
- Returns:
- an iterator over the elements in this deque in proper sequence
public boolean offer(E e)
Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returning true upon success and false if no space is currently available. When using a capacity-restricted deque, this method is generally preferable to theadd(E)
method, which can fail to insert an element only by throwing an exception. This method is equivalent toofferLast(E)
.
- Parameters:
e
- the element to add
- Returns:
- true if the element was added to this deque, else false
- Throws:
ClassCastException
- if the class of the specified element prevents it from being added to this dequeNullPointerException
- if the specified element is null and this deque does not permit null elementsIllegalArgumentException
- if some property of the specified element prevents it from being added to this deque
public boolean offerFirst(E e)
Inserts the specified element at the front of this deque unless it would violate capacity restrictions. When using a capacity-restricted deque, this method is generally preferable to theaddFirst(E)
method, which can fail to insert an element only by throwing an exception.
- Parameters:
e
- the element to add
- Returns:
- true if the element was added to this deque, else false
- Throws:
ClassCastException
- if the class of the specified element prevents it from being added to this dequeNullPointerException
- if the specified element is null and this deque does not permit null elementsIllegalArgumentException
- if some property of the specified element prevents it from being added to this deque
public boolean offerLast(E e)
Inserts the specified element at the end of this deque unless it would violate capacity restrictions. When using a capacity-restricted deque, this method is generally preferable to theaddLast(E)
method, which can fail to insert an element only by throwing an exception.
- Parameters:
e
- the element to add
- Returns:
- true if the element was added to this deque, else false
- Throws:
ClassCastException
- if the class of the specified element prevents it from being added to this dequeNullPointerException
- if the specified element is null and this deque does not permit null elementsIllegalArgumentException
- if some property of the specified element prevents it from being added to this deque
public E peek()
Retrieves, but does not remove, the head of the queue represented by this deque (in other words, the first element of this deque), or returns null if this deque is empty. This method is equivalent topeekFirst()
.
- Returns:
- the head of the queue represented by this deque, or null if this deque is empty
public E peekFirst()
Retrieves, but does not remove, the first element of this deque, or returns null if this deque is empty.
- Returns:
- the head of this deque, or null if this deque is empty
public E peekLast()
Retrieves, but does not remove, the last element of this deque, or returns null if this deque is empty.
- Returns:
- the tail of this deque, or null if this deque is empty
public E poll()
Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), or returns null if this deque is empty. This method is equivalent topollFirst()
.
- Returns:
- the first element of this deque, or null if this deque is empty
public E pollFirst()
Retrieves and removes the first element of this deque, or returns null if this deque is empty.
- Returns:
- the head of this deque, or null if this deque is empty
public E pollLast()
Retrieves and removes the last element of this deque, or returns null if this deque is empty.
- Returns:
- the tail of this deque, or null if this deque is empty
public E pop()
Pops an element from the stack represented by this deque. In other words, removes and returns the first element of this deque. This method is equivalent toremoveFirst()
.
- Returns:
- the element at the front of this deque (which is the top of the stack represented by this deque)
- Throws:
NoSuchElementException
- if this deque is empty
public void push(E e)
Pushes an element onto the stack represented by this deque (in other words, at the head of this deque) if it is possible to do so immediately without violating capacity restrictions, returning true upon success and throwing an IllegalStateException if no space is currently available. This method is equivalent toaddFirst(E)
.
- Parameters:
e
- the element to push
- Throws:
IllegalStateException
- if the element cannot be added at this time due to capacity restrictionsClassCastException
- if the class of the specified element prevents it from being added to this dequeNullPointerException
- if the specified element is null and this deque does not permit null elementsIllegalArgumentException
- if some property of the specified element prevents it from being added to this deque
public E remove()
Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque). This method differs frompoll
only in that it throws an exception if this deque is empty. This method is equivalent toremoveFirst()
.
- Returns:
- the head of the queue represented by this deque
- Throws:
NoSuchElementException
- if this deque is empty
public boolean remove(Object o)
Removes the first occurrence of the specified element from this deque. If the deque does not contain the element, it is unchanged. More formally, removes the first element e such that (o==null ? e==null : o.equals(e)) (if such an element exists). Returns true if this deque contained the specified element (or equivalently, if this deque changed as a result of the call). This method is equivalent toremoveFirstOccurrence(Object)
.
- Specified by:
- remove in interface Collection<E>
- Parameters:
o
- element to be removed from this deque, if present
- Returns:
- true if an element was removed as a result of this call
- Throws:
ClassCastException
- if the class of the specified element is incompatible with this deque (optional)NullPointerException
- if the specified element is null and this deque does not permit null elements (optional)
public E removeFirst()
Retrieves and removes the first element of this deque. This method differs frompollFirst
only in that it throws an exception if this deque is empty.
- Returns:
- the head of this deque
- Throws:
NoSuchElementException
- if this deque is empty
public boolean removeFirstOccurrence(Object o)
Removes the first occurrence of the specified element from this deque. If the deque does not contain the element, it is unchanged. More formally, removes the first element e such that (o==null ? e==null : o.equals(e)) (if such an element exists). Returns true if this deque contained the specified element (or equivalently, if this deque changed as a result of the call).
- Parameters:
o
- element to be removed from this deque, if present
- Returns:
- true if an element was removed as a result of this call
- Throws:
ClassCastException
- if the class of the specified element is incompatible with this deque (optional)NullPointerException
- if the specified element is null and this deque does not permit null elements (optional)
public E removeLast()
Retrieves and removes the last element of this deque. This method differs frompollLast
only in that it throws an exception if this deque is empty.
- Returns:
- the tail of this deque
- Throws:
NoSuchElementException
- if this deque is empty
public boolean removeLastOccurrence(Object o)
Removes the last occurrence of the specified element from this deque. If the deque does not contain the element, it is unchanged. More formally, removes the last element e such that (o==null ? e==null : o.equals(e)) (if such an element exists). Returns true if this deque contained the specified element (or equivalently, if this deque changed as a result of the call).
- Parameters:
o
- element to be removed from this deque, if present
- Returns:
- true if an element was removed as a result of this call
- Throws:
ClassCastException
- if the class of the specified element is incompatible with this deque (optional)NullPointerException
- if the specified element is null and this deque does not permit null elements (optional)
public int size()
Returns the number of elements in this deque.
- Specified by:
- size in interface Collection<E>
- Returns:
- the number of elements in this deque
GNU Classpath (0.98) |