The Deque class

(No version information available, might only be in Git)

Introduction

A Deque (pronounced “deck”) is a sequence of values in a contiguous buffer that grows and shrinks automatically. The name is a common abbreviation of “double-ended queue” and is used internally by Ds\Queue.

Two pointers are used to keep track of a head and a tail. The pointers can “wrap around” the end of the buffer, which avoids the need to move other values around to make room. This makes shift and unshift very fast —  something a Ds\Vector can’t compete with.

Accessing a value by index requires a translation between the index and its corresponding position in the buffer: ((head + position) % capacity).

Strengths

  • Supports array syntax (square brackets).
  • Uses less overall memory than an array for the same number of values.
  • Automatically frees allocated memory when its size drops low enough.
  • get(), set(), push(), pop(), shift(), and unshift() are all O(1).

Weaknesses

  • Capacity must be a power of 2.
  • insert() and remove() are O(n).

Class synopsis

Ds\Deque implements Ds\Sequence {
/* Constants */
const int MIN_CAPACITY = 8 ;
/* Methods */
public allocate ( int $capacity ) : void
public apply ( callable $callback ) : void
public capacity ( void ) : int
public clear ( void ) : void
public contains ([ mixed $...values ] ) : bool
public copy ( void ) : Ds\Deque
public filter ([ callable $callback ] ) : Ds\Deque
public find ( mixed $value ) : mixed
public first ( void ) : mixed
public get ( int $index ) : mixed
public insert ( int $index [, mixed $...values ] ) : void
public isEmpty ( void ) : bool
public join ([ string $glue ] ) : string
public last ( void ) : mixed
public map ( callable $callback ) : Ds\Deque
public merge ( mixed $values ) : Ds\Deque
public pop ( void ) : mixed
public push ([ mixed $...values ] ) : void
public reduce ( callable $callback [, mixed $initial ] ) : mixed
public remove ( int $index ) : mixed
public reverse ( void ) : void
public reversed ( void ) : Ds\Deque
public rotate ( int $rotations ) : void
public set ( int $index , mixed $value ) : void
public shift ( void ) : mixed
public slice ( int $index [, int $length ] ) : Ds\Deque
public sort ([ callable $comparator ] ) : void
public sorted ([ callable $comparator ] ) : Ds\Deque
public sum ( void ) : number
public toArray ( void ) : array
public unshift ([ mixed $values ] ) : void
}

Predefined Constants

Ds\Deque::MIN_CAPACITY

Table of Contents