Menu

Reference

Reference / Manticore\Ds

Set

finalclass
final class Set<T> implements \Countable, \IteratorAggregate, \JsonSerializable

An insertion-ordered collection of unique values.

Values may be int, string or objects, with the same rules as {@see Map} keys: 1 and '1' are different members, objects are compared by identity, and any other type throws TypeError. Adding a value that is already present does nothing. add(), has() and remove() run in O(1) on average.

Iteration is in insertion order and yields the positions 0, 1, 2, … as keys. Like Map, a Set is an object (assignment copies the handle, clone copies the contents), and it must not be changed while it is being iterated.

$tags = new Set();
$tags->add('php');
$tags->add('php');
echo count($tags);   // 1

Example

use Manticore\Ds\Set;

$tags = new Set();
foreach (['php', 'llvm', 'php', 'aot'] as $tag) {
    $tags->add($tag);           // a duplicate is ignored
}

echo count($tags), "\n";        // 3
var_dump($tags->has('llvm'));
echo implode(',', $tags->toArray()), "\n";   // insertion order

$other = new Set();
$other->add('aot');
$other->add('jit');

echo implode(',', $tags->union($other)->toArray()), "\n";
echo implode(',', $tags->intersect($other)->toArray()), "\n";
echo implode(',', $tags->diff($other)->toArray()), "\n";

$tags->remove('php');
try {
    $tags->remove('php');
} catch (OutOfBoundsException $e) {
    echo $e->getMessage(), "\n";
}

Output

3
bool(true)
php,llvm,aot
php,llvm,aot,jit
aot
php,llvm
Value not found

See also: Map

Methods

__construct()Creates an empty set.
__clone()Makes the clone an independent set with the same members.
add()Adds $value; a value already in the set is left where it is.
has()Tells whether $value is a member.
remove()Removes $value.
count()Returns the number of members.
isEmpty()Tells whether the set has no members.
clear()Removes every member.
toArray()Copies the members into a list, in insertion order.
union()Returns a new set with the members of both sets.
intersect()Returns a new set with the members present in both sets, in this set's order.
diff()Returns a new set with the members of this set that $other lacks, in this set's order.
getIterator()Iterates the members in insertion order; the keys are the positions 0, 1, 2, ….
jsonSerialize()Encodes as a JSON array of the members.
each()Calls $f($member) for every member, in order.
map()Builds a new set from $f($member) for every member.
filter()Builds a new set with the members for which $f($member) is truthy.
reduce()Folds the members into one value: $carry = $f($carry, $member).
any()Tells whether $f($member) is truthy for at least one member (stops at the first).
all()Tells whether $f($member) is truthy for every member (stops at the first miss).
find()Returns the first member for which $f($member) is truthy.

__construct()#source

function __construct()

Creates an empty set.

__clone()#source

function __clone()

Makes the clone an independent set with the same members.

add()#source

function add(mixed $value): void

Adds $value; a value already in the set is left where it is.

Parameters

$value T
the member to add

Throws

\TypeError
when $value is not an int, a string or an object

has()#source

function has(mixed $value): bool

Tells whether $value is a member.

Parameters

$value T
the value to look for

Returns

bool — true when present

Throws

\TypeError
when $value is not an int, a string or an object

remove()#source

function remove(mixed $value): void

Removes $value.

Parameters

$value T
the member to remove

Throws

\OutOfBoundsException
when $value is not a member
\TypeError
when $value is not an int, a string or an object

count()#source

function count(): int

Returns the number of members.

Returns

int — the member count

isEmpty()#source

function isEmpty(): bool

Tells whether the set has no members.

Returns

bool — true when empty

clear()#source

function clear(): void

Removes every member.

toArray()#source

function toArray(): array

Copies the members into a list, in insertion order.

Returns

list<T> — the members

union()#source

function union(Set $other): Set

Returns a new set with the members of both sets.

Members of this set come first, then the ones only $other has.

Parameters

$other Set<T>
the other set

Returns

Set<T> — a new set; neither input changes

intersect()#source

function intersect(Set $other): Set

Returns a new set with the members present in both sets, in this set's order.

Parameters

$other Set<T>
the other set

Returns

Set<T> — a new set; neither input changes

diff()#source

function diff(Set $other): Set

Returns a new set with the members of this set that $other lacks, in this set's order.

Parameters

$other Set<T>
the set to subtract

Returns

Set<T> — a new set; neither input changes

getIterator()#source

function getIterator(): \Generator

Iterates the members in insertion order; the keys are the positions 0, 1, 2, ….

Returns

\Generator — a generator over the members

Throws

\RuntimeException
when the set is changed in a way the running loop cannot follow

jsonSerialize()#source

function jsonSerialize(): mixed

Encodes as a JSON array of the members.

Returns

mixed — the list from {@see toArray()}

each()#source

function each(callable $f): void

Calls $f($member) for every member, in order.

Parameters

$f callable(T): void
the callback

map()#source

function map(callable $f): Set

Builds a new set from $f($member) for every member.

Results that coincide collapse into one member.

Parameters

$f callable(T): U
maps a member to the new member

Returns

Set<U> — a new set; this one is unchanged

filter()#source

function filter(callable $f): Set

Builds a new set with the members for which $f($member) is truthy.

Parameters

$f callable(T): bool
the predicate

Returns

Set<T> — a new set; this one is unchanged

reduce()#source

function reduce(callable $f, mixed $initial): mixed

Folds the members into one value: $carry = $f($carry, $member).

Parameters

$f callable(R, T): R
combines the carry with the next member
$initial R
the starting carry, also the result for an empty set

Returns

R — the final carry

any()#source

function any(callable $f): bool

Tells whether $f($member) is truthy for at least one member (stops at the first).

Parameters

$f callable(T): bool
the predicate

Returns

bool — false for an empty set

all()#source

function all(callable $f): bool

Tells whether $f($member) is truthy for every member (stops at the first miss).

Parameters

$f callable(T): bool
the predicate

Returns

bool — true for an empty set

find()#source

function find(callable $f): mixed

Returns the first member for which $f($member) is truthy.

null means "none matched" but is also a valid member; use {@see any()} when the set can hold null.

Parameters

$f callable(T): bool
the predicate

Returns

?T — the first matching member, or null

View source