DoubleEndedQueueInterface
extends
QueueInterface
in
A linear collection that supports element insertion and removal at both ends.
Most DoubleEndedQueueInterface implementations place no fixed limits on the
number of elements they may contain, but this interface supports
capacity-restricted double-ended queues as well as those with no fixed size
limit.
This interface defines methods to access the elements at both ends of the
double-ended queue. Methods are provided to insert, remove, and examine the
element. Each of these methods exists in two forms: one throws an exception
if the operation fails, the other returns a special value (either null or
false, depending on the operation). The latter form of the insert operation
is designed specifically for use with capacity-restricted implementations; in
most implementations, insert operations cannot fail.
The twelve methods described above are summarized in the following table:
| First Element (Head) | Last Element (Tail) | |||
|---|---|---|---|---|
| Throws exception | Special value | Throws exception | Special value | |
| Insert | addFirst() |
offerFirst() |
addLast() |
offerLast() |
| Remove | removeFirst() |
pollFirst() |
removeLast() |
pollLast() |
| Examine | firstElement() |
peekFirst() |
lastElement() |
peekLast() |
This interface extends the QueueInterface. When a double-ended queue is
used as a queue, FIFO (first-in-first-out) behavior results. Elements are
added at the end of the double-ended queue and removed from the beginning.
The methods inherited from the QueueInterface are precisely equivalent to
DoubleEndedQueueInterface methods as indicated in the following table:
| QueueInterface Method | DoubleEndedQueueInterface Method |
|---|---|
add() |
addLast() |
offer() |
offerLast() |
remove() |
removeFirst() |
poll() |
pollFirst() |
element() |
firstElement() |
peek() |
peekFirst() |
Double-ended queues can also be used as LIFO (last-in-first-out) stacks. When
a double-ended queue is used as a stack, elements are pushed and popped from
the beginning of the double-ended queue. Stack concepts are precisely
equivalent to DoubleEndedQueueInterface methods as indicated in the table
below:
| Stack concept | DoubleEndedQueueInterface Method |
|---|---|
| push | addFirst() |
| pop | removeFirst() |
| peek | peekFirst() |
Note that the peek() method works equally well when a double-ended queue is
used as a queue or a stack; in either case, elements are drawn from the
beginning of the double-ended queue.
While DoubleEndedQueueInterface implementations are not strictly required
to prohibit the insertion of null elements, they are strongly encouraged to
do so. Users of any DoubleEndedQueueInterface 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 double-ended queue is
empty.
Tags
Table of Contents
- add() : bool
- Ensures that this queue contains the specified element (optional operation).
- addFirst() : bool
- Inserts the specified element at the front of this queue if it is possible to do so immediately without violating capacity restrictions.
- addLast() : bool
- Inserts the specified element at the end of this queue if it is possible to do so immediately without violating capacity restrictions.
- clear() : void
- Removes all items from this array.
- element() : T
- Retrieves, but does not remove, the head of this queue.
- firstElement() : T
- Retrieves, but does not remove, the head of this queue.
- getType() : string
- Returns the type associated with this queue.
- isEmpty() : bool
- Returns `true` if this array is empty.
- lastElement() : T
- Retrieves, but does not remove, the tail of this queue.
- offer() : bool
- Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions.
- offerFirst() : bool
- Inserts the specified element at the front of this queue if it is possible to do so immediately without violating capacity restrictions.
- offerLast() : bool
- Inserts the specified element at the end of this queue if it is possible to do so immediately without violating capacity restrictions.
- peek() : T|null
- Retrieves, but does not remove, the head of this queue, or returns `null` if this queue is empty.
- peekFirst() : T|null
- Retrieves, but does not remove, the head of this queue, or returns `null` if this queue is empty.
- peekLast() : T|null
- Retrieves, but does not remove, the tail of this queue, or returns `null` if this queue is empty.
- poll() : T|null
- Retrieves and removes the head of this queue, or returns `null` if this queue is empty.
- pollFirst() : T|null
- Retrieves and removes the head of this queue, or returns `null` if this queue is empty.
- pollLast() : T|null
- Retrieves and removes the tail of this queue, or returns `null` if this queue is empty.
- remove() : T
- Retrieves and removes the head of this queue.
- removeFirst() : T
- Retrieves and removes the head of this queue.
- removeLast() : T
- Retrieves and removes the tail of this queue.
- toArray() : array<array-key, T>
- Returns a native PHP array representation of this array object.
Methods
add()
Ensures that this queue contains the specified element (optional operation).
public
add(T $element) : bool
Returns true if this queue changed as a result of the call. (Returns
false if this queue does not permit duplicates and already contains the
specified element.)
Queues that support this operation may place limitations on what elements
may be added to this queue. In particular, some queues will refuse to add
null elements, and others will impose restrictions on the type of
elements that may be added. Queue classes should clearly specify in their
documentation any restrictions on what elements may be added.
If a queue refuses to add a particular element for any reason other than
that it already contains the element, it must throw an exception (rather
than returning false). This preserves the invariant that a queue always
contains the specified element after this call returns.
Parameters
- $element : T
-
The element to add to this queue.
Tags
Return values
bool —true if this queue changed as a result of the call.
addFirst()
Inserts the specified element at the front of this queue if it is possible to do so immediately without violating capacity restrictions.
public
addFirst(T $element) : bool
When using a capacity-restricted double-ended queue, it is generally
preferable to use the offerFirst() method.
Parameters
- $element : T
-
The element to add to the front of this queue.
Tags
Return values
bool —true if this queue changed as a result of the call.
addLast()
Inserts the specified element at the end of this queue if it is possible to do so immediately without violating capacity restrictions.
public
addLast(T $element) : bool
When using a capacity-restricted double-ended queue, it is generally
preferable to use the offerLast() method.
This method is equivalent to add().
Parameters
- $element : T
-
The element to add to the end of this queue.
Tags
Return values
bool —true if this queue changed as a result of the call.
clear()
Removes all items from this array.
public
clear() : void
Return values
void —element()
Retrieves, but does not remove, the head of this queue.
public
element() : T
This method differs from peek() only in that it throws an exception if
this queue is empty.
Tags
Return values
T —the head of this queue.
firstElement()
Retrieves, but does not remove, the head of this queue.
public
firstElement() : T
This method differs from peekFirst() only in that it throws an
exception if this queue is empty.
Tags
Return values
T —the head of this queue.
getType()
Returns the type associated with this queue.
public
getType() : string
Return values
string —isEmpty()
Returns `true` if this array is empty.
public
isEmpty() : bool
Return values
bool —lastElement()
Retrieves, but does not remove, the tail of this queue.
public
lastElement() : T
This method differs from peekLast() only in that it throws an exception
if this queue is empty.
Tags
Return values
T —the tail of this queue.
offer()
Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions.
public
offer(T $element) : bool
When using a capacity-restricted queue, this method is generally
preferable to add(), which can fail to insert an element only by
throwing an exception.
Parameters
- $element : T
-
The element to add to this queue.
Tags
Return values
bool —true if the element was added to this queue, else false.
offerFirst()
Inserts the specified element at the front of this queue if it is possible to do so immediately without violating capacity restrictions.
public
offerFirst(T $element) : bool
When using a capacity-restricted queue, this method is generally
preferable to addFirst(), which can fail to insert an element only by
throwing an exception.
Parameters
- $element : T
-
The element to add to the front of this queue.
Return values
bool —true if the element was added to this queue, else false.
offerLast()
Inserts the specified element at the end of this queue if it is possible to do so immediately without violating capacity restrictions.
public
offerLast(T $element) : bool
When using a capacity-restricted queue, this method is generally
preferable to addLast() which can fail to insert an element only by
throwing an exception.
Parameters
- $element : T
-
The element to add to the end of this queue.
Return values
bool —true if the element was added to this queue, else false.
peek()
Retrieves, but does not remove, the head of this queue, or returns `null` if this queue is empty.
public
peek() : T|null
Tags
Return values
T|null —the head of this queue, or null if this queue is empty.
peekFirst()
Retrieves, but does not remove, the head of this queue, or returns `null` if this queue is empty.
public
peekFirst() : T|null
Return values
T|null —the head of this queue, or null if this queue is empty.
peekLast()
Retrieves, but does not remove, the tail of this queue, or returns `null` if this queue is empty.
public
peekLast() : T|null
Return values
T|null —the tail of this queue, or null if this queue is empty.
poll()
Retrieves and removes the head of this queue, or returns `null` if this queue is empty.
public
poll() : T|null
Tags
Return values
T|null —the head of this queue, or null if this queue is empty.
pollFirst()
Retrieves and removes the head of this queue, or returns `null` if this queue is empty.
public
pollFirst() : T|null
Return values
T|null —the head of this queue, or null if this queue is empty.
pollLast()
Retrieves and removes the tail of this queue, or returns `null` if this queue is empty.
public
pollLast() : T|null
Return values
T|null —the tail of this queue, or null if this queue is empty.
remove()
Retrieves and removes the head of this queue.
public
remove() : T
This method differs from poll() only in that it throws an exception if
this queue is empty.
Tags
Return values
T —the head of this queue.
removeFirst()
Retrieves and removes the head of this queue.
public
removeFirst() : T
This method differs from pollFirst() only in that it throws an
exception if this queue is empty.
Tags
Return values
T —the first element in this queue.
removeLast()
Retrieves and removes the tail of this queue.
public
removeLast() : T
This method differs from pollLast() only in that it throws an exception
if this queue is empty.
Tags
Return values
T —the last element in this queue.
toArray()
Returns a native PHP array representation of this array object.
public
toArray() : array<array-key, T>