DoubleEndedQueueInterface
interface DoubleEndedQueueInterface implements QueueInterface (View source)
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.
Methods
Ensures that this queue contains the specified element (optional operation).
Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions.
Retrieves, but does not remove, the head of this queue, or returns null
if this queue is empty.
Retrieves and removes the head of this queue, or returns null
if this queue is empty.
Inserts the specified element at the front of this queue if it is possible to do so immediately without violating capacity restrictions.
Inserts the specified element at the end of this queue if it is possible to do so immediately without violating capacity restrictions.
Inserts the specified element at the front of this queue if it is possible to do so immediately without violating capacity restrictions.
Inserts the specified element at the end of this queue if it is possible to do so immediately without violating capacity restrictions.
Retrieves and removes the head of this queue.
Retrieves and removes the tail of this queue.
Retrieves and removes the head of this queue, or returns null if this
queue is empty.
Retrieves and removes the tail of this queue, or returns null if this
queue is empty.
Retrieves, but does not remove, the head of this queue.
Retrieves, but does not remove, the tail of this queue.
Retrieves, but does not remove, the head of this queue, or returns null
if this queue is empty.
Retrieves, but does not remove, the tail of this queue, or returns null
if this queue is empty.
Details
in ArrayInterface at line 29
void
clear()
Removes all items from this array.
in ArrayInterface at line 36
array
toArray()
Returns a native PHP array representation of this array object.
in ArrayInterface at line 43
bool
isEmpty()
Returns true if this array is empty.
in QueueInterface at line 128
bool
add(mixed $element)
Ensures that this queue contains the specified element (optional operation).
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.
in QueueInterface at line 142
mixed
element()
Retrieves, but does not remove, the head of this queue.
This method differs from peek() only in that it throws an exception if
this queue is empty.
in QueueInterface at line 158
bool
offer(mixed $element)
Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions.
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.
in QueueInterface at line 168
mixed|null
peek()
Retrieves, but does not remove, the head of this queue, or returns null
if this queue is empty.
in QueueInterface at line 178
mixed|null
poll()
Retrieves and removes the head of this queue, or returns null
if this queue is empty.
in QueueInterface at line 192
mixed
remove()
Retrieves and removes the head of this queue.
This method differs from poll() only in that it throws an exception if
this queue is empty.
in QueueInterface at line 199
string
getType()
Returns the type associated with this queue.
at line 180
bool
addFirst(mixed $element)
Inserts the specified element at the front of this queue if it is possible to do so immediately without violating capacity restrictions.
When using a capacity-restricted double-ended queue, it is generally
preferable to use the offerFirst() method.
at line 200
bool
addLast(mixed $element)
Inserts the specified element at the end of this queue if it is possible to do so immediately without violating capacity restrictions.
When using a capacity-restricted double-ended queue, it is generally
preferable to use the offerLast() method.
This method is equivalent to add().
at line 214
bool
offerFirst(mixed $element)
Inserts the specified element at the front of this queue if it is possible to do so immediately without violating capacity restrictions.
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.
at line 228
bool
offerLast(mixed $element)
Inserts the specified element at the end of this queue if it is possible to do so immediately without violating capacity restrictions.
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.
at line 240
mixed
removeFirst()
Retrieves and removes the head of this queue.
This method differs from pollFirst() only in that it throws an
exception if this queue is empty.
at line 252
mixed
removeLast()
Retrieves and removes the tail of this queue.
This method differs from pollLast() only in that it throws an exception
if this queue is empty.
at line 260
mixed|null
pollFirst()
Retrieves and removes the head of this queue, or returns null if this
queue is empty.
at line 268
mixed|null
pollLast()
Retrieves and removes the tail of this queue, or returns null if this
queue is empty.
at line 280
mixed
firstElement()
Retrieves, but does not remove, the head of this queue.
This method differs from peekFirst() only in that it throws an
exception if this queue is empty.
at line 292
mixed
lastElement()
Retrieves, but does not remove, the tail of this queue.
This method differs from peekLast() only in that it throws an exception
if this queue is empty.
at line 300
mixed|null
peekFirst()
Retrieves, but does not remove, the head of this queue, or returns null
if this queue is empty.
at line 308
mixed|null
peekLast()
Retrieves, but does not remove, the tail of this queue, or returns null
if this queue is empty.