Documentation

QueueInterface extends ArrayInterface
in

A queue is a collection in which the entities in the collection are kept in order.

The principal operations on the queue are the addition of entities to the end (tail), also known as enqueue, and removal of entities from the front (head), also known as dequeue. This makes the queue a first-in-first-out (FIFO) data structure.

Besides basic array operations, queues provide additional insertion, extraction, and inspection operations. 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 QueueInterface implementations; in most implementations, insert operations cannot fail.

Summary of QueueInterface methods
Throws exception Returns special value
Insert add() offer()
Remove remove() poll()
Examine element() peek()

Queues typically, but do not necessarily, order elements in a FIFO (first-in-first-out) manner. Among the exceptions are priority queues, which order elements according to a supplied comparator, or the elements' natural ordering, and LIFO queues (or stacks) which order the elements LIFO (last-in-first-out). Whatever the ordering used, the head of the queue is that element which would be removed by a call to remove() or poll(). In a FIFO queue, all new elements are inserted at the tail of the queue. Other kinds of queues may use different placement rules. Every QueueInterface implementation must specify its ordering properties.

The offer() method inserts an element if possible, otherwise returning false. This differs from the add() method, which can fail to add an element only by throwing an unchecked exception. The offer() method is designed for use when failure is a normal, rather than exceptional occurrence, for example, in fixed-capacity (or "bounded") queues.

The remove() and poll() methods remove and return the head of the queue. Exactly which element is removed from the queue is a function of the queue's ordering policy, which differs from implementation to implementation. The remove() and poll() methods differ only in their behavior when the queue is empty: the remove() method throws an exception, while the poll() method returns null.

The element() and peek() methods return, but do not remove, the head of the queue.

QueueInterface implementations generally do not allow insertion of null elements, although some implementations do not prohibit insertion of null. Even in the implementations that permit it, null should not be inserted into a queue, as null is also used as a special return value by the poll() method to indicate that the queue contains no elements.

Tags
template

T

extends

ArrayInterface<T>

Table of Contents

add()  : bool
Ensures that this queue contains the specified element (optional operation).
clear()  : void
Removes all items from this array.
element()  : 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.
offer()  : bool
Inserts the specified element into 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.
poll()  : T|null
Retrieves and removes the head of this queue, or returns `null` if this queue is empty.
remove()  : T
Retrieves and removes the head 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
see
self::offer()
throws
RuntimeException

if a queue refuses to add a particular element for any reason other than that it already contains the element. Implementations should use a more-specific exception that extends \RuntimeException.

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
see
self::peek()
throws
NoSuchElementException

if this queue is empty.

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 —

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
see
self::add()
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
see
self::element()
Return values
T|null —

the head 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
see
self::remove()
Return values
T|null —

the head 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
see
self::poll()
throws
NoSuchElementException

if this queue is empty.

Return values
T —

the head of this queue.

toArray()

Returns a native PHP array representation of this array object.

public toArray() : array<array-key, T>
Return values
array<array-key, T> —

Search results