Book/ds-Phpdoc专题

Data Structures

简介
安装／配置
- 需求
- 安装
预定义常量
范例
Collection — The Collection interface
- Ds\Collection::clear — Removes all values
- Ds\Collection::copy — Returns a shallow copy of the collection
- Ds\Collection::isEmpty — Returns whether the collection is empty
- Ds\Collection::toArray — Converts the collection to an array
Hashable — The Hashable interface
- Ds\Hashable::equals — Determines whether an object is equal to the current instance
- Ds\Hashable::hash — Returns a scalar value to be used as a hash value
Sequence — The Sequence interface
- Ds\Sequence::allocate — Allocates enough memory for a required capacity
- Ds\Sequence::apply — Updates all values by applying a callback function to each value
- Ds\Sequence::capacity — Returns the current capacity
- Ds\Sequence::contains — Determines if the sequence contains given values
- Ds\Sequence::filter — Creates a new sequence using a callable to determine which values to include
- Ds\Sequence::find — Attempts to find a value's index
- Ds\Sequence::first — Returns the first value in the sequence
- Ds\Sequence::get — Returns the value at a given index
- Ds\Sequence::insert — Inserts values at a given index
- Ds\Sequence::join — Joins all values together as a string
- Ds\Sequence::last — Returns the last value
- Ds\Sequence::map — Returns the result of applying a callback to each value
- Ds\Sequence::merge — Returns the result of adding all given values to the sequence
- Ds\Sequence::pop — Removes and returns the last value
- Ds\Sequence::push — Adds values to the end of the sequence
- Ds\Sequence::reduce — Reduces the sequence to a single value using a callback function
- Ds\Sequence::remove — Removes and returns a value by index
- Ds\Sequence::reverse — Reverses the sequence in-place
- Ds\Sequence::reversed — Returns a reversed copy
- Ds\Sequence::rotate — Rotates the sequence by a given number of rotations
- Ds\Sequence::set — Updates a value at a given index
- Ds\Sequence::shift — Removes and returns the first value
- Ds\Sequence::slice — Returns a sub-sequence of a given range
- Ds\Sequence::sort — Sorts the sequence in-place
- Ds\Sequence::sorted — Returns a sorted copy
- Ds\Sequence::sum — Returns the sum of all values in the sequence
- Ds\Sequence::unshift — Adds values to the front of the sequence
Vector — The Vector class
- Ds\Vector::allocate — Allocates enough memory for a required capacity
- Ds\Vector::apply — Updates all values by applying a callback function to each value
- Ds\Vector::capacity — Returns the current capacity
- Ds\Vector::clear — Removes all values
- Ds\Vector::__construct — Creates a new instance
- Ds\Vector::contains — Determines if the vector contains given values
- Ds\Vector::copy — Returns a shallow copy of the vector
- Ds\Vector::count — Returns the number of values in the collection
- Ds\Vector::filter — Creates a new vector using a callable to determine which values to include
- Ds\Vector::find — Attempts to find a value's index
- Ds\Vector::first — Returns the first value in the vector
- Ds\Vector::get — Returns the value at a given index
- Ds\Vector::insert — Inserts values at a given index
- Ds\Vector::isEmpty — Returns whether the vector is empty
- Ds\Vector::join — Joins all values together as a string
- Ds\Vector::jsonSerialize — Returns a representation that can be converted to JSON
- Ds\Vector::last — Returns the last value
- Ds\Vector::map — Returns the result of applying a callback to each value
- Ds\Vector::merge — Returns the result of adding all given values to the vector
- Ds\Vector::pop — Removes and returns the last value
- Ds\Vector::push — Adds values to the end of the vector
- Ds\Vector::reduce — Reduces the vector to a single value using a callback function
- Ds\Vector::remove — Removes and returns a value by index
- Ds\Vector::reverse — Reverses the vector in-place
- Ds\Vector::reversed — Returns a reversed copy
- Ds\Vector::rotate — Rotates the vector by a given number of rotations
- Ds\Vector::set — Updates a value at a given index
- Ds\Vector::shift — Removes and returns the first value
- Ds\Vector::slice — Returns a sub-vector of a given range
- Ds\Vector::sort — Sorts the vector in-place
- Ds\Vector::sorted — Returns a sorted copy
- Ds\Vector::sum — Returns the sum of all values in the vector
- Ds\Vector::toArray — Converts the vector to an array
- Ds\Vector::unshift — Adds values to the front of the vector
Deque — The Deque class
- Ds\Deque::allocate — Allocates enough memory for a required capacity
- Ds\Deque::apply — Updates all values by applying a callback function to each value
- Ds\Deque::capacity — Returns the current capacity
- Ds\Deque::clear — Removes all values from the deque
- Ds\Deque::__construct — Creates a new instance
- Ds\Deque::contains — Determines if the deque contains given values
- Ds\Deque::copy — Returns a shallow copy of the deque
- Ds\Deque::count — Returns the number of values in the collection
- Ds\Deque::filter — Creates a new deque using a callable to determine which values to include
- Ds\Deque::find — Attempts to find a value's index
- Ds\Deque::first — Returns the first value in the deque
- Ds\Deque::get — Returns the value at a given index
- Ds\Deque::insert — Inserts values at a given index
- Ds\Deque::isEmpty — Returns whether the deque is empty
- Ds\Deque::join — Joins all values together as a string
- Ds\Deque::jsonSerialize — Returns a representation that can be converted to JSON
- Ds\Deque::last — Returns the last value
- Ds\Deque::map — Returns the result of applying a callback to each value
- Ds\Deque::merge — Returns the result of adding all given values to the deque
- Ds\Deque::pop — Removes and returns the last value
- Ds\Deque::push — Adds values to the end of the deque
- Ds\Deque::reduce — Reduces the deque to a single value using a callback function
- Ds\Deque::remove — Removes and returns a value by index
- Ds\Deque::reverse — Reverses the deque in-place
- Ds\Deque::reversed — Returns a reversed copy
- Ds\Deque::rotate — Rotates the deque by a given number of rotations
- Ds\Deque::set — Updates a value at a given index
- Ds\Deque::shift — Removes and returns the first value
- Ds\Deque::slice — Returns a sub-deque of a given range
- Ds\Deque::sort — Sorts the deque in-place
- Ds\Deque::sorted — Returns a sorted copy
- Ds\Deque::sum — Returns the sum of all values in the deque
- Ds\Deque::toArray — Converts the deque to an array
- Ds\Deque::unshift — Adds values to the front of the deque
Map — The Map class
- Ds\Map::allocate — Allocates enough memory for a required capacity
- Ds\Map::apply — Updates all values by applying a callback function to each value
- Ds\Map::capacity — Returns the current capacity
- Ds\Map::clear — Removes all values
- Ds\Map::__construct — Creates a new instance
- Ds\Map::copy — Returns a shallow copy of the map
- Ds\Map::count — Returns the number of values in the map
- Ds\Map::diff — Creates a new map using keys that aren't in another map
- Ds\Map::filter — Creates a new map using a callable to determine which pairs to include
- Ds\Map::first — Returns the first pair in the map
- Ds\Map::get — Returns the value for a given key
- Ds\Map::hasKey — Determines whether the map contains a given key
- Ds\Map::hasValue — Determines whether the map contains a given value
- Ds\Map::intersect — Creates a new map by intersecting keys with another map
- Ds\Map::isEmpty — Returns whether the map is empty
- Ds\Map::jsonSerialize — Returns a representation that can be converted to JSON
- Ds\Map::keys — Returns a set of the map's keys
- Ds\Map::ksort — Sorts the map in-place by key
- Ds\Map::ksorted — Returns a copy, sorted by key
- Ds\Map::last — Returns the last pair of the map
- Ds\Map::map — Returns the result of applying a callback to each value
- Ds\Map::merge — Returns the result of adding all given associations
- Ds\Map::pairs — Returns a sequence containing all the pairs of the map
- Ds\Map::put — Associates a key with a value
- Ds\Map::putAll — Associates all key-value pairs of a traversable object or array
- Ds\Map::reduce — Reduces the map to a single value using a callback function
- Ds\Map::remove — Removes and returns a value by key
- Ds\Map::reverse — Reverses the map in-place
- Ds\Map::reversed — Returns a reversed copy
- Ds\Map::skip — Returns the pair at a given positional index
- Ds\Map::slice — Returns a subset of the map defined by a starting index and length
- Ds\Map::sort — Sorts the map in-place by value
- Ds\Map::sorted — Returns a copy, sorted by value
- Ds\Map::sum — Returns the sum of all values in the map
- Ds\Map::toArray — Converts the map to an array
- Ds\Map::union — Creates a new map using values from the current instance and another map
- Ds\Map::values — Returns a sequence of the map's values
- Ds\Map::xor — Creates a new map using keys of either the current instance or of another map, but not of both
Pair — The Pair class
- Ds\Pair::clear — Removes all values
- Ds\Pair::__construct — Creates a new instance
- Ds\Pair::copy — Returns a shallow copy of the pair
- Ds\Pair::isEmpty — Returns whether the pair is empty
- Ds\Pair::jsonSerialize — Returns a representation that can be converted to JSON
- Ds\Pair::toArray — Converts the pair to an array
Set — The Set class
- Ds\Set::add — Adds values to the set
- Ds\Set::allocate — Allocates enough memory for a required capacity
- Ds\Set::capacity — Returns the current capacity
- Ds\Set::clear — Removes all values
- Ds\Set::__construct — Creates a new instance
- Ds\Set::contains — Determines if the set contains all values
- Ds\Set::copy — Returns a shallow copy of the set
- Ds\Set::count — Returns the number of values in the set
- Ds\Set::diff — Creates a new set using values that aren't in another set
- Ds\Set::filter — Creates a new set using a callable to determine which values to include
- Ds\Set::first — Returns the first value in the set
- Ds\Set::get — Returns the value at a given index
- Ds\Set::intersect — Creates a new set by intersecting values with another set
- Ds\Set::isEmpty — Returns whether the set is empty
- Ds\Set::join — Joins all values together as a string
- Ds\Set::jsonSerialize — Returns a representation that can be converted to JSON
- Ds\Set::last — Returns the last value in the set
- Ds\Set::merge — Returns the result of adding all given values to the set
- Ds\Set::reduce — Reduces the set to a single value using a callback function
- Ds\Set::remove — Removes all given values from the set
- Ds\Set::reverse — Reverses the set in-place
- Ds\Set::reversed — Returns a reversed copy
- Ds\Set::slice — Returns a sub-set of a given range
- Ds\Set::sort — Sorts the set in-place
- Ds\Set::sorted — Returns a sorted copy
- Ds\Set::sum — Returns the sum of all values in the set
- Ds\Set::toArray — Converts the set to an array
- Ds\Set::union — Creates a new set using values from the current instance and another set
- Ds\Set::xor — Creates a new set using values in either the current instance or in another set, but not in both
Stack — The Stack class
- Ds\Stack::allocate — Allocates enough memory for a required capacity
- Ds\Stack::capacity — Returns the current capacity
- Ds\Stack::clear — Removes all values
- Ds\Stack::__construct — Creates a new instance
- Ds\Stack::copy — Returns a shallow copy of the stack
- Ds\Stack::count — Returns the number of values in the stack
- Ds\Stack::isEmpty — Returns whether the stack is empty
- Ds\Stack::jsonSerialize — Returns a representation that can be converted to JSON
- Ds\Stack::peek — Returns the value at the top of the stack
- Ds\Stack::pop — Removes and returns the value at the top of the stack
- Ds\Stack::push — Pushes values onto the stack
- Ds\Stack::toArray — Converts the stack to an array
Queue — The Queue class
- Ds\Queue::allocate — Allocates enough memory for a required capacity
- Ds\Queue::capacity — Returns the current capacity
- Ds\Queue::clear — Removes all values
- Ds\Queue::__construct — Creates a new instance
- Ds\Queue::copy — Returns a shallow copy of the queue
- Ds\Queue::count — Returns the number of values in the queue
- Ds\Queue::isEmpty — Returns whether the queue is empty
- Ds\Queue::jsonSerialize — Returns a representation that can be converted to JSON
- Ds\Queue::peek — Returns the value at the front of the queue
- Ds\Queue::pop — Removes and returns the value at the front of the queue
- Ds\Queue::push — Pushes values into the queue
- Ds\Queue::toArray — Converts the queue to an array
PriorityQueue — The PriorityQueue class
- Ds\PriorityQueue::allocate — Allocates enough memory for a required capacity
- Ds\PriorityQueue::capacity — Returns the current capacity
- Ds\PriorityQueue::clear — Removes all values
- Ds\PriorityQueue::__construct — Creates a new instance
- Ds\PriorityQueue::copy — Returns a shallow copy of the queue
- Ds\PriorityQueue::count — Returns the number of values in the queue
- Ds\PriorityQueue::isEmpty — Returns whether the queue is empty
- Ds\PriorityQueue::jsonSerialize — Returns a representation that can be converted to JSON
- Ds\PriorityQueue::peek — Returns the value at the front of the queue
- Ds\PriorityQueue::pop — Removes and returns the value with the highest priority
- Ds\PriorityQueue::push — Pushes values into the queue
- Ds\PriorityQueue::toArray — Converts the queue to an array

简介

Collection is the base interface which covers functionality common to all the data structures in this library. It guarantees that all structures are traversable, countable, and can be converted to json using json_encode.

接口摘要

Ds\Collection

class Ds\Collection implements Traversable , Countable , JsonSerializable {

/* 方法 */

abstract public void clear ( void )

abstract public Ds\Collection copy ( void )

abstract public bool isEmpty ( void )

abstract public array toArray ( void )

}

Ds\Collection::clear

Removes all values

说明

abstract public void Ds\Collection::clear ( void )

Removes all values from the collection.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Collection::clear example

<?php
$collection = new \Ds\Vector([1, 2, 3]);
print_r($collection);

$collection->clear();
print_r($collection);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
)

Ds\Collection::copy

Returns a shallow copy of the collection

说明

abstract public Ds\Collection Ds\Collection::copy ( void )

Returns a shallow copy of the collection.

参数

此函数没有参数。

返回值

Returns a shallow copy of the collection.

范例

示例 #1 Ds\Collection::copy example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = $a->copy();

$b->push(4);

print_r($a);
print_r($b);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

Ds\Collection::isEmpty

Returns whether the collection is empty

说明

abstract public bool Ds\Collection::isEmpty ( void )

Returns whether the collection is empty.

参数

此函数没有参数。

返回值

Returns true if the collection is empty, false otherwise.

范例

示例 #1 Ds\Collection::isEmpty example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = new \Ds\Vector();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

以上例程的输出类似于：

bool(false)
bool(true)

Ds\Collection::toArray

Converts the collection to an array

说明

abstract public array Ds\Collection::toArray ( void )

Converts the collection to an array.

Note:

Casting to an array is not supported yet.

参数

此函数没有参数。

返回值

An array containing all the values in the same order as the collection.

范例

示例 #1 Ds\Collection::toArray example

<?php
$collection = new \Ds\Vector([1, 2, 3]);

var_dump($collection->toArray());
?>

以上例程的输出类似于：

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

简介

Hashable is an interface which allows objects to be used as keys. It’s an alternative to spl_object_hash, which determines an object’s hash based on its handle: this means that two objects that are considered equal by an implicit definition would not treated as equal because they are not the same instance.

hash is used to return a scalar value to be used as the object's hash value, which determines where it goes in the hash table. While this value does not have to be unique, objects which are equal must have the same hash value.

equals is used to determine if two objects are equal. It's guaranteed that the comparing object will be an instance of the same class as the subject.

接口摘要

Ds\Hashable

class Ds\Hashable {

/* 方法 */

abstract public bool equals ( object $obj )

abstract public mixed hash ( void )

}

Ds\Hashable::equals

Determines whether an object is equal to the current instance

说明

abstract public bool Ds\Hashable::equals ( object $obj )

Determines whether another object is equal to the current instance.

This method allows objects to be used as keys in structures such as Ds\Map and Ds\Set, or any other lookup structure that honors this interface.

Note:

It's guaranteed that obj is an instance of the same class.

Caution

It's important that objects which are equal also have the same hash value. See Ds\Hashable::hash.

参数

obj
The object to compare the current instance to, which is always an instance of the same class.

返回值

true if equal, false otherwise.

Ds\Hashable::hash

Returns a scalar value to be used as a hash value

说明

abstract public mixed Ds\Hashable::hash ( void )

Returns a scalar value to be used as the hash value of the objects.

While the hash value does not define equality, all objects that are equal according to Ds\Hashable::equals must have the same hash value. Hash values of equal objects don't have to be unique, for example you could just return true for all objects and nothing would break - the only implication would be that hash tables then turn into linked lists because all your objects will be hashed to the same bucket. It's therefore very important that you pick a good hash value, such as an ID or email address.

This method allows objects to be used as keys in structures such as Ds\Map and Ds\Set, or any other lookup structure that honors this interface.

Caution

Do not pick a value that might change within the object, such as a public property. Hash table lookups would fail because the hash has changed.

Caution

All objects that are equal must have the same hash value.

参数

此函数没有参数。

返回值

A scalar value to be used as this object's hash value.

范例

示例 #1 Ds\Hashable::hash example

<?php
class HashableObject implements \Ds\Hashable
{
    private $name;
    private $email;

    public function __construct($name, $email)
    {
        $this->name  = $name;
        $this->email = $email;
    }

    /**
     * Should return the same value for all equal objects, but doesn't have to
     * be unique. This value will not be used to determine equality.
     */
    public function hash()
    {
        return $this->email;
    }

    /**
     * This determines equality, usually during a hash table lookup to determine
     * if the bucket's key matches the lookup key. The hash has to be equal if
     * the objects are equal, otherwise this determination wouldn't be reached.
     */
    public function equals($obj): bool
    {
        return $this->name  === $obj->name
            && $this->email === $obj->email;
    }
}
?>

简介

A Sequence describes the behaviour of values arranged in a single, linear dimension. Some languages refer to this as a "List". It’s similar to an array that uses incremental integer keys, with the exception of a few characteristics:

Values will always be indexed as [0, 1, 2, …, size - 1].
Only allowed to access values by index in the range [0, size - 1].

Use cases:

Wherever you would use an array as a list (not concerned with keys).
A more efficient alternative to SplDoublyLinkedList and SplFixedArray.

接口摘要

Ds\Sequence

class Ds\Sequence implements Ds\Collection , ArrayAccess {

/* 方法 */

abstract public void allocate ( int $capacity )

abstract public void apply ( callable $callback )

abstract public int capacity ( void )

abstract public bool contains ( mixed $values )

abstract public Ds\Sequence filter ([ callable $callback ] )

abstract public mixed find ( mixed $value )

abstract public mixed first ( void )

abstract public mixed get ( int $index )

abstract public void insert ( int $index , mixed $values )

abstract public string join ([ string $glue ] )

abstract public mixed last ( void )

abstract public Ds\Sequence map ( callable $callback )

abstract public Ds\Sequence merge ( mixed $values )

abstract public mixed pop ( void )

abstract public void push ( mixed $values )

abstract public mixed reduce ( callable $callback [, mixed $initial ] )

abstract public mixed remove ( int $index )

abstract public void reverse ( void )

abstract public Ds\Sequence reversed ( void )

abstract public void rotate ( int $rotations )

abstract public void set ( int $index , mixed $value )

abstract public mixed shift ( void )

abstract public Ds\Sequence slice ( int $index [, int $length ] )

abstract public void sort ([ callable $comparator ] )

abstract public Ds\Sequence sorted ([ callable $comparator ] )

abstract public intfloat sum ( void )

abstract public void unshift ([ mixed $values ] )

}

更新日志

版本	说明
PECL ds 1.3.0	The interface now extends ArrayAccess.

Ds\Sequence::allocate

Allocates enough memory for a required capacity

说明

abstract public void Ds\Sequence::allocate ( int $capacity )

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

参数

capacity
The number of values for which capacity should be allocated.

Note:

Capacity will stay the same if this value is less than or equal to the current capacity.

返回值

没有返回值。

范例

示例 #1 Ds\Sequence::allocate example

<?php
$sequence = new \Ds\Vector();
var_dump($sequence->capacity());

$vector->allocate(100);
var_dump($sequence->capacity());
?>

以上例程的输出类似于：

int(10)
int(100)

Ds\Sequence::apply

Updates all values by applying a callback function to each value

说明

abstract public void Ds\Sequence::apply ( callable $callback )

Updates all values by applying a callback function to each value in the sequence.

参数

callback
mixed callback ( mixed $value )

A callable to apply to each value in the sequence.

The callback should return what the value should be replaced by.

返回值

没有返回值。

范例

示例 #1 Ds\Sequence::apply example

<?php
$sequence = new \Ds\Sequence([1, 2, 3]);
$sequence->apply(function($value) { return $value * 2; });

print_r($sequence);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)

Ds\Sequence::capacity

Returns the current capacity

说明

abstract public int Ds\Sequence::capacity ( void )

Returns the current capacity.

参数

此函数没有参数。

返回值

The current capacity.

范例

示例 #1 Ds\Sequence::capacity example

<?php
$sequence = new \Ds\Vector();
var_dump($sequence->capacity());

$sequence->push(...range(1, 50));
var_dump($sequence->capacity());

$sequence[] = "a";
var_dump($sequence->capacity());
?>

以上例程的输出类似于：

int(10)
int(50)
int(75)

Ds\Sequence::contains

Determines if the sequence contains given values

说明

abstract public bool Ds\Sequence::contains ( mixed $values )

Determines if the sequence contains all values.

参数

values
Values to check.

返回值

false if any of the provided values are not in the sequence, true otherwise.

范例

示例 #1 Ds\Sequence::contains example

<?php
$sequence = new \Ds\Vector(['a', 'b', 'c', 1, 2, 3]);

var_dump($sequence->contains('a'));                // true
var_dump($sequence->contains('a', 'b'));           // true
var_dump($sequence->contains('c', 'd'));           // false

var_dump($sequence->contains(...['c', 'b', 'a'])); // true

// Always strict
var_dump($sequence->contains(1));                  // true
var_dump($sequence->contains('1'));                // false

var_dump($sequece->contains(...[]));               // true
?>

以上例程的输出类似于：

bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(false)
bool(true)

Ds\Sequence::filter

Creates a new sequence using a callable to determine which values to include

说明

abstract public Ds\Sequence Ds\Sequence::filter ([ callable $callback ] )

Creates a new sequence using a callable to determine which values to include.

参数

callback
bool callback ( mixed $value )

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

返回值

A new sequence containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

范例

示例 #1 Ds\Sequence::filter example using callback function

<?php
$sequence = new \Ds\Vector([1, 2, 3, 4, 5]);

var_dump($sequence->filter(function($value) {
    return $value % 2 == 0;
}));
?>

以上例程的输出类似于：

object(Ds\Vector)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

示例 #2 Ds\Sequence::filter example without a callback function

<?php
$sequence = new \Ds\Vector([0, 1, 'a', true, false]);

var_dump($sequence->filter());
?>

以上例程的输出类似于：

object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}

Ds\Sequence::find

Attempts to find a value's index

说明

abstract public mixed Ds\Sequence::find ( mixed $value )

Returns the index of the value, or false if not found.

参数

value
The value to find.

返回值

The index of the value, or false if not found.

Note:

Values will be compared by value and by type.

范例

示例 #1 Ds\Sequence::find example

<?php
$sequence = new \Ds\Vector(["a", 1, true]);

var_dump($sequence->find("a")); // 0
var_dump($sequence->find("b")); // false
var_dump($sequence->find("1")); // false
var_dump($sequence->find(1));   // 1
?>

以上例程的输出类似于：

int(0)
bool(false)
bool(false)
int(1)

Ds\Sequence::first

Returns the first value in the sequence

说明

abstract public mixed Ds\Sequence::first ( void )

Returns the first value in the sequence.

参数

此函数没有参数。

返回值

The first value in the sequence.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Sequence::first example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);
var_dump($sequence->first());
?>

以上例程的输出类似于：

int(1)

Ds\Sequence::get

Returns the value at a given index

说明

abstract public mixed Ds\Sequence::get ( int $index )

Returns the value at a given index.

参数

index
The index to access, starting at 0.

返回值

The value at the requested index.

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Sequence::get example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence->get(0));
var_dump($sequence->get(1));
var_dump($sequence->get(2));
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

示例 #2 Ds\Sequence::get example using array syntax

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence[0]);
var_dump($sequence[1]);
var_dump($sequence[2]);
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

Ds\Sequence::insert

Inserts values at a given index

说明

abstract public void Ds\Sequence::insert ( int $index , mixed $values )

Inserts values into the sequence at a given index.

参数

index
The index at which to insert. 0 <= index <= count

Note:

You can insert at the index equal to the number of values.

values
The value or values to insert.

返回值

没有返回值。

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Sequence::insert example

<?php
$sequence = new \Ds\Vector();

$sequence->insert(0, "e");             // [e]
$sequence->insert(1, "f");             // [e, f]
$sequence->insert(2, "g");             // [e, f, g]
$sequence->insert(0, "a", "b");        // [a, b, e, f, g]
$sequence->insert(2, ...["c", "d"]);   // [a, b, c, d, e, f, g]

var_dump($sequence);
?>

以上例程的输出类似于：

object(Ds\Vector)#1 (7) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
  [3]=>
  string(1) "d"
  [4]=>
  string(1) "e"
  [5]=>
  string(1) "f"
  [6]=>
  string(1) "g"
}

Ds\Sequence::join

Joins all values together as a string

说明

abstract public string Ds\Sequence::join ([ string $glue ] )

Joins all values together as a string using an optional separator between each value.

参数

glue
An optional string to separate each value.

返回值

All values of the sequence joined together as a string.

范例

示例 #1 Ds\Sequence::join example using a separator string

<?php
$sequence = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($sequence->join("|"));
?>

以上例程的输出类似于：

string(11) "a|b|c|1|2|3"

示例 #2 Ds\Sequence::join example without a separator string

<?php
$sequence = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($sequence->join());
?>

以上例程的输出类似于：

string(11) "abc123"

Ds\Sequence::last

Returns the last value

说明

abstract public mixed Ds\Sequence::last ( void )

Returns the last value in the sequence.

参数

此函数没有参数。

返回值

The last value in the sequence.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Sequence::last example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);
var_dump($sequence->last());
?>

以上例程的输出类似于：

int(3)

Ds\Sequence::map

Returns the result of applying a callback to each value

说明

abstract public Ds\Sequence Ds\Sequence::map ( callable $callback )

Returns the result of applying a callback function to each value in the sequence.

参数

callback
mixed callback ( mixed $value )

A callable to apply to each value in the sequence.

The callable should return what the new value will be in the new sequence.

返回值

The result of applying a callback to each value in the sequence.

Note:

The values of the current instance won't be affected.

范例

示例 #1 Ds\Sequence::map example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

print_r($sequence->map(function($value) { return $value * 2; }));
print_r($sequence);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)

Ds\Sequence::merge

Returns the result of adding all given values to the sequence

说明

abstract public Ds\Sequence Ds\Sequence::merge ( mixed $values )

Returns the result of adding all given values to the sequence.

参数

values
A traversable object or an array.

返回值

The result of adding all given values to the sequence, effectively the same as adding the values to a copy, then returning that copy.

Note:

The current instance won't be affected.

范例

示例 #1 Ds\Sequence::merge example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

var_dump($sequence->merge([4, 5, 6]));
var_dump($sequence);
?>

以上例程的输出类似于：

object(Ds\Vector)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
  [5]=>
  int(6)
}
object(Ds\Vector)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Sequence::pop

Removes and returns the last value

说明

abstract public mixed Ds\Sequence::pop ( void )

Removes and returns the last value.

参数

此函数没有参数。

返回值

The removed last value.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Sequence::pop example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

var_dump($sequence->pop());
var_dump($sequence->pop());
var_dump($sequence->pop());
?>

以上例程的输出类似于：

int(3)
int(2)
int(1)

Ds\Sequence::push

Adds values to the end of the sequence

说明

abstract public void Ds\Sequence::push ( mixed $values )

Adds values to the end of the sequence.

参数

values
The values to add.

返回值

没有返回值。

范例

示例 #1 Ds\Sequence::push example

<?php
$sequence = new \Ds\Vector();

$sequence->push("a");
$sequence->push("b");
$sequence->push("c", "d");
$sequence->push(...["e", "f"]);

print_r($sequence);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)

Ds\Sequence::reduce

Reduces the sequence to a single value using a callback function

说明

abstract public mixed Ds\Sequence::reduce ( callable $callback [, mixed $initial ] )

Reduces the sequence to a single value using a callback function.

参数

callback
mixed callback ( mixed $carry , mixed $value )

carry
The return value of the previous callback, or initial if it's the first iteration.

value
The value of the current iteration.

initial
The initial value of the carry value. Can be null.

返回值

The return value of the final callback.

范例

示例 #1 Ds\Sequence::reduce with initial value example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

$callback = function($carry, $value) {
    return $carry * $value;
};

var_dump($sequence->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 =  5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

以上例程的输出类似于：

int(30)

示例 #2 Ds\Sequence::reduce without an initial value example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

var_dump($sequence->reduce(function($carry, $value) {
    return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 =  6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

以上例程的输出类似于：

int(21)

Ds\Sequence::remove

Removes and returns a value by index

说明

abstract public mixed Ds\Sequence::remove ( int $index )

Removes and returns a value by index.

参数

index
The index of the value to remove.

返回值

The value that was removed.

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Sequence::remove example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence->remove(1));
var_dump($sequence->remove(0));
var_dump($sequence->remove(0));
?>

以上例程的输出类似于：

string(1) "b"
string(1) "a"
string(1) "c"

Ds\Sequence::reverse

Reverses the sequence in-place

说明

abstract public void Ds\Sequence::reverse ( void )

Reverses the sequence in-place.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Sequence::reverse example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);
$sequence->reverse();

print_r($sequence);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)

Ds\Sequence::reversed

Returns a reversed copy

说明

abstract public Ds\Sequence Ds\Sequence::reversed ( void )

Returns a reversed copy of the sequence.

参数

此函数没有参数。

返回值

A reversed copy of the sequence.

Note:

The current instance is not affected.

范例

示例 #1 Ds\Sequence::reversed example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

print_r($sequence->reversed());
print_r($sequence);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
)

Ds\Sequence::rotate

Rotates the sequence by a given number of rotations

说明

abstract public void Ds\Sequence::rotate ( int $rotations )

Rotates the sequence by a given number of rotations, which is equivalent to successively calling $sequence->push($sequence->shift()) if the number of rotations is positive, or $sequence->unshift($sequence->pop()) if negative.

参数

rotations
The number of times the sequence should be rotated.

返回值

没有返回值。. The sequence of the current instance will be rotated.

范例

示例 #1 Ds\Sequence::rotate example

<?php
$sequence = new \Ds\Vector(["a", "b", "c", "d"]);

$sequence->rotate(1);  // "a" is shifted, then pushed.
print_r($sequence);

$sequence->rotate(2);  // "b" and "c" are both shifted, the pushed.
print_r($sequence);
?>

以上例程的输出类似于：

(
    [0] => b
    [1] => c
    [2] => d
    [3] => a
)
Ds\Vector Object
(
    [0] => d
    [1] => a
    [2] => b
    [3] => c
)

Ds\Sequence::set

Updates a value at a given index

说明

abstract public void Ds\Sequence::set ( int $index , mixed $value )

Updates a value at a given index.

参数

index
The index of the value to update.

value
The new value.

返回值

没有返回值。

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Sequence::set example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

$sequence->set(1, "_");
print_r($sequence);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)

示例 #2 Ds\Sequence::set example using array syntax

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

$sequence[1] = "_";
print_r($sequence);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)

Ds\Sequence::shift

Removes and returns the first value

说明

abstract public mixed Ds\Sequence::shift ( void )

Removes and returns the first value.

参数

此函数没有参数。

返回值

The first value, which was removed.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Sequence::shift example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence->shift());
var_dump($sequence->shift());
var_dump($sequence->shift());
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

Ds\Sequence::slice

Returns a sub-sequence of a given range

说明

abstract public Ds\Sequence Ds\Sequence::slice ( int $index [, int $length ] )

Creates a sub-sequence of a given range.

参数

index
The index at which the sub-sequence starts.

If positive, the sequence will start at that index in the sequence. If negative, the sequence will start that far from the end.

length
If a length is given and is positive, the resulting sequence will have up to that many values in it. If the length results in an overflow, only values up to the end of the sequence will be included. If a length is given and is negative, the sequence will stop that many values from the end. If a length is not provided, the resulting sequence will contain all values between the index and the end of the sequence.

返回值

A sub-sequence of the given range.

范例

示例 #1 Ds\Sequence::slice example

<?php
$sequence = new \Ds\Vector(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($sequence->slice(2));

// Slice from 1, for a length of 3
print_r($sequence->slice(1, 3));

// Slice from 1 onwards
print_r($sequence->slice(1));

// Slice from 2 from the end onwards
print_r($sequence->slice(-2));

// Slice from 1 to 1 from the end
print_r($sequence->slice(1, -1));
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Vector Object
(
    [0] => d
    [1] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)

Ds\Sequence::sort

Sorts the sequence in-place

说明

abstract public void Ds\Sequence::sort ([ callable $comparator ] )

Sorts the sequence in-place, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

Caution Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返回值

没有返回值。

范例

示例 #1 Ds\Sequence::sort example

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);
$sequence->sort();

print_r($sequence);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

示例 #2 Ds\Sequence::sort example using a comparator

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);

$sequence->sort(function($a, $b) {
    return $b <=> $a;
});

print_r($sequence);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

Ds\Sequence::sorted

Returns a sorted copy

说明

abstract public Ds\Sequence Ds\Sequence::sorted ([ callable $comparator ] )

Returns a sorted copy, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

Returns a sorted copy of the sequence.

范例

示例 #1 Ds\Sequence::sorted example

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);

print_r($sequence->sorted());
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

示例 #2 Ds\Sequence::sorted example using a comparator

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);

$sorted = $sequence->sorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

Ds\Sequence::sum

Returns the sum of all values in the sequence

说明

abstract public intfloat Ds\Sequence::sum ( void )

Returns the sum of all values in the sequence.

Note:

Arrays and objects are considered equal to zero when calculating the sum.

参数

此函数没有参数。

返回值

The sum of all the values in the sequence as either a float or int depending on the values in the sequence.

范例

示例 #1 Ds\Sequence::sum integer example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);
var_dump($sequence->sum());
?>

以上例程的输出类似于：

int(6)

示例 #2 Ds\Sequence::sum float example

<?php
$sequence = new \Ds\Vector([1, 2.5, 3]);
var_dump($sequence->sum());
?>

以上例程的输出类似于：

float(6.5)

Ds\Sequence::unshift

Adds values to the front of the sequence

说明

abstract public void Ds\Sequence::unshift ([ mixed $values ] )

Adds values to the front of the sequence, moving all the current values forward to make room for the new values.

参数

values
The values to add to the front of the sequence.

Note:

Multiple values will be added in the same order that they are passed.

返回值

没有返回值。

范例

示例 #1 Ds\Sequence::unshift example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

$sequence->unshift("a");
$sequence->unshift("b", "c");

print_r($sequence);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => a
    [3] => 1
    [4] => 2
    [5] => 3
)

简介

A Vector is a sequence of values in a contiguous buffer that grows and shrinks automatically. It’s the most efficient sequential structure because a value’s index is a direct mapping to its index in the buffer, and the growth factor isn't bound to a specific multiple or exponent.

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.
Capacity does not have to be a power of 2.
get, set, push, pop are all O(1).

Weaknesses

shift, unshift, insert and remove are all O(n).

类摘要

Ds\Vector

class Ds\Vector implements Ds\Sequence , ArrayAccess {

/* Constants */

const int Ds\Vector::MIN_CAPACITY = 10 ;

/* 方法 */

public void allocate ( int $capacity )

public void apply ( callable $callback )

public int capacity ( void )

public void clear ( void )

public bool contains ( mixed $values )

public Ds\Vector copy ( void )

public Ds\Vector filter ([ callable $callback ] )

public mixed find ( mixed $value )

public mixed first ( void )

public mixed get ( int $index )

public void insert ( int $index , mixed $values )

public bool isEmpty ( void )

public string join ([ string $glue ] )

public mixed last ( void )

public Ds\Vector map ( callable $callback )

public Ds\Vector merge ( mixed $values )

public mixed pop ( void )

public void push ( mixed $values )

public mixed reduce ( callable $callback [, mixed $initial ] )

public mixed remove ( int $index )

public void reverse ( void )

public Ds\Vector reversed ( void )

public void rotate ( int $rotations )

public void set ( int $index , mixed $value )

public mixed shift ( void )

public Ds\Vector slice ( int $index [, int $length ] )

public void sort ([ callable $comparator ] )

public Ds\Vector sorted ([ callable $comparator ] )

public intfloat sum ( void )

public array toArray ( void )

public void unshift ([ mixed $values ] )

}

预定义常量

Ds\Vector::MIN_CAPACITY

更新日志

版本	说明
PECL ds 1.3.0	The class now implements ArrayAccess.

Ds\Vector::allocate

Allocates enough memory for a required capacity

说明

public void Ds\Vector::allocate ( int $capacity )

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

参数

capacity
The number of values for which capacity should be allocated.

Note:

Capacity will stay the same if this value is less than or equal to the current capacity.

返回值

没有返回值。

范例

示例 #1 Ds\Vector::allocate example

<?php
$vector = new \Ds\Vector();
var_dump($vector->capacity());

$vector->allocate(100);
var_dump($vector->capacity());
?>

以上例程的输出类似于：

int(10)
int(100)

Ds\Vector::apply

Updates all values by applying a callback function to each value

说明

public void Ds\Vector::apply ( callable $callback )

Updates all values by applying a callback function to each value in the vector.

参数

callback
mixed callback ( mixed $value )

A callable to apply to each value in the vector.

The callback should return what the value should be replaced by.

返回值

没有返回值。

范例

示例 #1 Ds\Vector::apply example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
$vector->apply(function($value) { return $value * 2; });

print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)

Ds\Vector::capacity

Returns the current capacity

说明

public int Ds\Vector::capacity ( void )

Returns the current capacity.

参数

此函数没有参数。

返回值

The current capacity.

范例

示例 #1 Ds\Vector::capacity example

<?php
$vector = new \Ds\Vector();
var_dump($vector->capacity());

$vector->push(...range(1, 50));
var_dump($vector->capacity());

$vector[] = "a";
var_dump($vector->capacity());
?>

以上例程的输出类似于：

int(10)
int(50)
int(75)

Ds\Vector::clear

Removes all values

说明

public void Ds\Vector::clear ( void )

Removes all values from the vector.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Vector::clear example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
print_r($vector);

$vector->clear();
print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
)

Ds\Vector::__construct

Creates a new instance

说明

public Ds\Vector::__construct ([ mixed $values ] )

Creates a new instance, using either a traversable object or an array for the initial values.

参数

values
A traversable object or an array to use for the initial values.

范例

示例 #1 Ds\Vector::__construct example

<?php
$vector = new \Ds\Vector();
var_dump($vector);


$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector);
?>

以上例程的输出类似于：

object(Ds\Vector)#2 (0) {
}
object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Vector::contains

Determines if the vector contains given values

说明

public bool Ds\Vector::contains ( mixed $values )

Determines if the vector contains all values.

参数

values
Values to check.

返回值

false if any of the provided values are not in the vector, true otherwise.

范例

示例 #1 Ds\Vector::contains example

<?php
$vector = new \Ds\Vector(['a', 'b', 'c', 1, 2, 3]);

var_dump($vector->contains('a'));                // true
var_dump($vector->contains('a', 'b'));           // true
var_dump($vector->contains('c', 'd'));           // false

var_dump($vector->contains(...['c', 'b', 'a'])); // true

// Always strict
var_dump($vector->contains(1));                  // true
var_dump($vector->contains('1'));                // false

var_dump($sequece->contains(...[]));               // true
?>

以上例程的输出类似于：

bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(false)
bool(true)

Ds\Vector::copy

Returns a shallow copy of the vector

说明

public Ds\Vector Ds\Vector::copy ( void )

Returns a shallow copy of the vector.

参数

此函数没有参数。

返回值

Returns a shallow copy of the vector.

范例

示例 #1 Ds\Vector::copy example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->push(4);

print_r($a);
print_r($b);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

Ds\Vector::count

Returns the number of values in the collection

See Countable::count

Ds\Vector::filter

Creates a new vector using a callable to determine which values to include

说明

public Ds\Vector Ds\Vector::filter ([ callable $callback ] )

Creates a new vector using a callable to determine which values to include.

参数

callback
bool callback ( mixed $value )

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

返回值

A new vector containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

范例

示例 #1 Ds\Vector::filter example using callback function

<?php
$vector = new \Ds\Vector([1, 2, 3, 4, 5]);

var_dump($vector->filter(function($value) {
    return $value % 2 == 0;
}));
?>

以上例程的输出类似于：

object(Ds\Vector)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

示例 #2 Ds\Vector::filter example without a callback function

<?php
$vector = new \Ds\Vector([0, 1, 'a', true, false]);

var_dump($vector->filter());
?>

以上例程的输出类似于：

object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}

Ds\Vector::find

Attempts to find a value's index

说明

public mixed Ds\Vector::find ( mixed $value )

Returns the index of the value, or false if not found.

参数

value
The value to find.

返回值

The index of the value, or false if not found.

Note:

Values will be compared by value and by type.

范例

示例 #1 Ds\Vector::find example

<?php
$vector = new \Ds\Vector(["a", 1, true]);

var_dump($vector->find("a")); // 0
var_dump($vector->find("b")); // false
var_dump($vector->find("1")); // false
var_dump($vector->find(1));   // 1
?>

以上例程的输出类似于：

int(0)
bool(false)
bool(false)
int(1)

Ds\Vector::first

Returns the first value in the vector

说明

public mixed Ds\Vector::first ( void )

Returns the first value in the vector.

参数

此函数没有参数。

返回值

The first value in the vector.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Vector::first example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector->first());
?>

以上例程的输出类似于：

int(1)

Ds\Vector::get

Returns the value at a given index

说明

public mixed Ds\Vector::get ( int $index )

Returns the value at a given index.

参数

index
The index to access, starting at 0.

返回值

The value at the requested index.

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Vector::get example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector->get(0));
var_dump($vector->get(1));
var_dump($vector->get(2));
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

示例 #2 Ds\Vector::get example using array syntax

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector[0]);
var_dump($vector[1]);
var_dump($vector[2]);
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

Ds\Vector::insert

Inserts values at a given index

说明

public void Ds\Vector::insert ( int $index , mixed $values )

Inserts values into the vector at a given index.

参数

index
The index at which to insert. 0 <= index <= count

Note:

You can insert at the index equal to the number of values.

values
The value or values to insert.

返回值

没有返回值。

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Vector::insert example

<?php
$vector = new \Ds\Vector();

$vector->insert(0, "e");             // [e]
$vector->insert(1, "f");             // [e, f]
$vector->insert(2, "g");             // [e, f, g]
$vector->insert(0, "a", "b");        // [a, b, e, f, g]
$vector->insert(2, ...["c", "d"]);   // [a, b, c, d, e, f, g]

var_dump($vector);
?>

以上例程的输出类似于：

object(Ds\Vector)#1 (7) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
  [3]=>
  string(1) "d"
  [4]=>
  string(1) "e"
  [5]=>
  string(1) "f"
  [6]=>
  string(1) "g"
}

Ds\Vector::isEmpty

Returns whether the vector is empty

说明

public bool Ds\Vector::isEmpty ( void )

Returns whether the vector is empty.

参数

此函数没有参数。

返回值

Returns true if the vector is empty, false otherwise.

范例

示例 #1 Ds\Vector::isEmpty example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = new \Ds\Vector();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

以上例程的输出类似于：

bool(false)
bool(true)

Ds\Vector::join

Joins all values together as a string

说明

public string Ds\Vector::join ([ string $glue ] )

Joins all values together as a string using an optional separator between each value.

参数

glue
An optional string to separate each value.

返回值

All values of the vector joined together as a string.

范例

示例 #1 Ds\Vector::join example using a separator string

<?php
$vector = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($vector->join("|"));
?>

以上例程的输出类似于：

string(11) "a|b|c|1|2|3"

示例 #2 Ds\Vector::join example without a separator string

<?php
$vector = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($vector->join());
?>

以上例程的输出类似于：

string(11) "abc123"

Ds\Vector::jsonSerialize

Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize

Note:

You should never need to call this directly.

Ds\Vector::last

Returns the last value

说明

public mixed Ds\Vector::last ( void )

Returns the last value in the vector.

参数

此函数没有参数。

返回值

The last value in the vector.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Vector::last example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector->last());
?>

以上例程的输出类似于：

int(3)

Ds\Vector::map

Returns the result of applying a callback to each value

说明

public Ds\Vector Ds\Vector::map ( callable $callback )

Returns the result of applying a callback function to each value in the vector.

参数

callback
mixed callback ( mixed $value )

A callable to apply to each value in the vector.

The callable should return what the new value will be in the new vector.

返回值

The result of applying a callback to each value in the vector.

Note:

The values of the current instance won't be affected.

范例

示例 #1 Ds\Vector::map example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

print_r($vector->map(function($value) { return $value * 2; }));
print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)

Ds\Vector::merge

Returns the result of adding all given values to the vector

说明

public Ds\Vector Ds\Vector::merge ( mixed $values )

Returns the result of adding all given values to the vector.

参数

values
A traversable object or an array.

返回值

The result of adding all given values to the vector, effectively the same as adding the values to a copy, then returning that copy.

Note:

The current instance won't be affected.

范例

示例 #1 Ds\Vector::merge example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->merge([4, 5, 6]));
var_dump($vector);
?>

以上例程的输出类似于：

object(Ds\Vector)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
  [5]=>
  int(6)
}
object(Ds\Vector)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Vector::pop

Removes and returns the last value

说明

public mixed Ds\Vector::pop ( void )

Removes and returns the last value.

参数

此函数没有参数。

返回值

The removed last value.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Vector::pop example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->pop());
var_dump($vector->pop());
var_dump($vector->pop());
?>

以上例程的输出类似于：

int(3)
int(2)
int(1)

Ds\Vector::push

Adds values to the end of the vector

说明

public void Ds\Vector::push ( mixed $values )

Adds values to the end of the vector.

参数

values
The values to add.

返回值

没有返回值。

范例

示例 #1 Ds\Vector::push example

<?php
$vector = new \Ds\Vector();

$vector->push("a");
$vector->push("b");
$vector->push("c", "d");
$vector->push(...["e", "f"]);

print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)

Ds\Vector::reduce

Reduces the vector to a single value using a callback function

说明

public mixed Ds\Vector::reduce ( callable $callback [, mixed $initial ] )

Reduces the vector to a single value using a callback function.

参数

callback
mixed callback ( mixed $carry , mixed $value )

carry
The return value of the previous callback, or initial if it's the first iteration.

value
The value of the current iteration.

initial
The initial value of the carry value. Can be null.

返回值

The return value of the final callback.

范例

示例 #1 Ds\Vector::reduce with initial value example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

$callback = function($carry, $value) {
    return $carry * $value;
};

var_dump($vector->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 =  5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

以上例程的输出类似于：

int(30)

示例 #2 Ds\Vector::reduce without an initial value example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->reduce(function($carry, $value) {
    return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 =  6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

以上例程的输出类似于：

int(21)

Ds\Vector::remove

Removes and returns a value by index

说明

public mixed Ds\Vector::remove ( int $index )

Removes and returns a value by index.

参数

index
The index of the value to remove.

返回值

The value that was removed.

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Vector::remove example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector->remove(1));
var_dump($vector->remove(0));
var_dump($vector->remove(0));
?>

以上例程的输出类似于：

string(1) "b"
string(1) "a"
string(1) "c"

Ds\Vector::reverse

Reverses the vector in-place

说明

public void Ds\Vector::reverse ( void )

Reverses the vector in-place.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Vector::reverse example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);
$vector->reverse();

print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)

Ds\Vector::reversed

Returns a reversed copy

说明

public Ds\Vector Ds\Vector::reversed ( void )

Returns a reversed copy of the vector.

参数

此函数没有参数。

返回值

A reversed copy of the vector.

Note:

The current instance is not affected.

范例

示例 #1 Ds\Vector::reversed example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

print_r($vector->reversed());
print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
)

Ds\Vector::rotate

Rotates the vector by a given number of rotations

说明

public void Ds\Vector::rotate ( int $rotations )

Rotates the vector by a given number of rotations, which is equivalent to successively calling $vector->push($vector->shift()) if the number of rotations is positive, or $vector->unshift($vector->pop()) if negative.

参数

rotations
The number of times the vector should be rotated.

返回值

没有返回值。. The vector of the current instance will be rotated.

范例

示例 #1 Ds\Vector::rotate example

<?php
$vector = new \Ds\Vector(["a", "b", "c", "d"]);

$vector->rotate(1);  // "a" is shifted, then pushed.
print_r($vector);

$vector->rotate(2);  // "b" and "c" are both shifted, the pushed.
print_r($vector);
?>

以上例程的输出类似于：

(
    [0] => b
    [1] => c
    [2] => d
    [3] => a
)
Ds\Vector Object
(
    [0] => d
    [1] => a
    [2] => b
    [3] => c
)

Ds\Vector::set

Updates a value at a given index

说明

public void Ds\Vector::set ( int $index , mixed $value )

Updates a value at a given index.

参数

index
The index of the value to update.

value
The new value.

返回值

没有返回值。

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Vector::set example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

$vector->set(1, "_");
print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)

示例 #2 Ds\Vector::set example using array syntax

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

$vector[1] = "_";
print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)

Ds\Vector::shift

Removes and returns the first value

说明

public mixed Ds\Vector::shift ( void )

Removes and returns the first value.

参数

此函数没有参数。

返回值

The first value, which was removed.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Vector::shift example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector->shift());
var_dump($vector->shift());
var_dump($vector->shift());
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

Ds\Vector::slice

Returns a sub-vector of a given range

说明

public Ds\Vector Ds\Vector::slice ( int $index [, int $length ] )

Creates a sub-vector of a given range.

参数

index
The index at which the sub-vector starts.

If positive, the vector will start at that index in the vector. If negative, the vector will start that far from the end.

length
If a length is given and is positive, the resulting vector will have up to that many values in it. If the length results in an overflow, only values up to the end of the vector will be included. If a length is given and is negative, the vector will stop that many values from the end. If a length is not provided, the resulting vector will contain all values between the index and the end of the vector.

返回值

A sub-vector of the given range.

范例

示例 #1 Ds\Vector::slice example

<?php
$vector = new \Ds\Vector(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($vector->slice(2));

// Slice from 1, for a length of 3
print_r($vector->slice(1, 3));

// Slice from 1 onwards
print_r($vector->slice(1));

// Slice from 2 from the end onwards
print_r($vector->slice(-2));

// Slice from 1 to 1 from the end
print_r($vector->slice(1, -1));
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Vector Object
(
    [0] => d
    [1] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)

Ds\Vector::sort

Sorts the vector in-place

说明

public void Ds\Vector::sort ([ callable $comparator ] )

Sorts the vector in-place, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

没有返回值。

范例

示例 #1 Ds\Vector::sort example

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);
$vector->sort();

print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

示例 #2 Ds\Vector::sort example using a comparator

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);

$vector->sort(function($a, $b) {
    return $b <=> $a;
});

print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

Ds\Vector::sorted

Returns a sorted copy

说明

public Ds\Vector Ds\Vector::sorted ([ callable $comparator ] )

Returns a sorted copy, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

Returns a sorted copy of the vector.

范例

示例 #1 Ds\Vector::sorted example

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);

print_r($vector->sorted());
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

示例 #2 Ds\Vector::sorted example using a comparator

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);

$sorted = $vector->sorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

Ds\Vector::sum

Returns the sum of all values in the vector

说明

public intfloat Ds\Vector::sum ( void )

Returns the sum of all values in the vector.

Note:

Arrays and objects are considered equal to zero when calculating the sum.

参数

此函数没有参数。

返回值

The sum of all the values in the vector as either a float or int depending on the values in the vector.

范例

示例 #1 Ds\Vector::sum integer example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector->sum());
?>

以上例程的输出类似于：

int(6)

示例 #2 Ds\Vector::sum float example

<?php
$vector = new \Ds\Vector([1, 2.5, 3]);
var_dump($vector->sum());
?>

以上例程的输出类似于：

float(6.5)

Ds\Vector::toArray

Converts the vector to an array

说明

public array Ds\Vector::toArray ( void )

Converts the vector to an array.

Note:

Casting to an array is not supported yet.

参数

此函数没有参数。

返回值

An array containing all the values in the same order as the vector.

范例

示例 #1 Ds\Vector::toArray example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->toArray());
?>

以上例程的输出类似于：

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Vector::unshift

Adds values to the front of the vector

说明

public void Ds\Vector::unshift ([ mixed $values ] )

Adds values to the front of the vector, moving all the current values forward to make room for the new values.

参数

values
The values to add to the front of the vector.

Note:

Multiple values will be added in the same order that they are passed.

返回值

没有返回值。

范例

示例 #1 Ds\Vector::unshift example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

$vector->unshift("a");
$vector->unshift("b", "c");

print_r($vector);
?>

以上例程的输出类似于：

Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => a
    [3] => 1
    [4] => 2
    [5] => 3
)

简介

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).

类摘要

Ds\Deque

class Ds\Deque implements Ds\Sequence , ArrayAccess {

/* Constants */

const int Ds\Deque::MIN_CAPACITY = 8 ;

/* 方法 */

public void allocate ( int $capacity )

public void apply ( callable $callback )

public int capacity ( void )

public void clear ( void )

public bool contains ( mixed $values )

public Ds\Deque copy ( void )

public Ds\Deque filter ([ callable $callback ] )

public mixed find ( mixed $value )

public mixed first ( void )

public mixed get ( int $index )

public void insert ( int $index , mixed $values )

public bool isEmpty ( void )

public string join ([ string $glue ] )

public mixed last ( void )

public Ds\Deque map ( callable $callback )

public Ds\Deque merge ( mixed $values )

public mixed pop ( void )

public void push ( mixed $values )

public mixed reduce ( callable $callback [, mixed $initial ] )

public mixed remove ( int $index )

public void reverse ( void )

public Ds\Deque reversed ( void )

public void rotate ( int $rotations )

public void set ( int $index , mixed $value )

public mixed shift ( void )

public Ds\Deque slice ( int $index [, int $length ] )

public void sort ([ callable $comparator ] )

public Ds\Deque sorted ([ callable $comparator ] )

public intfloat sum ( void )

public array toArray ( void )

public void unshift ([ mixed $values ] )

}

预定义常量

Ds\Deque::MIN_CAPACITY

更新日志

版本	说明
PECL ds 1.3.0	The class now implements ArrayAccess.

Ds\Deque::allocate

Allocates enough memory for a required capacity

说明

public void Ds\Deque::allocate ( int $capacity )

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

参数

capacity
The number of values for which capacity should be allocated.

Note:

Capacity will stay the same if this value is less than or equal to the current capacity.

Note:

Capacity will always be rounded up to the nearest power of 2.

返回值

没有返回值。

范例

示例 #1 Ds\Deque::allocate example

<?php
$deque = new \Ds\Deque();
var_dump($deque->capacity());

$deque->allocate(100);
var_dump($deque->capacity());
?>

以上例程的输出类似于：

int(8)
int(128)

Ds\Deque::apply

Updates all values by applying a callback function to each value

说明

public void Ds\Deque::apply ( callable $callback )

Updates all values by applying a callback function to each value in the deque.

参数

callback
mixed callback ( mixed $value )

A callable to apply to each value in the deque.

The callback should return what the value should be replaced by.

返回值

没有返回值。

范例

示例 #1 Ds\Deque::apply example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
$deque->apply(function($value) { return $value * 2; });

print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)

Ds\Deque::capacity

Returns the current capacity

说明

public int Ds\Deque::capacity ( void )

Returns the current capacity.

参数

此函数没有参数。

返回值

The current capacity.

范例

示例 #1 Ds\Deque::capacity example

<?php
$deque = new \Ds\Deque();
var_dump($deque->capacity());

$deque->push(...range(1, 50));
var_dump($deque->capacity());
?>

以上例程的输出类似于：

int(8)
int(64)

Ds\Deque::clear

Removes all values from the deque

说明

public void Ds\Deque::clear ( void )

Removes all values from the deque.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Deque::clear example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
print_r($deque);

$deque->clear();
print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Deque Object
(
)

Ds\Deque::__construct

Creates a new instance

说明

public Ds\Deque::__construct ([ mixed $values ] )

Creates a new instance, using either a traversable object or an array for the initial values.

参数

values
A traversable object or an array to use for the initial values.

范例

示例 #1 Ds\Deque::__construct example

<?php
$deque = new \Ds\Deque();
var_dump($deque);

$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque);
?>

以上例程的输出类似于：

object(Ds\Deque)#2 (0) {
}
object(Ds\Deque)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Deque::contains

Determines if the deque contains given values

说明

public bool Ds\Deque::contains ( mixed $values )

Determines if the deque contains all values.

参数

values
Values to check.

返回值

false if any of the provided values are not in the deque, true otherwise.

范例

示例 #1 Ds\Deque::contains example

<?php
$deque = new \Ds\Deque(['a', 'b', 'c', 1, 2, 3]);

var_dump($deque->contains('a'));                // true
var_dump($deque->contains('a', 'b'));           // true
var_dump($deque->contains('c', 'd'));           // false

var_dump($deque->contains(...['c', 'b', 'a'])); // true

// Always strict
var_dump($deque->contains(1));                  // true
var_dump($deque->contains('1'));                // false

var_dump($sequece->contains(...[]));               // true
?>

以上例程的输出类似于：

bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(false)
bool(true)

Ds\Deque::copy

Returns a shallow copy of the deque

说明

public Ds\Deque Ds\Deque::copy ( void )

Returns a shallow copy of the deque.

参数

此函数没有参数。

返回值

A shallow copy of the deque.

范例

示例 #1 Ds\Deque::copy example

<?php
$a = new \Ds\Deque([1, 2, 3]);
$b = $a->copy();

$b->push(4);

print_r($a);
print_r($b);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

Ds\Deque::count

Returns the number of values in the collection

See Countable::count

Ds\Deque::filter

Creates a new deque using a callable to determine which values to include

说明

public Ds\Deque Ds\Deque::filter ([ callable $callback ] )

Creates a new deque using a callable to determine which values to include.

参数

callback
bool callback ( mixed $value )

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

返回值

A new deque containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

范例

示例 #1 Ds\Deque::filter example using callback function

<?php
$deque = new \Ds\Deque([1, 2, 3, 4, 5]);

var_dump($deque->filter(function($value) {
    return $value % 2 == 0;
}));
?>

以上例程的输出类似于：

object(Ds\Deque)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

示例 #2 Ds\Deque::filter example without a callback function

<?php
$deque = new \Ds\Deque([0, 1, 'a', true, false]);

var_dump($deque->filter());
?>

以上例程的输出类似于：

object(Ds\Deque)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}

Ds\Deque::find

Attempts to find a value's index

说明

public mixed Ds\Deque::find ( mixed $value )

Returns the index of the value, or false if not found.

参数

value
The value to find.

返回值

The index of the value, or false if not found.

Note:

Values will be compared by value and by type.

范例

示例 #1 Ds\Deque::find example

<?php
$deque = new \Ds\Deque(["a", 1, true]);

var_dump($deque->find("a")); // 0
var_dump($deque->find("b")); // false
var_dump($deque->find("1")); // false
var_dump($deque->find(1));   // 1
?>

以上例程的输出类似于：

int(0)
bool(false)
bool(false)
int(1)

Ds\Deque::first

Returns the first value in the deque

说明

public mixed Ds\Deque::first ( void )

Returns the first value in the deque.

参数

此函数没有参数。

返回值

The first value in the deque.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Deque::first example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque->first());
?>

以上例程的输出类似于：

int(1)

Ds\Deque::get

Returns the value at a given index

说明

public mixed Ds\Deque::get ( int $index )

Returns the value at a given index.

参数

index
The index to access, starting at 0.

返回值

The value at the requested index.

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Deque::get example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque->get(0));
var_dump($deque->get(1));
var_dump($deque->get(2));
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

示例 #2 Ds\Deque::get example using array syntax

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque[0]);
var_dump($deque[1]);
var_dump($deque[2]);
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

Ds\Deque::insert

Inserts values at a given index

说明

public void Ds\Deque::insert ( int $index , mixed $values )

Inserts values into the deque at a given index.

参数

index
The index at which to insert. 0 <= index <= count

Note:

You can insert at the index equal to the number of values.

values
The value or values to insert.

返回值

没有返回值。

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Deque::insert example

<?php
$deque = new \Ds\Deque();

$deque->insert(0, "e");             // [e]
$deque->insert(1, "f");             // [e, f]
$deque->insert(2, "g");             // [e, f, g]
$deque->insert(0, "a", "b");        // [a, b, e, f, g]
$deque->insert(2, ...["c", "d"]);   // [a, b, c, d, e, f, g]

var_dump($deque);
?>

以上例程的输出类似于：

object(Ds\Deque)#1 (7) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
  [3]=>
  string(1) "d"
  [4]=>
  string(1) "e"
  [5]=>
  string(1) "f"
  [6]=>
  string(1) "g"
}

Ds\Deque::isEmpty

Returns whether the deque is empty

说明

public bool Ds\Deque::isEmpty ( void )

Returns whether the deque is empty.

参数

此函数没有参数。

返回值

Returns true if the deque is empty, false otherwise.

范例

示例 #1 Ds\Deque::isEmpty example

<?php
$a = new \Ds\Deque([1, 2, 3]);
$b = new \Ds\Deque();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

以上例程的输出类似于：

bool(false)
bool(true)

Ds\Deque::join

Joins all values together as a string

说明

public string Ds\Deque::join ([ string $glue ] )

Joins all values together as a string using an optional separator between each value.

参数

glue
An optional string to separate each value.

返回值

All values of the deque joined together as a string.

范例

示例 #1 Ds\Deque::join example using a separator string

<?php
$deque = new \Ds\Deque(["a", "b", "c", 1, 2, 3]);

var_dump($deque->join("|"));
?>

以上例程的输出类似于：

string(11) "a|b|c|1|2|3"

示例 #2 Ds\Deque::join example without a separator string

<?php
$deque = new \Ds\Deque(["a", "b", "c", 1, 2, 3]);

var_dump($deque->join());
?>

以上例程的输出类似于：

string(11) "abc123"

Ds\Deque::jsonSerialize

Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize

Note:

You should never need to call this directly.

Ds\Deque::last

Returns the last value

说明

public mixed Ds\Deque::last ( void )

Returns the last value in the deque.

参数

此函数没有参数。

返回值

The last value in the deque.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Deque::last example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque->last());
?>

以上例程的输出类似于：

int(3)

Ds\Deque::map

Returns the result of applying a callback to each value

说明

public Ds\Deque Ds\Deque::map ( callable $callback )

Returns the result of applying a callback function to each value in the deque.

参数

callback
mixed callback ( mixed $value )

A callable to apply to each value in the deque.

The callable should return what the new value will be in the new deque.

返回值

The result of applying a callback to each value in the deque.

Note:

The values of the current instance won't be affected.

范例

示例 #1 Ds\Deque::map example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

print_r($deque->map(function($value) { return $value * 2; }));
print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)
Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)

Ds\Deque::merge

Returns the result of adding all given values to the deque

说明

public Ds\Deque Ds\Deque::merge ( mixed $values )

Returns the result of adding all given values to the deque.

参数

values
A traversable object or an array.

返回值

The result of adding all given values to the deque, effectively the same as adding the values to a copy, then returning that copy.

Note:

The current instance won't be affected.

范例

示例 #1 Ds\Deque::merge example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->merge([4, 5, 6]));
var_dump($deque);
?>

以上例程的输出类似于：

object(Ds\Deque)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
  [5]=>
  int(6)
}
object(Ds\Deque)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Deque::pop

Removes and returns the last value

说明

public mixed Ds\Deque::pop ( void )

Removes and returns the last value.

参数

此函数没有参数。

返回值

The removed last value.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Deque::pop example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->pop());
var_dump($deque->pop());
var_dump($deque->pop());
?>

以上例程的输出类似于：

int(3)
int(2)
int(1)

Ds\Deque::push

Adds values to the end of the deque

说明

public void Ds\Deque::push ( mixed $values )

Adds values to the end of the deque.

参数

values
The values to add.

返回值

没有返回值。

范例

示例 #1 Ds\Deque::push example

<?php
$deque = new \Ds\Deque();

$deque->push("a");
$deque->push("b");
$deque->push("c", "d");
$deque->push(...["e", "f"]);

print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)

Ds\Deque::reduce

Reduces the deque to a single value using a callback function

说明

public mixed Ds\Deque::reduce ( callable $callback [, mixed $initial ] )

Reduces the deque to a single value using a callback function.

参数

callback
mixed callback ( mixed $carry , mixed $value )

carry
The return value of the previous callback, or initial if it's the first iteration.

value
The value of the current iteration.

initial
The initial value of the carry value. Can be null.

返回值

The return value of the final callback.

范例

示例 #1 Ds\Deque::reduce with initial value example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

$callback = function($carry, $value) {
    return $carry * $value;
};

var_dump($deque->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 =  5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

以上例程的输出类似于：

int(30)

示例 #2 Ds\Deque::reduce without an initial value example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->reduce(function($carry, $value) {
    return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 =  6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

以上例程的输出类似于：

int(21)

Ds\Deque::remove

Removes and returns a value by index

说明

public mixed Ds\Deque::remove ( int $index )

Removes and returns a value by index.

参数

index
The index of the value to remove.

返回值

The value that was removed.

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Deque::remove example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque->remove(1));
var_dump($deque->remove(0));
var_dump($deque->remove(0));
?>

以上例程的输出类似于：

string(1) "b"
string(1) "a"
string(1) "c"

Ds\Deque::reverse

Reverses the deque in-place

说明

public void Ds\Deque::reverse ( void )

Reverses the deque in-place.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Deque::reverse example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);
$deque->reverse();

print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => c
    [1] => b
    [2] => a
)

Ds\Deque::reversed

Returns a reversed copy

说明

public Ds\Deque Ds\Deque::reversed ( void )

Returns a reversed copy of the deque.

参数

此函数没有参数。

返回值

A reversed copy of the deque.

Note:

The current instance is not affected.

范例

示例 #1 Ds\Deque::reversed example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

print_r($deque->reversed());
print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Deque Object
(
    [0] => a
    [1] => b
    [2] => c
)

Ds\Deque::rotate

Rotates the deque by a given number of rotations

说明

public void Ds\Deque::rotate ( int $rotations )

Rotates the deque by a given number of rotations, which is equivalent to successively calling $deque->push($deque->shift()) if the number of rotations is positive, or $deque->unshift($deque->pop()) if negative.

参数

rotations
The number of times the deque should be rotated.

返回值

没有返回值。. The deque of the current instance will be rotated.

范例

示例 #1 Ds\Deque::rotate example

<?php
$deque = new \Ds\Deque(["a", "b", "c", "d"]);

$deque->rotate(1);  // "a" is shifted, then pushed.
print_r($deque);

$deque->rotate(2);  // "b" and "c" are both shifted, the pushed.
print_r($deque);
?>

以上例程的输出类似于：

(
    [0] => b
    [1] => c
    [2] => d
    [3] => a
)
Ds\Deque Object
(
    [0] => d
    [1] => a
    [2] => b
    [3] => c
)

Ds\Deque::set

Updates a value at a given index

说明

public void Ds\Deque::set ( int $index , mixed $value )

Updates a value at a given index.

参数

index
The index of the value to update.

value
The new value.

返回值

没有返回值。

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Deque::set example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

$deque->set(1, "_");
print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => a
    [1] => _
    [2] => c
)

示例 #2 Ds\Deque::set example using array syntax

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

$deque[1] = "_";
print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => a
    [1] => _
    [2] => c
)

Ds\Deque::shift

Removes and returns the first value

说明

public mixed Ds\Deque::shift ( void )

Removes and returns the first value.

参数

此函数没有参数。

返回值

The first value, which was removed.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Deque::shift example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque->shift());
var_dump($deque->shift());
var_dump($deque->shift());
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

Ds\Deque::slice

Returns a sub-deque of a given range

说明

public Ds\Deque Ds\Deque::slice ( int $index [, int $length ] )

Creates a sub-deque of a given range.

参数

index
The index at which the sub-deque starts.

If positive, the deque will start at that index in the deque. If negative, the deque will start that far from the end.

length
If a length is given and is positive, the resulting deque will have up to that many values in it. If the length results in an overflow, only values up to the end of the deque will be included. If a length is given and is negative, the deque will stop that many values from the end. If a length is not provided, the resulting deque will contain all values between the index and the end of the deque.

返回值

A sub-deque of the given range.

范例

示例 #1 Ds\Deque::slice example

<?php
$deque = new \Ds\Deque(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($deque->slice(2));

// Slice from 1, for a length of 3
print_r($deque->slice(1, 3));

// Slice from 1 onwards
print_r($deque->slice(1));

// Slice from 2 from the end onwards
print_r($deque->slice(-2));

// Slice from 1 to 1 from the end
print_r($deque->slice(1, -1));
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Deque Object
(
    [0] => d
    [1] => e
)
Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => d
)

Ds\Deque::sort

Sorts the deque in-place

说明

public void Ds\Deque::sort ([ callable $comparator ] )

Sorts the deque in-place, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

没有返回值。

范例

示例 #1 Ds\Deque::sort example

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);
$deque->sort();

print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

示例 #2 Ds\Deque::sort example using a comparator

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);

$deque->sort(function($a, $b) {
    return $b <=> $a;
});

print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

Ds\Deque::sorted

Returns a sorted copy

说明

public Ds\Deque Ds\Deque::sorted ([ callable $comparator ] )

Returns a sorted copy, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

Returns a sorted copy of the deque.

范例

示例 #1 Ds\Deque::sorted example

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);

print_r($deque->sorted());
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

示例 #2 Ds\Deque::sorted example using a comparator

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);

$sorted = $deque->sorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

Ds\Deque::sum

Returns the sum of all values in the deque

说明

public intfloat Ds\Deque::sum ( void )

Returns the sum of all values in the deque.

Note:

Arrays and objects are considered equal to zero when calculating the sum.

参数

此函数没有参数。

返回值

The sum of all the values in the deque as either a float or int depending on the values in the deque.

范例

示例 #1 Ds\Deque::sum integer example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque->sum());
?>

以上例程的输出类似于：

int(6)

示例 #2 Ds\Deque::sum float example

<?php
$deque = new \Ds\Deque([1, 2.5, 3]);
var_dump($deque->sum());
?>

以上例程的输出类似于：

float(6.5)

Ds\Deque::toArray

Converts the deque to an array

说明

public array Ds\Deque::toArray ( void )

Converts the deque to an array.

Note:

Casting to an array is not supported yet.

参数

此函数没有参数。

返回值

An array containing all the values in the same order as the deque.

范例

示例 #1 Ds\Deque::toArray example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->toArray());
?>

以上例程的输出类似于：

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Deque::unshift

Adds values to the front of the deque

说明

public void Ds\Deque::unshift ([ mixed $values ] )

Adds values to the front of the deque, moving all the current values forward to make room for the new values.

参数

values
The values to add to the front of the deque.

Note:

Multiple values will be added in the same order that they are passed.

返回值

没有返回值。

范例

示例 #1 Ds\Deque::unshift example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

$deque->unshift("a");
$deque->unshift("b", "c");

print_r($deque);
?>

以上例程的输出类似于：

Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => a
    [3] => 1
    [4] => 2
    [5] => 3
)

简介

A Map is a sequential collection of key-value pairs, almost identical to an array used in a similar context. Keys can be any type, but must be unique. Values are replaced if added to the map using the same key.

Strengths

Keys and values can be any type, including objects.
Supports array syntax (square brackets).
Insertion order is preserved.
Performance and memory efficiency is very similar to an array.
Automatically frees allocated memory when its size drops low enough.

Weaknesses

Can’t be converted to an array when objects are used as keys.

类摘要

Ds\Map

class Ds\Map implements Ds\Collection , ArrayAccess {

/* Constants */

const int Ds\Map::MIN_CAPACITY = 16 ;

/* 方法 */

public void allocate ( int $capacity )

public void apply ( callable $callback )

public int capacity ( void )

public void clear ( void )

public Ds\Map copy ( void )

public Ds\Map diff ( Ds\Map $map )

public Ds\Map filter ([ callable $callback ] )

public Ds\Pair first ( void )

public mixed get ( mixed $key [, mixed $default ] )

public bool hasKey ( mixed $key )

public bool hasValue ( mixed $value )

public Ds\Map intersect ( Ds\Map $map )

public bool isEmpty ( void )

public Ds\Set keys ( void )

public void ksort ([ callable $comparator ] )

public Ds\Map ksorted ([ callable $comparator ] )

public Ds\Pair last ( void )

public Ds\Map map ( callable $callback )

public Ds\Map merge ( mixed $values )

public Ds\Sequence pairs ( void )

public void put ( mixed $key , mixed $value )

public void putAll ( mixed $pairs )

public mixed reduce ( callable $callback [, mixed $initial ] )

public mixed remove ( mixed $key [, mixed $default ] )

public void reverse ( void )

public Ds\Map reversed ( void )

public Ds\Pair skip ( int $position )

public Ds\Map slice ( int $index [, int $length ] )

public void sort ([ callable $comparator ] )

public Ds\Map sorted ([ callable $comparator ] )

public intfloat sum ( void )

public array toArray ( void )

public Ds\Map union ( Ds\Map $map )

public Ds\Sequence values ( void )

public Ds\Map xor ( Ds\Map $map )

}

预定义常量

Ds\Map::MIN_CAPACITY

更新日志

版本	说明
PECL ds 1.3.0	The class now implements ArrayAccess.

Ds\Map::allocate

Allocates enough memory for a required capacity

说明

public void Ds\Map::allocate ( int $capacity )

Allocates enough memory for a required capacity.

参数

capacity
The number of values for which capacity should be allocated.

Note:

Capacity will stay the same if this value is less than or equal to the current capacity.

Note:

Capacity will always be rounded up to the nearest power of 2.

返回值

没有返回值。

范例

示例 #1 Ds\Map::allocate example

<?php
$map = new \Ds\Map();
var_dump($map->capacity());

$map->allocate(100);
var_dump($map->capacity());
?>

以上例程的输出类似于：

int(16)
int(128)

Ds\Map::apply

Updates all values by applying a callback function to each value

说明

public void Ds\Map::apply ( callable $callback )

Updates all values by applying a callback function to each value in the map.

参数

callback
mixed callback ( mixed $key , mixed $value )

A callable to apply to each value in the map.

The callback should return what the value should be replaced by.

返回值

没有返回值。

范例

示例 #1 Ds\Map::apply example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$map->apply(function($key, $value) { return $value * 2; });

print_r($map);
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 4
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 6
        )

)

Ds\Map::capacity

Returns the current capacity

说明

public int Ds\Map::capacity ( void )

Returns the current capacity.

参数

此函数没有参数。

返回值

The current capacity.

范例

示例 #1 Ds\Map::capacity example

<?php
$map = new \Ds\Map();
var_dump($map->capacity());
?>

以上例程的输出类似于：

int(16)

Ds\Map::clear

Removes all values

说明

public void Ds\Map::clear ( void )

Removes all values from the map.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Map::clear example

<?php
$map = new \Ds\Map([
    "a" => 1,
    "b" => 2,
    "c" => 3,
]);
print_r($map);

$map->clear();
print_r($map);
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)
Ds\Map Object
(
)

Ds\Map::__construct

Creates a new instance

说明

public Ds\Map::__construct ( mixed $values )

Creates a new instance, using either a traversable object or an array for the initial values.

参数

values
A traversable object or an array to use for the initial values.

范例

示例 #1 Ds\Map::__construct example

<?php
$map = new \Ds\Map();
var_dump($map);

$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map);
?>

以上例程的输出类似于：

object(Ds\Map)#1 (0) {
}
object(Ds\Map)#2 (3) {
  [0]=>
  object(Ds\Pair)#1 (2) {
    ["key"]=>
    string(1) "a"
    ["value"]=>
    int(1)
  }
  [1]=>
  object(Ds\Pair)#3 (2) {
    ["key"]=>
    string(1) "b"
    ["value"]=>
    int(2)
  }
  [2]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    string(1) "c"
    ["value"]=>
    int(3)
  }
}

Ds\Map::copy

Returns a shallow copy of the map

说明

public Ds\Map Ds\Map::copy ( void )

Returns a shallow copy of the map.

参数

此函数没有参数。

返回值

Returns a shallow copy of the map.

范例

示例 #1 Ds\Map::copy example

<?php
$map = new \Ds\Map([
    "a" => 1,
    "b" => 2,
    "c" => 3,
]);

print_r($map->copy());
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

Ds\Map::count

Returns the number of values in the map

See Countable::count

Ds\Map::diff

Creates a new map using keys that aren't in another map

说明

public Ds\Map Ds\Map::diff ( Ds\Map $map )

Returns the result of removing all keys from the current instance that are present in a given map.

A \ B = {x ∈ A | x ∉ B}

参数

map
The map containing the keys to exclude in the resulting map.

返回值

The result of removing all keys from the current instance that are present in a given map.

范例

示例 #1 Ds\Map::diff example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 4, "c" => 5, "d" => 6]);

var_dump($a->diff($b));
?>

以上例程的输出类似于：

object(Ds\Map)#3 (1) {
  [0]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    string(1) "a"
    ["value"]=>
    int(1)
  }
}

Ds\Map::filter

Creates a new map using a callable to determine which pairs to include

说明

public Ds\Map Ds\Map::filter ([ callable $callback ] )

Creates a new map using a callable to determine which pairs to include.

参数

callback
bool callback ( mixed $key , mixed $value )

Optional callable which returns true if the pair should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

返回值

A new map containing all the pairs for which either the callback returned true, or all values that convert to true if a callback was not provided.

范例

示例 #1 Ds\Map::filter example using callback function

<?php
$map = new \Ds\Map(["a", "b", "c", "d", "e"]);

var_dump($map->filter(function($key, $value) {
    return $key % 2 == 0;
}));
?>

以上例程的输出类似于：

object(Ds\Map)#3 (3) {
  [0]=>
  object(Ds\Pair)#2 (2) {
    ["key"]=>
    int(0)
    ["value"]=>
    string(1) "a"
  }
  [1]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    int(2)
    ["value"]=>
    string(1) "c"
  }
  [2]=>
  object(Ds\Pair)#5 (2) {
    ["key"]=>
    int(4)
    ["value"]=>
    string(1) "e"
  }
}

示例 #2 Ds\Map::filter example without a callback function

<?php
$map = new \Ds\Map(["a" => 0, "b" => 1, "c" => true, "d" => false]);

var_dump($map->filter());
?>

以上例程的输出类似于：

object(Ds\Map)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}

Ds\Map::first

Returns the first pair in the map

说明

public Ds\Pair Ds\Map::first ( void )

Returns the first pair in the map.

参数

此函数没有参数。

返回值

The first pair in the map.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Map::first example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->first());
?>

以上例程的输出类似于：

object(Ds\Pair)#2 (2) {
  ["key"]=>
  string(1) "a"
  ["value"]=>
  int(1)
}

Ds\Map::get

Returns the value for a given key

说明

public mixed Ds\Map::get ( mixed $key [, mixed $default ] )

Returns the value for a given key, or an optional default value if the key could not be found.

Note:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

Note:

You can also use array syntax to access values by key, eg. $map["key"].

Caution

Be careful when using array syntax. Scalar keys will be coerced to integers by the engine. For example, $map["1"] will attempt to access int(1), while $map->get("1") will correctly look up the string key.

See Arrays.

参数

key
The key to look up.

default
The optional default value, returned if the key could not be found.

返回值

The value mapped to the given key, or the default value if provided and the key could not be found in the map.

错误／异常

OutOfBoundsException if the key could not be found and a default value was not provided.

范例

示例 #1 Ds\Map::get example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->get("a"));       // 1
var_dump($map->get("d", 10));   // 10 (default used)
?>

以上例程的输出类似于：

int(1)
int(10)

示例 #2 Ds\Map::get example using array syntax

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map["a"])); // 1
?>

以上例程的输出类似于：

int(1)

Ds\Map::hasKey

Determines whether the map contains a given key

说明

public bool Ds\Map::hasKey ( mixed $key )

Determines whether the map contains a given key.

参数

key
The key to look for.

返回值

Returns true if the key could found, false otherwise.

范例

示例 #1 Ds\Map::hasKey example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->hasKey("a")); // true
var_dump($map->hasKey("e")); // false
?>

以上例程的输出类似于：

bool(true)
bool(false)

Ds\Map::hasValue

Determines whether the map contains a given value

说明

public bool Ds\Map::hasValue ( mixed $value )

Determines whether the map contains a given value.

参数

value
The value to look for.

返回值

Returns true if the value could found, false otherwise.

范例

示例 #1 Ds\Map::hasValue example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->hasValue(1)); // true
var_dump($map->hasValue(4)); // false
?>

以上例程的输出类似于：

bool(true)
bool(false)

Ds\Map::intersect

Creates a new map by intersecting keys with another map

说明

public Ds\Map Ds\Map::intersect ( Ds\Map $map )

Creates a new map containing the pairs of the current instance whose keys are also present in the given map. In other words, returns a copy of the current instance with all keys removed that are not also in the other map.

A ∩ B = {x : x ∈ A ∧ x ∈ B}

Note:

Values from the current instance will be kept.

参数

map
The other map, containing the keys to intersect with.

返回值

The key intersection of the current instance and another map.

范例

示例 #1 Ds\Map::intersect example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 4, "c" => 5, "d" => 6]);

var_dump($a->intersect($b));
?>

以上例程的输出类似于：

object(Ds\Map)#3 (2) {
  [0]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    string(1) "b"
    ["value"]=>
    int(2)
  }
  [1]=>
  object(Ds\Pair)#5 (2) {
    ["key"]=>
    string(1) "c"
    ["value"]=>
    int(3)
  }
}

Ds\Map::isEmpty

Returns whether the map is empty

说明

public bool Ds\Map::isEmpty ( void )

Returns whether the map is empty.

参数

此函数没有参数。

返回值

Returns true if the map is empty, false otherwise.

范例

示例 #1 Ds\Map::isEmpty example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

以上例程的输出类似于：

bool(false)
bool(true)

Ds\Map::jsonSerialize

Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize

Note:

You should never need to call this directly.

Ds\Map::keys

Returns a set of the map's keys

说明

public Ds\Set Ds\Map::keys ( void )

Returns a set containing all the keys of the map, in the same order.

参数

此函数没有参数。

返回值

A Ds\Set containing all the keys of the map.

范例

示例 #1 Ds\Map::keys example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->keys());
?>

以上例程的输出类似于：

object(Ds\Set)#2 (3) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
}

Ds\Map::ksort

Sorts the map in-place by key

说明

public void Ds\Map::ksort ([ callable $comparator ] )

Sorts the map in-place by key, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

没有返回值。

范例

示例 #1 Ds\Map::ksort example

<?php
$map = new \Ds\Map(["b" => 2, "c" => 3, "a" => 1]);
$map->ksort();

print_r($map);
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

示例 #2 Ds\Map::ksort example using a comparator

<?php
$map = new \Ds\Map([1 => "x", 2 => "y", 0 => "z"]);

// Reverse
$map->ksort(function($a, $b) {
    return $b <=> $a;
});

print_r($map);
?>

以上例程的输出类似于：

Ds\Map Object
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => 2
            [value] => y
        )

    [1] => Ds\Pair Object
        (
            [key] => 1
            [value] => x
        )

    [2] => Ds\Pair Object
        (
            [key] => 0
            [value] => z
        )

)

Ds\Map::ksorted

Returns a copy, sorted by key

说明

public Ds\Map Ds\Map::ksorted ([ callable $comparator ] )

Returns a copy sorted by key, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

Returns a copy of the map, sorted by key.

范例

示例 #1 Ds\Map::ksorted example

<?php
$map = new \Ds\Map(["b" => 2, "c" => 3, "a" => 1]);

print_r($map->ksorted());
?>

以上例程的输出类似于：

Ds\Map Object
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

示例 #2 Ds\Map::ksorted example using a comparator

<?php
$map = new \Ds\Map([1 => "x", 2 => "y", 0 => "z"]);

// Reverse
$sorted = $map->ksorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

以上例程的输出类似于：

Ds\Map Object
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => 2
            [value] => y
        )

    [1] => Ds\Pair Object
        (
            [key] => 1
            [value] => x
        )

    [2] => Ds\Pair Object
        (
            [key] => 0
            [value] => z
        )

)

Ds\Map::last

Returns the last pair of the map

说明

public Ds\Pair Ds\Map::last ( void )

Returns the last pair of the map.

参数

此函数没有参数。

返回值

The last pair of the map.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Map::last example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->last());
?>

以上例程的输出类似于：

object(Ds\Pair)#2 (2) {
  ["key"]=>
  string(1) "c"
  ["value"]=>
  int(3)
}

Ds\Map::map

Returns the result of applying a callback to each value

说明

public Ds\Map Ds\Map::map ( callable $callback )

Returns the result of applying a callback function to each value of the map.

参数

callback
mixed callback ( mixed $key , mixed $value )

A callable to apply to each value in the map.

The callable should return what the key will be mapped to in the resulting map.

返回值

The result of applying a callback to each value in the map.

Note:

The keys and values of the current instance won't be affected.

范例

示例 #1 Ds\Map::map example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

print_r($map->map(function($key, $value) { return $value * 2; }));
print_r($map);
?>

以上例程的输出类似于：

(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 4
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 6
        )

)
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

Ds\Map::merge

Returns the result of adding all given associations

说明

public Ds\Map Ds\Map::merge ( mixed $values )

Returns the result of associating all keys of a given traversable object or array with their corresponding values, combined with the current instance.

Note:

Values of the current instance will be overwritten by those provided where keys are equal.

参数

values
A traversable object or an array.

返回值

The result of associating all keys of a given traversable object or array with their corresponding values, combined with the current instance.

Note:

The current instance won't be affected.

范例

示例 #1 Ds\Map::merge example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

print_r($map->merge(["a" => 10, "e" => 50]));
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 10
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

    [3] => Ds\Pair Object
        (
            [key] => e
            [value] => 50
        )

)

Ds\Map::pairs

Returns a sequence containing all the pairs of the map

说明

public Ds\Sequence Ds\Map::pairs ( void )

Returns a Ds\Sequence containing all the pairs of the map.

参数

此函数没有参数。

返回值

Ds\Sequence containing all the pairs of the map.

范例

示例 #1 Ds\Map::pairs example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->pairs());
?>

以上例程的输出类似于：

object(Ds\Map)#8 (3) {
  [0]=>
  object(Ds\Pair)#5 (2) {
    ["key"]=>
    string(1) "a"
    ["value"]=>
    int(1)
  }
  [1]=>
  object(Ds\Pair)#6 (2) {
    ["key"]=>
    string(1) "b"
    ["value"]=>
    int(2)
  }
  [2]=>
  object(Ds\Pair)#7 (2) {
    ["key"]=>
    string(1) "c"
    ["value"]=>
    int(3)
  }
}
p

Ds\Map::put

Associates a key with a value

说明

public void Ds\Map::put ( mixed $key , mixed $value )

Associates a key with a value, overwriting a previous association if one exists.

Note:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

Note:

You can also use array syntax to associate values by key, eg. $map["key"] = $value.

Caution

See Arrays.

参数

key
The key to associate the value with.

value
The value to be associated with the key.

返回值

没有返回值。

范例

示例 #1 Ds\Map::put example

<?php
$map = new \Ds\Map();

$map->put("a", 1);
$map->put("b", 2);
$map->put("c", 3);

print_r($map);
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

示例 #2 Ds\Map::put example using objects as keys

<?php
class HashableObject implements \Ds\Hashable
{
    /**
     * An arbitrary value to use as the hash value. Does not define equality.
     */
    private $value;

    public function __construct($value)
    {
        $this->value = $value;
    }

    public function hash()
    {
        return $this->value;
    }

    public function equals($obj): bool
    {
        return $this->value === $obj->value;
    }
}

$map = new \Ds\Map();

$obj = new \ArrayIterator([]);

// Using the same instance multiple times will overwrite the previous value.
$map->put($obj, 1);
$map->put($obj, 2);

// Using multiple instances of the same object will create new associations.
$map->put(new \stdClass(), 3);
$map->put(new \stdClass(), 4);

// Using multiple instances of equal hashable objects will overwrite previous values.
$map->put(new \HashableObject(1), 5);
$map->put(new \HashableObject(1), 6);
$map->put(new \HashableObject(2), 7);
$map->put(new \HashableObject(2), 8);

var_dump($map);
?>

以上例程的输出类似于：

object(Ds\Map)#1 (5) {
  [0]=>
  object(Ds\Pair)#7 (2) {
    ["key"]=>
    object(ArrayIterator)#2 (1) {
      ["storage":"ArrayIterator":private]=>
      array(0) {
      }
    }
    ["value"]=>
    int(2)
  }
  [1]=>
  object(Ds\Pair)#8 (2) {
    ["key"]=>
    object(stdClass)#3 (0) {
    }
    ["value"]=>
    int(3)
  }
  [2]=>
  object(Ds\Pair)#9 (2) {
    ["key"]=>
    object(stdClass)#4 (0) {
    }
    ["value"]=>
    int(4)
  }
  [3]=>
  object(Ds\Pair)#10 (2) {
    ["key"]=>
    object(HashableObject)#5 (1) {
      ["value":"HashableObject":private]=>
      int(1)
    }
    ["value"]=>
    int(6)
  }
  [4]=>
  object(Ds\Pair)#11 (2) {
    ["key"]=>
    object(HashableObject)#6 (1) {
      ["value":"HashableObject":private]=>
      int(2)
    }
    ["value"]=>
    int(8)
  }
}

Ds\Map::putAll

Associates all key-value pairs of a traversable object or array

说明

public void Ds\Map::putAll ( mixed $pairs )

Associates all key-value pairs of a traversable object or array.

Note:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

参数

pairs
traversable object or array.

返回值

没有返回值。

范例

示例 #1 Ds\Map::putAll example

<?php
$map = new \Ds\Map();

$map->putAll([
    "a" => 1,
    "b" => 2,
    "c" => 3,
]);

print_r($map);
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

Ds\Map::reduce

Reduces the map to a single value using a callback function

说明

public mixed Ds\Map::reduce ( callable $callback [, mixed $initial ] )

Reduces the map to a single value using a callback function.

参数

callback
mixed callback ( mixed $carry , mixed $key , mixed $value )

carry
The return value of the previous callback, or initial if it's the first iteration.

key
The key of the current iteration.

value
The value of the current iteration.

initial
The initial value of the carry value. Can be null.

返回值

The return value of the final callback.

范例

示例 #1 Ds\Map::reduce with initial value example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

$callback = function($carry, $key, $value) {
    return $carry * $value;
};

var_dump($map->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 =  5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

以上例程的输出类似于：

int(30)

示例 #2 Ds\Map::reduce without an initial value example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->reduce(function($carry, $key, $value) {
    return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 =  6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

以上例程的输出类似于：

int(21)

Ds\Map::remove

Removes and returns a value by key

说明

public mixed Ds\Map::remove ( mixed $key [, mixed $default ] )

Removes and returns a value by key, or return an optional default value if the key could not be found.

Note:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

Note:

You can also use array syntax to access values by key, eg. $map["key"].

Caution

See Arrays.

参数

key
The key to remove.

default
The optional default value, returned if the key could not be found.

返回值

The value that was removed, or the default value if provided and the key could not be found in the map.

错误／异常

OutOfBoundsException if the key could not be found and a default value was not provided.

范例

示例 #1 Ds\Map::remove example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->remove("a"));      //  1
var_dump($map->remove("e", 10));  // 10 (default used)
?>

以上例程的输出类似于：

int(1)
int(10)

Ds\Map::reverse

Reverses the map in-place

说明

public void Ds\Map::reverse ( void )

Reverses the map in-place.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Map::reverse example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$map->reverse();

print_r($map);
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

)

Ds\Map::reversed

Returns a reversed copy

说明

public Ds\Map Ds\Map::reversed ( void )

Returns a reversed copy of the map.

参数

此函数没有参数。

返回值

A reversed copy of the map.

Note:

The current instance is not affected.

范例

示例 #1 Ds\Map::reversed example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

print_r($map->reversed());
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

)

Ds\Map::skip

Returns the pair at a given positional index

说明

public Ds\Pair Ds\Map::skip ( int $position )

Returns the pair at a given zero-based position.

参数

position
The zero-based positional index to return.

返回值

Returns the Ds\Pair at the given position.

错误／异常

OutOfRangeException if the position is not valid.

范例

示例 #1 Ds\Map::skip example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->skip(1));
?>

以上例程的输出类似于：

object(Ds\Pair)#2 (2) {
  ["key"]=>
  string(1) "b"
  ["value"]=>
  int(2)
}

Ds\Map::slice

Returns a subset of the map defined by a starting index and length

说明

public Ds\Map Ds\Map::slice ( int $index [, int $length ] )

Returns a subset of the map defined by a starting index and length.

参数

index
The index at which the range starts.

If positive, the range will start at that index in the map. If negative, the range will start that far from the end.

length
If a length is given and is positive, the resulting map will have up to that many pairs in it. If a length is given and is negative, the range will stop that many pairs from the end. If the length results in an overflow, only pairs up to the end of the map will be included. If a length is not provided, the resulting map will contain all pairs between the index and the end of the map.

返回值

A subset of the map defined by a starting index and length.

范例

示例 #1 Ds\Map::slice example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3, "d" => 4, "e" => 5]);

// Slice from 2 onwards
print_r($map->slice(2)->toArray());

// Slice from 1, for a length of 3
print_r($map->slice(1, 3)->toArray());

// Slice from 1 onwards
print_r($map->slice(1)->toArray());

// Slice from 2 from the end onwards
print_r($map->slice(-2)->toArray());

// Slice from 1 to 1 from the end
print_r($map->slice(1, -1)->toArray());
?>

以上例程的输出类似于：

Array
(
    [c] => 3
    [d] => 4
    [e] => 5
)
Array
(
    [b] => 2
    [c] => 3
    [d] => 4
)
Array
(
    [b] => 2
    [c] => 3
    [d] => 4
    [e] => 5
)
Array
(
    [d] => 4
    [e] => 5
)
Array
(
    [b] => 2
    [c] => 3
    [d] => 4
)

Ds\Map::sort

Sorts the map in-place by value

说明

public void Ds\Map::sort ([ callable $comparator ] )

Sorts the map in-place by value, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

没有返回值。

范例

示例 #1 Ds\Map::sort example

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);
$map->sort();

print_r($map);
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

)

示例 #2 Ds\Map::sort example using a comparator

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);

$map->sort(function($a, $b) {
    return $b <=> $a;
});

print_r($map);
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

)

Ds\Map::sorted

Returns a copy, sorted by value

说明

public Ds\Map Ds\Map::sorted ([ callable $comparator ] )

Returns a copy, sorted by value using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

Returns a copy of the map, sorted by value.

范例

示例 #1 Ds\Map::sort example

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);

print_r($map->sorted());
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

)

示例 #2 Ds\Map::sort example using a comparator

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);

// Reverse
$sorted = $map->sorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

)

Ds\Map::sum

Returns the sum of all values in the map

说明

public intfloat Ds\Map::sum ( void )

Returns the sum of all values in the map.

Note:

Arrays and objects are considered equal to zero when calculating the sum.

参数

此函数没有参数。

返回值

The sum of all the values in the map as either a float or int depending on the values in the map.

范例

示例 #1 Ds\Map::sum integer example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->sum());
?>

以上例程的输出类似于：

int(6)

示例 #2 Ds\Map::sum float example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2.5, "c" => 3]);
var_dump($map->sum());
?>

以上例程的输出类似于：

float(6.5)

Ds\Map::toArray

Converts the map to an array

说明

public array Ds\Map::toArray ( void )

Converts the map to an array.

Caution

Maps where non-scalar keys are can't be converted to an array.

Caution

An array will treat all numeric keys as integers, eg. "1" and 1 as keys in the map will only result in 1 being included in the array.

Note:

Casting to an array is not supported yet.

参数

此函数没有参数。

返回值

An array containing all the values in the same order as the map.

范例

示例 #1 Ds\Map::toArray example

<?php
$map = new \Ds\Map([
    "a" => 1,
    "b" => 2,
    "c" => 3,
]);

var_dump($map->toArray());
?>

以上例程的输出类似于：

array(3) {
  ["a"]=>
  int(1)
  ["b"]=>
  int(2)
  ["c"]=>
  int(3)
}

Ds\Map::union

Creates a new map using values from the current instance and another map

说明

public Ds\Map Ds\Map::union ( Ds\Map $map )

Creates a new map that contains the pairs of the current instance as well as the pairs of another map.

A ∪ B = {x: x ∈ A ∨ x ∈ B}

Note:

Values of the current instance will be overwritten by those provided where keys are equal.

参数

map
The other map, to combine with the current instance.

返回值

A new map containing all the pairs of the current instance as well as another map.

范例

示例 #1 Ds\Map::union example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 3, "c" => 4, "d" => 5]);

print_r($a->union($b));
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 4
        )

    [3] => Ds\Pair Object
        (
            [key] => d
            [value] => 5
        )

)

Ds\Map::values

Returns a sequence of the map's values

说明

public Ds\Sequence Ds\Map::values ( void )

Returns a sequence containing all the values of the map, in the same order.

参数

此函数没有参数。

返回值

A Ds\Sequence containing all the values of the map.

范例

示例 #1 Ds\Map::values example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->values());
?>

以上例程的输出类似于：

object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Map::xor

Creates a new map using keys of either the current instance or of another map, but not of both

说明

public Ds\Map Ds\Map::xor ( Ds\Map $map )

Creates a new map containing keys of the current instance as well as another map, but not of both.

A ⊖ B = {x : x ∈ (A \ B) ∪ (B \ A)}

参数

map
The other map.

返回值

A new map containing keys in the current instance as well as another map, but not in both.

范例

示例 #1 Ds\Map::xor example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 4, "c" => 5, "d" => 6]);

print_r($a->xor($b));
?>

以上例程的输出类似于：

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => d
            [value] => 6
        )

)

简介

A pair is used by Ds\Map to pair keys with values.

类摘要

Ds\Pair

class Ds\Pair implements JsonSerializable {

/* 方法 */

public __construct ([ mixed $key [, mixed $value ]] )

public void clear ( void )

public Ds\Pair copy ( void )

public bool isEmpty ( void )

public array toArray ( void )

}

Ds\Pair::clear

Removes all values

说明

public void Ds\Pair::clear ( void )

Removes all values from the pair.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Pair::clear example

<?php
$pair = new \Ds\Pair("a", 1);
print_r($pair);

$pair->clear();
print_r($pair);
?>

以上例程的输出类似于：

Ds\Pair Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Pair Object
(
)

Ds\Pair::__construct

Creates a new instance

说明

public Ds\Pair::__construct ([ mixed $key [, mixed $value ]] )

Creates a new instance using a given key and value.

参数

key
The key.

value
The value.

Ds\Pair::copy

Returns a shallow copy of the pair

说明

public Ds\Pair Ds\Pair::copy ( void )

Returns a shallow copy of the pair.

参数

此函数没有参数。

返回值

Returns a shallow copy of the pair.

范例

示例 #1 Ds\Pair::copy example

<?php
$a = new \Ds\Pair("a", 1);
$b = $a->copy();

$a->key = "x";

print_r($a);
print_r($b);
?>

以上例程的输出类似于：

Ds\Pair Object
(
    [key] => x
    [value] => 1
)
Ds\Pair Object
(
    [key] => a
    [value] => 1
)

Ds\Pair::isEmpty

Returns whether the pair is empty

说明

public bool Ds\Pair::isEmpty ( void )

Returns whether the pair is empty.

参数

此函数没有参数。

返回值

Returns true if the pair is empty, false otherwise.

范例

示例 #1 Ds\Pair::isEmpty example

<?php
$a = new \Ds\Pair("a", 1);
$b = new \Ds\Pair();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

以上例程的输出类似于：

bool(false)
bool(true)

Ds\Pair::jsonSerialize

Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize

Note:

You should never need to call this directly.

Ds\Pair::toArray

Converts the pair to an array

说明

public array Ds\Pair::toArray ( void )

Converts the pair to an array.

Note:

Casting to an array is not supported yet.

参数

此函数没有参数。

返回值

An array containing all the values in the same order as the pair.

范例

示例 #1 Ds\Pair::toArray example

<?php
$pair = new \Ds\Pair("a", 1);

var_dump($pair->toArray());
?>

以上例程的输出类似于：

array(2) {
  ["key"]=>
  string(1) "a"
  ["value"]=>
  int(1)
}

简介

A Set is a sequence of unique values. This implementation uses the same hash table as Ds\Map, where values are used as keys and the mapped value is ignored.

Strengths

Values can be any type, including objects.
Supports array syntax (square brackets).
Insertion order is preserved.
Automatically frees allocated memory when its size drops low enough.
add, remove and contains are all O(1).

Weaknesses

Doesn’t support push, pop, insert, shift, or unshift.
get is O(n) if there are deleted values in the buffer before the accessed index, O(1) otherwise.

类摘要

Ds\Set

class Ds\Set implements Ds\Collection , ArrayAccess {

/* Constants */

const int Ds\Set::MIN_CAPACITY = 16 ;

/* 方法 */

public void add ( mixed $values )

public void allocate ( int $capacity )

public int capacity ( void )

public void clear ( void )

public bool contains ( mixed $values )

public Ds\Set copy ( void )

public Ds\Set diff ( Ds\Set $set )

public Ds\Set filter ([ callable $callback ] )

public mixed first ( void )

public mixed get ( int $index )

public Ds\Set intersect ( Ds\Set $set )

public bool isEmpty ( void )

public string join ([ string $glue ] )

public mixed last ( void )

public Ds\Set merge ( mixed $values )

public mixed reduce ( callable $callback [, mixed $initial ] )

public void remove ( mixed $values )

public void reverse ( void )

public Ds\Set reversed ( void )

public Ds\Set slice ( int $index [, int $length ] )

public void sort ([ callable $comparator ] )

public Ds\Set sorted ([ callable $comparator ] )

public intfloat sum ( void )

public array toArray ( void )

public Ds\Set union ( Ds\Set $set )

public Ds\Set xor ( Ds\Set $set )

}

预定义常量

Ds\Set::MIN_CAPACITY

更新日志

版本	说明
PECL ds 1.3.0	The class now implements ArrayAccess.

Ds\Set::add

Adds values to the set

说明

public void Ds\Set::add ( mixed $values )

Adds all given values to the set that haven't already been added.

Note:

Values of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

Caution

All comparisons are strict (type and value).

参数

values
Values to add to the set.

返回值

没有返回值。

范例

示例 #1 Ds\Set::add example using integers

<?php
$set = new \Ds\Set();

$set->add(1);
$set->add(1);
$set->add(2);
$set->add(3);

// Strict comparison would not treat these the same as int(1)
$set->add("1");
$set->add(true);

var_dump($set);
?>

以上例程的输出类似于：

object(Ds\Set)#1 (5) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  string(1) "1"
  [4]=>
  bool(true)
}

示例 #2 Ds\Set::add example using objects

<?php
class HashableObject implements \Ds\Hashable
{
    /**
     * An arbitrary value to use as the hash value. Does not define equality.
     */
    private $value;

    public function __construct($value)
    {
        $this->value = $value;
    }

    public function hash()
    {
        return $this->value;
    }

    public function equals($obj): bool
    {
        return $this->value === $obj->value;
    }
}

$set = new \Ds\Set();

$obj = new \ArrayIterator([]);

// Adding the same instance multiple times will only add the first.
$set->add($obj);
$set->add($obj);

// Adding multiple instances of the same object will add them all.
$set->add(new \stdClass());
$set->add(new \stdClass());

// Adding multiple instances of equal hashable objects will only add the first.
$set->add(new \HashableObject(1));
$set->add(new \HashableObject(1));
$set->add(new \HashableObject(2));
$set->add(new \HashableObject(2));

var_dump($set);
?>

以上例程的输出类似于：

object(Ds\Set)#1 (5) {
  [0]=>
  object(ArrayIterator)#2 (1) {
    ["storage":"ArrayIterator":private]=>
    array(0) {
    }
  }
  [1]=>
  object(stdClass)#3 (0) {
  }
  [2]=>
  object(stdClass)#4 (0) {
  }
  [3]=>
  object(HashableObject)#5 (1) {
    ["value":"HashableObject":private]=>
    int(1)
  }
  [4]=>
  object(HashableObject)#6 (1) {
    ["value":"HashableObject":private]=>
    int(2)
  }
}

Ds\Set::allocate

Allocates enough memory for a required capacity

说明

public void Ds\Set::allocate ( int $capacity )

Allocates enough memory for a required capacity.

参数

capacity
The number of values for which capacity should be allocated.

Note:

Capacity will stay the same if this value is less than or equal to the current capacity.

Note:

Capacity will always be rounded up to the nearest power of 2.

返回值

没有返回值。

范例

示例 #1 Ds\Set::allocate example

<?php
$set = new \Ds\Set();
var_dump($set->capacity());

$set->allocate(100);
var_dump($set->capacity());
?>

以上例程的输出类似于：

int(16)
int(128)

Ds\Set::capacity

Returns the current capacity

说明

public int Ds\Set::capacity ( void )

Returns the current capacity.

参数

此函数没有参数。

返回值

The current capacity.

范例

示例 #1 Ds\Set::capacity example

<?php
$set = new \Ds\Set();
var_dump($set->capacity());

$set->push(...range(1, 50));
var_dump($set->capacity());
?>

以上例程的输出类似于：

int(16)
int(64)

Ds\Set::clear

Removes all values

说明

public void Ds\Set::clear ( void )

Removes all values from the set.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Set::clear example

<?php
$set = new \Ds\Set([1, 2, 3]);
print_r($set);

$set->clear();
print_r($set);
?>

以上例程的输出类似于：

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Set Object
(
)

Ds\Set::__construct

Creates a new instance

说明

public Ds\Set::__construct ( mixed $values )

Creates a new instance, using either a traversable object or an array for the initial values.

参数

values
A traversable object or an array to use for the initial values.

范例

示例 #1 Ds\Set::__construct example

<?php
$set = new \Ds\Set();
var_dump($set);

$set = new \Ds\Set([1, 2, 3]);
var_dump($set);
?>

以上例程的输出类似于：

object(Ds\Set)#1 (0) {
}
object(Ds\Set)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Set::contains

Determines if the set contains all values

说明

public bool Ds\Set::contains ( mixed $values )

Determines if the set contains all values.

Note:

Values of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

Caution

All comparisons are strict (type and value).

参数

values
Values to check.

返回值

false if any of the provided values are not in the set, true otherwise.

范例

示例 #1 Ds\Set::contains example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->contains(1));                // true
var_dump($set->contains(1, 2));             // true
var_dump($set->contains(...[1, 2]));        // true

var_dump($set->contains("1"));              // false
var_dump($set->contains(...[1, 2, 3, 4]));  // false

var_dump($set->contains(...[]));            // true
?>

以上例程的输出类似于：

bool(true)
bool(true)
bool(true)
bool(false)
bool(false)
bool(true)

Ds\Set::copy

Returns a shallow copy of the set

说明

public Ds\Set Ds\Set::copy ( void )

Returns a shallow copy of the set.

参数

此函数没有参数。

返回值

Returns a shallow copy of the set.

范例

示例 #1 Ds\Set::copy example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->add(4);

print_r($a);
print_r($b);
?>

以上例程的输出类似于：

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

Ds\Set::count

Returns the number of values in the set

See Countable::count

Ds\Set::diff

Creates a new set using values that aren't in another set

说明

public Ds\Set Ds\Set::diff ( Ds\Set $set )

Creates a new set using values that aren't in another set.

A \ B = {x ∈ A | x ∉ B}

参数

set
Set containing the values to exclude.

返回值

A new set containing all values that were not in the other set.

范例

示例 #1 Ds\Set::diff example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->diff($b));
?>

以上例程的输出类似于：

object(Ds\Set)#3 (2) {
  [0]=>
  int(1)
  [1]=>
  int(2)
}

Ds\Set::filter

Creates a new set using a callable to determine which values to include

说明

public Ds\Set Ds\Set::filter ([ callable $callback ] )

Creates a new set using a callable to determine which values to include.

参数

callback
bool callback ( mixed $value )

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

返回值

A new set containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

范例

示例 #1 Ds\Set::filter example using callback function

<?php
$set = new \Ds\Set([1, 2, 3, 4, 5]);

var_dump($set->filter(function($value) {
    return $value % 2 == 0;
}));
?>

以上例程的输出类似于：

object(Ds\Set)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

示例 #2 Ds\Set::filter example without a callback function

<?php
$set = new \Ds\Set([0, 1, 'a', true, false]);

var_dump($set->filter());
?>

以上例程的输出类似于：

object(Ds\Set)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}

Ds\Set::first

Returns the first value in the set

说明

public mixed Ds\Set::first ( void )

Returns the first value in the set.

参数

此函数没有参数。

返回值

The first value in the set.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Set::first example

<?php
$set = new \Ds\Set([1, 2, 3]);
var_dump($set->first());
?>

以上例程的输出类似于：

int(1)

Ds\Set::get

Returns the value at a given index

说明

public mixed Ds\Set::get ( int $index )

Returns the value at a given index.

参数

index
The index to access, starting at 0.

返回值

The value at the requested index.

错误／异常

OutOfRangeException if the index is not valid.

范例

示例 #1 Ds\Set::get example

<?php
$set = new \Ds\Set(["a", "b", "c"]);

var_dump($set->get(0));
var_dump($set->get(1));
var_dump($set->get(2));
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

示例 #2 Ds\Set::get example using array syntax

<?php
$set = new \Ds\Set(["a", "b", "c"]);

var_dump($set[0]);
var_dump($set[1]);
var_dump($set[2]);
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

Ds\Set::intersect

Creates a new set by intersecting values with another set

说明

public Ds\Set Ds\Set::intersect ( Ds\Set $set )

Creates a new set using values common to both the current instance and another set. In other words, returns a copy of the current instance with all values removed that are not in the other set.

A ∩ B = {x : x ∈ A ∧ x ∈ B}

参数

set
The other set.

返回值

The intersection of the current instance and another set.

范例

示例 #1 Ds\Set::intersect example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->intersect($b));
?>

以上例程的输出类似于：

object(Ds\Set)#3 (1) {
  [0]=>
  int(3)
}

Ds\Set::isEmpty

Returns whether the set is empty

说明

public bool Ds\Set::isEmpty ( void )

Returns whether the set is empty.

参数

此函数没有参数。

返回值

Returns true if the set is empty, false otherwise.

范例

示例 #1 Ds\Set::isEmpty example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

以上例程的输出类似于：

bool(false)
bool(true)

Ds\Set::join

Joins all values together as a string

说明

public string Ds\Set::join ([ string $glue ] )

Joins all values together as a string using an optional separator between each value.

参数

glue
An optional string to separate each value.

返回值

All values of the set joined together as a string.

范例

示例 #1 Ds\Set::join example using a separator string

<?php
$set = new \Ds\Set(["a", "b", "c", 1, 2, 3]);

var_dump($set->join("|"));
?>

以上例程的输出类似于：

string(11) "a|b|c|1|2|3"

示例 #2 Ds\Set::join example without a separator string

<?php
$set = new \Ds\Set(["a", "b", "c", 1, 2, 3]);

var_dump($set->join());
?>

以上例程的输出类似于：

string(11) "abc123"

Ds\Set::jsonSerialize

Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize

Note:

You should never need to call this directly.

Ds\Set::last

Returns the last value in the set

说明

public mixed Ds\Set::last ( void )

Returns the last value in the set.

参数

此函数没有参数。

返回值

The last value in the set.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Set::last example

<?php
$set = new \Ds\Set([1, 2, 3]);
var_dump($set->last());
?>

以上例程的输出类似于：

int(3)

Ds\Set::merge

Returns the result of adding all given values to the set

说明

public Ds\Set Ds\Set::merge ( mixed $values )

Returns the result of adding all given values to the set.

参数

values
A traversable object or an array.

返回值

The result of adding all given values to the set, effectively the same as adding the values to a copy, then returning that copy.

Note:

The current instance won't be affected.

范例

示例 #1 Ds\Set::merge example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->merge([3, 4, 5]));
var_dump($set);
?>

以上例程的输出类似于：

object(Ds\Set)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
}
object(Ds\Set)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Set::reduce

Reduces the set to a single value using a callback function

说明

public mixed Ds\Set::reduce ( callable $callback [, mixed $initial ] )

Reduces the set to a single value using a callback function.

参数

callback
mixed callback ( mixed $carry , mixed $value )

carry
The return value of the previous callback, or initial if it's the first iteration.

value
The value of the current iteration.

initial
The initial value of the carry value. Can be null.

返回值

The return value of the final callback.

范例

示例 #1 Ds\Set::reduce with initial value example

<?php
$set = new \Ds\Set([1, 2, 3]);

$callback = function($carry, $value) {
    return $carry * $value;
};

var_dump($set->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 =  5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

以上例程的输出类似于：

int(30)

示例 #2 Ds\Set::reduce without an initial value example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->reduce(function($carry, $value) {
    return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 =  6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

以上例程的输出类似于：

int(21)

Ds\Set::remove

Removes all given values from the set

说明

public void Ds\Set::remove ( mixed $values )

Removes all given values from the set, ignoring any that are not in the set.

参数

values
The values to remove.

返回值

没有返回值。

范例

示例 #1 Ds\Set::remove example

<?php
$set = new \Ds\Set([1, 2, 3, 4, 5]);

$set->remove(1);            // Remove 1
$set->remove(1, 2);         // Can't find 1, but remove 2
$set->remove(...[3, 4]);    // Remove 3 and 4

var_dump($set);
?>

以上例程的输出类似于：

object(Ds\Set)#1 (1) {
  [0]=>
  int(5)
}

Ds\Set::reverse

Reverses the set in-place

说明

public void Ds\Set::reverse ( void )

Reverses the set in-place.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Set::reverse example

<?php
$set = new \Ds\Set(["a", "b", "c"]);
$set->reverse();

print_r($set);
?>

以上例程的输出类似于：

Ds\Set Object
(
    [0] => c
    [1] => b
    [2] => a
)

Ds\Set::reversed

Returns a reversed copy

说明

public Ds\Set Ds\Set::reversed ( void )

Returns a reversed copy of the set.

参数

此函数没有参数。

返回值

A reversed copy of the set.

Note:

The current instance is not affected.

范例

示例 #1 Ds\Set::reversed example

<?php
$set = new \Ds\Set(["a", "b", "c"]);

print_r($set->reversed());
print_r($set);
?>

以上例程的输出类似于：

Ds\Set Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Set Object
(
    [0] => a
    [1] => b
    [2] => c
)

Ds\Set::slice

Returns a sub-set of a given range

说明

public Ds\Set Ds\Set::slice ( int $index [, int $length ] )

Creates a sub-set of a given range.

参数

index
The index at which the sub-set starts.

If positive, the set will start at that index in the set. If negative, the set will start that far from the end.

length
If a length is given and is positive, the resulting set will have up to that many values in it. If the length results in an overflow, only values up to the end of the set will be included. If a length is given and is negative, the set will stop that many values from the end. If a length is not provided, the resulting set will contain all values between the index and the end of the set.

返回值

A sub-set of the given range.

范例

示例 #1 Ds\Set::slice example

<?php
$set = new \Ds\Set(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($set->slice(2));

// Slice from 1, for a length of 3
print_r($set->slice(1, 3));

// Slice from 1 onwards
print_r($set->slice(1));

// Slice from 2 from the end onwards
print_r($set->slice(-2));

// Slice from 1 to 1 from the end
print_r($set->slice(1, -1));
?>

以上例程的输出类似于：

Ds\Set Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Set Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Set Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Set Object
(
    [0] => d
    [1] => e
)
Ds\Set Object
(
    [0] => b
    [1] => c
    [2] => d
)

Ds\Set::sort

Sorts the set in-place

说明

public void Ds\Set::sort ([ callable $comparator ] )

Sorts the set in-place, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

没有返回值。

范例

示例 #1 Ds\Set::sort example

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);
$set->sort();

print_r($set);
?>

以上例程的输出类似于：

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

示例 #2 Ds\Set::sort example using a comparator

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);

$set->sort(function($a, $b) {
    return $b <=> $a;
});

print_r($set);
?>

以上例程的输出类似于：

Ds\Set Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

Ds\Set::sorted

Returns a sorted copy

说明

public Ds\Set Ds\Set::sorted ([ callable $comparator ] )

Returns a sorted copy, using an optional comparator function.

参数

comparator
在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

int callback ( mixed $a, mixed $b )

返回值

Returns a sorted copy of the set.

范例

示例 #1 Ds\Set::sorted example

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);

print_r($set->sorted());
?>

以上例程的输出类似于：

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

示例 #2 Ds\Set::sorted example using a comparator

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);

$sorted = $set->sorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

以上例程的输出类似于：

Ds\Set Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

Ds\Set::sum

Returns the sum of all values in the set

说明

public intfloat Ds\Set::sum ( void )

Returns the sum of all values in the set.

Note:

Arrays and objects are considered equal to zero when calculating the sum.

参数

此函数没有参数。

返回值

The sum of all the values in the set as either a float or int depending on the values in the set.

范例

示例 #1 Ds\Set::sum integer example

<?php
$set = new \Ds\Set([1, 2, 3]);
var_dump($set->sum());
?>

以上例程的输出类似于：

int(6)

示例 #2 Ds\Set::sum float example

<?php
$set = new \Ds\Set([1, 2.5, 3]);
var_dump($set->sum());
?>

以上例程的输出类似于：

float(6.5)

Ds\Set::toArray

Converts the set to an array

说明

public array Ds\Set::toArray ( void )

Converts the set to an array.

Note:

Casting to an array is not supported yet.

参数

此函数没有参数。

返回值

An array containing all the values in the same order as the set.

范例

示例 #1 Ds\Set::toArray example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->toArray());
?>

以上例程的输出类似于：

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Set::union

Creates a new set using values from the current instance and another set

说明

public Ds\Set Ds\Set::union ( Ds\Set $set )

Creates a new set that contains the values of the current instance as well as the values of another set.

A ∪ B = {x: x ∈ A ∨ x ∈ B}

参数

set
The other set, to combine with the current instance.

返回值

A new set containing all the values of the current instance as well as another set.

范例

示例 #1 Ds\Set::union example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->union($b));
?>

以上例程的输出类似于：

object(Ds\Set)#3 (5) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
}

Ds\Set::xor

Creates a new set using values in either the current instance or in another set, but not in both

说明

public Ds\Set Ds\Set::xor ( Ds\Set $set )

Creates a new set containing values in the current instance as well as another set, but not in both.

A ⊖ B = {x : x ∈ (A \ B) ∪ (B \ A)}

参数

set
The other set.

返回值

A new set containing values in the current instance as well as another set, but not in both.

范例

示例 #1 Ds\Set::xor example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->xor($b));
?>

以上例程的输出类似于：

object(Ds\Set)#3 (4) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(4)
  [3]=>
  int(5)
}

简介

A Stack is a “last in, first out” or “LIFO” collection that only allows access to the value at the top of the structure and iterates in that order, destructively.

Uses a Ds\Vector internally.

类摘要

Ds\Stack

class Ds\Stack implements Ds\Collection , ArrayAccess {

/* 方法 */

public void allocate ( int $capacity )

public int capacity ( void )

public void clear ( void )

public Ds\Stack copy ( void )

public bool isEmpty ( void )

public mixed peek ( void )

public mixed pop ( void )

public void push ( mixed $values )

public array toArray ( void )

}

更新日志

版本	说明
PECL ds 1.3.0	The class now implements ArrayAccess.

Ds\Stack::allocate

Allocates enough memory for a required capacity

说明

public void Ds\Stack::allocate ( int $capacity )

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

参数

capacity
The number of values for which capacity should be allocated.

Note:

Capacity will stay the same if this value is less than or equal to the current capacity.

返回值

没有返回值。

Ds\Stack::capacity

Returns the current capacity

说明

public int Ds\Stack::capacity ( void )

Returns the current capacity.

参数

此函数没有参数。

返回值

The current capacity.

Ds\Stack::clear

Removes all values

说明

public void Ds\Stack::clear ( void )

Removes all values from the stack.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Stack::clear example

<?php
$stack = new \Ds\Stack([1, 2, 3]);
print_r($stack);

$stack->clear();
print_r($stack);
?>

以上例程的输出类似于：

Ds\Stack Object
(
    [0] => 3
    [1] => 2
    [2] => 1
)
Ds\Stack Object
(
)

Ds\Stack::__construct

Creates a new instance

说明

public Ds\Stack::__construct ([ mixed $values ] )

Creates a new instance, using either a traversable object or an array for the initial values.

参数

values
A traversable object or an array to use for the initial values.

范例

示例 #1 Ds\Stack::__construct example

<?php
$stack = new \Ds\Stack();
print_r($stack);

$stack = new \Ds\Stack([1, 2, 3]);
print_r($stack);
?>

以上例程的输出类似于：

Ds\Stack Object
(
)
Ds\Stack Object
(
    [0] => 3
    [1] => 2
    [2] => 1
)

Ds\Stack::copy

Returns a shallow copy of the stack

说明

public Ds\Stack Ds\Stack::copy ( void )

Returns a shallow copy of the stack.

参数

此函数没有参数。

返回值

Returns a shallow copy of the stack.

范例

示例 #1 Ds\Stack::copy example

<?php
$a = new \Ds\Stack([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->push(4);

print_r($a);
print_r($b);
?>

以上例程的输出类似于：

Ds\Stack Object
(
    [0] => 3
    [1] => 2
    [2] => 1
)
Ds\Stack Object
(
    [0] => 4
    [1] => 3
    [2] => 2
    [3] => 1
)

Ds\Stack::count

Returns the number of values in the stack

See Countable::count

Ds\Stack::isEmpty

Returns whether the stack is empty

说明

public bool Ds\Stack::isEmpty ( void )

Returns whether the stack is empty.

参数

此函数没有参数。

返回值

Returns true if the stack is empty, false otherwise.

范例

示例 #1 Ds\Stack::isEmpty example

<?php
$a = new \Ds\Stack([1, 2, 3]);
$b = new \Ds\Stack();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

以上例程的输出类似于：

bool(false)
bool(true)

Ds\Stack::jsonSerialize

Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize

Note:

You should never need to call this directly.

Ds\Stack::peek

Returns the value at the top of the stack

说明

public mixed Ds\Stack::peek ( void )

Returns the value at the top of the stack, but does not remove it.

参数

此函数没有参数。

返回值

The value at the top of the stack.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Stack::peek example

<?php
$stack = new \Ds\Stack();

$stack->push("a");
$stack->push("b");
$stack->push("c");

var_dump($stack->peek());
?>

以上例程的输出类似于：

string(1) "c"

Ds\Stack::pop

Removes and returns the value at the top of the stack

说明

public mixed Ds\Stack::pop ( void )

Removes and returns the value at the top of the stack.

参数

此函数没有参数。

返回值

The removed value which was at the top of the stack.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Stack::pop example

<?php
$stack = new \Ds\Stack();

$stack->push("a");
$stack->push("b");
$stack->push("c");

var_dump($stack->pop());
var_dump($stack->pop());
var_dump($stack->pop());
?>

以上例程的输出类似于：

string(1) "c"
string(1) "b"
string(1) "a"

Ds\Stack::push

Pushes values onto the stack

说明

public void Ds\Stack::push ( mixed $values )

Pushes values onto the stack.

参数

values
The values to push onto the stack.

返回值

没有返回值。

范例

示例 #1 Ds\Stack::push example

<?php
$stack = new \Ds\Stack();

$stack->push("a");
$stack->push("b");
$stack->push("c", "d");
$stack->push(...["e", "f"]);

print_r($stack);
?>

以上例程的输出类似于：

Ds\Stack Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)

Ds\Stack::toArray

Converts the stack to an array

说明

public array Ds\Stack::toArray ( void )

Converts the stack to an array.

Note:

Casting to an array is not supported yet.

参数

此函数没有参数。

返回值

An array containing all the values in the same order as the stack.

范例

示例 #1 Ds\Stack::toArray example

<?php
$stack = new \Ds\Stack([1, 2, 3]);

var_dump($stack->toArray());
?>

以上例程的输出类似于：

array(3) {
  [0]=>
  int(3)
  [1]=>
  int(2)
  [2]=>
  int(1)
}

简介

A Queue is a “first in, first out” or “FIFO” collection that only allows access to the value at the front of the queue and iterates in that order, destructively.

类摘要

Ds\Queue

class Ds\Queue implements Ds\Collection , ArrayAccess {

/* Constants */

const int Ds\Queue::MIN_CAPACITY = 8 ;

/* 方法 */

public void allocate ( int $capacity )

public int capacity ( void )

public void clear ( void )

public Ds\Queue copy ( void )

public bool isEmpty ( void )

public mixed peek ( void )

public mixed pop ( void )

public void push ( mixed $values )

public array toArray ( void )

}

预定义常量

Ds\Queue::MIN_CAPACITY

更新日志

版本	说明
PECL ds 1.3.0	The class now implements ArrayAccess.

Ds\Queue::allocate

Allocates enough memory for a required capacity

说明

public void Ds\Queue::allocate ( int $capacity )

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

Note:

Capacity will always be rounded up to the nearest power of 2.

参数

capacity
The number of values for which capacity should be allocated.

Note:

Capacity will stay the same if this value is less than or equal to the current capacity.

Note:

Capacity will always be rounded up to the nearest power of 2.

返回值

没有返回值。

范例

示例 #1 Ds\Queue::allocate example

<?php
$queue = new \Ds\Queue();
var_dump($queue->capacity());

$queue->allocate(100);
var_dump($queue->capacity());
?>

以上例程的输出类似于：

int(8)
int(128)

Ds\Queue::capacity

Returns the current capacity

说明

public int Ds\Queue::capacity ( void )

Returns the current capacity.

参数

此函数没有参数。

返回值

The current capacity.

范例

示例 #1 Ds\Queue::capacity example

<?php
$queue = new \Ds\Queue();
var_dump($queue->capacity());

$queue->push(...range(1, 50));
var_dump($queue->capacity());
?>

以上例程的输出类似于：

int(8)
int(64)

Ds\Queue::clear

Removes all values

说明

public void Ds\Queue::clear ( void )

Removes all values from the queue.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\Queue::clear example

<?php
$queue = new \Ds\Queue([1, 2, 3]);
print_r($queue);

$queue->clear();
print_r($queue);
?>

以上例程的输出类似于：

Ds\Queue Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Queue Object
(
)

Ds\Queue::__construct

Creates a new instance

说明

public Ds\Queue::__construct ([ mixed $values ] )

Creates a new instance, using either a traversable object or an array for the initial values.

参数

values
A traversable object or an array to use for the initial values.

范例

示例 #1 Ds\Queue::__construct example

<?php
$queue = new \Ds\Queue();
var_dump($queue);


$queue = new \Ds\Queue([1, 2, 3]);
var_dump($queue);
?>

以上例程的输出类似于：

object(Ds\Queue)#2 (0) {
}
object(Ds\Queue)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

Ds\Queue::copy

Returns a shallow copy of the queue

说明

public Ds\Queue Ds\Queue::copy ( void )

Returns a shallow copy of the queue.

参数

此函数没有参数。

返回值

Returns a shallow copy of the queue.

范例

示例 #1 Ds\Queue::copy example

<?php
$a = new \Ds\Queue([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->push(4);

print_r($a);
print_r($b);
?>

以上例程的输出类似于：

Ds\Queue Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Queue Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

Ds\Queue::count

Returns the number of values in the queue

See Countable::count

Ds\Queue::isEmpty

Returns whether the queue is empty

说明

public bool Ds\Queue::isEmpty ( void )

Returns whether the queue is empty.

参数

此函数没有参数。

返回值

Returns true if the queue is empty, false otherwise.

范例

示例 #1 Ds\Queue::isEmpty example

<?php
$a = new \Ds\Queue([1, 2, 3]);
$b = new \Ds\Queue();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

以上例程的输出类似于：

bool(false)
bool(true)

Ds\Queue::jsonSerialize

Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize

Note:

You should never need to call this directly.

Ds\Queue::peek

Returns the value at the front of the queue

说明

public mixed Ds\Queue::peek ( void )

Returns the value at the front of the queue, but does not remove it.

参数

此函数没有参数。

返回值

The value at the front of the queue.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Queue::peek example

<?php
$queue = new \Ds\Queue();

$queue->push("a");
$queue->push("b");
$queue->push("c");

var_dump($queue->peek());
?>

以上例程的输出类似于：

string(1) "a"

Ds\Queue::pop

Removes and returns the value at the front of the queue

说明

public mixed Ds\Queue::pop ( void )

Removes and returns the value at the front of the queue.

参数

此函数没有参数。

返回值

The removed value which was at the front of the queue.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\Queue::pop example

<?php
$queue = new \Ds\Queue();

$queue->push("a");
$queue->push("b");
$queue->push("c");

var_dump($queue->pop());
var_dump($queue->pop());
var_dump($queue->pop());
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

Ds\Queue::push

Pushes values into the queue

说明

public void Ds\Queue::push ( mixed $values )

Pushes values into the queue.

参数

values
The values to push into the queue.

返回值

没有返回值。

范例

示例 #1 Ds\Queue::push example

<?php
$queue = new \Ds\Queue();

$queue->push("a");
$queue->push("b");
$queue->push("c", "d");
$queue->push(...["e", "f"]);

print_r($queue);
?>

以上例程的输出类似于：

Ds\Queue Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)

Ds\Queue::toArray

Converts the queue to an array

说明

public array Ds\Queue::toArray ( void )

Converts the queue to an array.

Note:

Casting to an array is not supported yet.

Note:

This method is not destructive.

参数

此函数没有参数。

返回值

An array containing all the values in the same order as the queue.

范例

示例 #1 Ds\Queue::toArray example

<?php
$queue = new \Ds\Queue([1, 2, 3]);

var_dump($queue->toArray());
?>

以上例程的输出类似于：

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

简介

A PriorityQueue is very similar to a Queue. Values are pushed into the queue with an assigned priority, and the value with the highest priority will always be at the front of the queue.

Implemented using a max heap.

Note:

"First in, first out" ordering is preserved for values with the same priority.

Note:

Iterating over a PriorityQueue is destructive, equivalent to successive pop operations until the queue is empty.

类摘要

Ds\PriorityQueue

class Ds\PriorityQueue implements Ds\Collection {

/* Constants */

const int Ds\PriorityQueue::MIN_CAPACITY = 8 ;

/* 方法 */

public void allocate ( int $capacity )

public int capacity ( void )

public void clear ( void )

public Ds\PriorityQueue copy ( void )

public bool isEmpty ( void )

public mixed peek ( void )

public mixed pop ( void )

public void push ( mixed $value , int $priority )

public array toArray ( void )

}

预定义常量

Ds\PriorityQueue::MIN_CAPACITY

Ds\PriorityQueue::allocate

Allocates enough memory for a required capacity

说明

public void Ds\PriorityQueue::allocate ( int $capacity )

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

参数

capacity
The number of values for which capacity should be allocated.

Note:

Capacity will stay the same if this value is less than or equal to the current capacity.

Note:

Capacity will always be rounded up to the nearest power of 2.

返回值

没有返回值。

范例

示例 #1 Ds\PriorityQueue::allocate example

<?php
$queue = new \Ds\PriorityQueue();
var_dump($queue->capacity());

$queue->allocate(100);
var_dump($queue->capacity());
?>

以上例程的输出类似于：

int(8)
int(128)

Ds\PriorityQueue::capacity

Returns the current capacity

说明

public int Ds\PriorityQueue::capacity ( void )

Returns the current capacity.

参数

此函数没有参数。

返回值

The current capacity.

范例

示例 #1 Ds\PriorityQueue::capacity example

<?php
$queue = new \Ds\PriorityQueue();
var_dump($queue->capacity());
?>

以上例程的输出类似于：

int(8)

Ds\PriorityQueue::clear

Removes all values

说明

public void Ds\PriorityQueue::clear ( void )

Removes all values from the queue.

参数

此函数没有参数。

返回值

没有返回值。

范例

示例 #1 Ds\PriorityQueue::clear example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

$queue->clear();
print_r($queue);
?>

以上例程的输出类似于：

Ds\PriorityQueue Object
(
)

Ds\PriorityQueue::__construct

Creates a new instance

说明

public Ds\PriorityQueue::__construct ( void )

Creates a new instance.

范例

示例 #1 Ds\PriorityQueue::__construct example

<?php
$queue = new \Ds\PriorityQueue();
var_dump($queue);
?>

以上例程的输出类似于：

object(Ds\PriorityQueue)#1 (0) {
}

Ds\PriorityQueue::copy

Returns a shallow copy of the queue

说明

public Ds\PriorityQueue Ds\PriorityQueue::copy ( void )

Returns a shallow copy of the queue.

参数

此函数没有参数。

返回值

Returns a shallow copy of the queue.

范例

示例 #1 Ds\PriorityQueue::copy example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

print_r($queue->copy());
?>

以上例程的输出类似于：

Ds\PriorityQueue Object
(
    [0] => b
    [1] => c
    [2] => a
)

Ds\PriorityQueue::count

Returns the number of values in the queue

See Countable::count

Ds\PriorityQueue::isEmpty

Returns whether the queue is empty

说明

public bool Ds\PriorityQueue::isEmpty ( void )

Returns whether the queue is empty.

参数

此函数没有参数。

返回值

Returns true if the queue is empty, false otherwise.

范例

示例 #1 Ds\PriorityQueue::isEmpty example

<?php
$a = new \Ds\PriorityQueue();
$b = new \Ds\PriorityQueue();

$a->push("a",  5);
$a->push("b", 15);
$a->push("c", 10);

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

以上例程的输出类似于：

bool(false)
bool(true)

Ds\PriorityQueue::jsonSerialize

Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize

Note:

You should never need to call this directly.

Ds\PriorityQueue::peek

Returns the value at the front of the queue

说明

public mixed Ds\PriorityQueue::peek ( void )

Returns the value at the front of the queue, but does not remove it.

参数

此函数没有参数。

返回值

The value at the front of the queue.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\PriorityQueue::peek example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

var_dump($queue->peek());
?>

以上例程的输出类似于：

string(1) "b"

Ds\PriorityQueue::pop

Removes and returns the value with the highest priority

说明

public mixed Ds\PriorityQueue::pop ( void )

Removes and returns the value at the front of the queue, ie. the value with the highest priority.

Note:

Values with equal priority fall back to FIFO (first in first out).

参数

此函数没有参数。

返回值

The removed value which was at the front of the queue.

错误／异常

UnderflowException if empty.

范例

示例 #1 Ds\PriorityQueue::pop example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

print_r($queue->pop());
print_r($queue->pop());
print_r($queue->pop());
?>

以上例程的输出类似于：

string(1) "a"
string(1) "b"
string(1) "c"

Ds\PriorityQueue::push

Pushes values into the queue

说明

public void Ds\PriorityQueue::push ( mixed $value , int $priority )

Pushes a value with a given priority into the queue.

参数

value
The value to push into the queue.

priority
The priority associated with the value.

返回值

没有返回值。

范例

示例 #1 Ds\PriorityQueue::push example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

print_r($queue->pop());
print_r($queue->pop());
print_r($queue->pop());
?>

以上例程的输出类似于：

string(1) "b"
string(1) "c"
string(1) "a"

Ds\PriorityQueue::toArray

Converts the queue to an array

说明

public array Ds\PriorityQueue::toArray ( void )

Converts the queue to an array.

Note:

This method is not destructive.

Note:

Casting to an array is not supported yet.

参数

此函数没有参数。

返回值

An array containing all the values in the same order as the queue.

范例

示例 #1 Ds\PriorityQueue::toArray example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

var_dump($queue->toArray());
?>

以上例程的输出类似于：

array(3) {
  [0]=>
  string(1) "b"
  [1]=>
  string(1) "c"
  [2]=>
  string(1) "a"
}