| Methods |
public
|
__construct(mixed ...$values)
Creates a new instance, using either a traversable object or an array for the initial values.
Creates a new instance, using either a traversable object or an array for the initial values.
Parameters
| ...$values |
A traversable object or an array to use for the initial values.
|
|
#
|
public
|
allocate(int $capacity)
Allocates enough memory for a required capacity.
Allocates enough memory for a required capacity.
Parameters
| $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.
Capacity will always be rounded up to the nearest power of 2.
|
|
#
|
public
|
apply(callable $callback)
Updates all values by applying a callback function to each value in the map.
Updates all values by applying a callback function to each value in the map.
Parameters
| $callback |
A callable to apply to each value in the map. The callback should return what
the value should be replaced by.
|
|
#
|
public
|
capacity(): int
Returns the current capacity.
Returns the current capacity.
|
#
|
public
|
count(): int
Count elements of an object
Count elements of an object
Returns
The custom count as an integer.
The return value is cast to an integer.
Implements
|
#
|
public
|
clear(): void
Removes all values from the collection.
Removes all values from the collection.
Implements
|
#
|
public
|
copy(): Collection
Returns a shallow copy of the collection.
Returns a shallow copy of the collection.
Implements
|
#
|
public
|
diff(Map $map): Map
Returns the result of removing all keys from the current instance that are present in a given 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}
Parameters
| $map |
The map containing the keys to exclude in the resulting map.
|
Returns
The result of removing all keys from the current instance that are present in a given map.
|
#
|
public
|
filter(null|callable $callback = null): Map
Creates a new map using a callable to determine which pairs to include
Creates a new map using a callable to determine which pairs to include
Parameters
| $callback |
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.
|
|
#
|
public
|
first(): Pair
Returns the first pair in the map
Returns the first pair in the map
Returns
The first pair in the map.
Throws
|
#
|
public
|
get(mixed $key, mixed $default = null): mixed
Returns the value for a given key, or an optional default value if the key could not be found.
<p>
<b>Note:</b> Keys of…
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.
Parameters
| $key |
The key to look up.
|
| $default |
The optional default value, returned if the key could not be found.
|
Returns
The value mapped to the given key, or the default value if provided and the key could not be found in the map.
Throws
|
#
|
public
|
getIterator(): Traversable
|
#
|
public
|
hasKey(mixed $key): bool
Determines whether the map contains a given key
Determines whether the map contains a given key
Parameters
| $key |
The key to look for.
|
Returns
Returns TRUE if the key could found, FALSE otherwise.
|
#
|
public
|
hasValue(mixed $value): bool
Determines whether the map contains a given value
Determines whether the map contains a given value
Parameters
| $value |
The value to look for.
|
Returns
Returns TRUE if the value could found, FALSE otherwise.
|
#
|
public
|
intersect(Map $map): Map
Creates a new map containing the pairs of the current instance whose
keys are also present in the given map. In other…
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.
Parameters
| $map |
The other map, containing the keys to intersect with.
|
Returns
The key intersection of the current instance and another map.
|
#
|
public
|
isEmpty(): bool
Returns whether the collection is empty.
Returns whether the collection is empty.
Returns
Returns TRUE if the map is empty, FALSE otherwise.
Implements
|
#
|
public
|
toArray(): array
Converts the map to an array.
<p><b>Note:</b> Casting to an array is not supported yet.</p>
<p><b>Caution:</b> Maps…
Converts the map to an array.
Note: Casting to an array is not supported yet.
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.
Returns
An array containing all the values in the same order as
the map.
Implements
|
#
|
public
|
jsonSerialize(): mixed
Specify data which should be serialized to JSON
Specify data which should be serialized to JSON
Returns
data which can be serialized by json_encode,
which is a value of any type other than a resource.
Implements
|
#
|
public
|
keys(): Set
Returns a set containing all the keys of the map, in the same order.
Returns a set containing all the keys of the map, in the same order.
Returns
A Ds\Set containing all the keys of the map.
|
#
|
public
|
ksort(callable|null $comparator = null)
Sorts the map in-place by key, using an optional comparator function.
Sorts the map in-place by key, using an optional comparator function.
Parameters
| $comparator |
The comparison function must return
an integer less than, equal to, or greater than zero if the first
argument is considered to be respectively less than, equal to, or
greater than the second. Note that before PHP 7.0.0 this integer had
to be in the range from -2147483648 to 2147483647.
callback ( mixed $a, mixed $b ) : int
Caution: Returning non-integer values from the comparison function, such
as float, will result in an internal cast to integer 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.
|
|
#
|
public
|
ksorted(callable|null $comparator = null): Map
Returns a copy sorted by key, using an optional comparator function.
Returns a copy sorted by key, using an optional comparator function.
Parameters
| $comparator |
The comparison function must return
an integer less than, equal to, or greater than zero if the first
argument is considered to be respectively less than, equal to, or
greater than the second. Note that before PHP 7.0.0 this integer had
to be in the range from -2147483648 to 2147483647.
callback ( mixed $a, mixed $b ) : int
Caution: Returning non-integer values from the comparison function, such
as float, will result in an internal cast to integer 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.
|
Returns
Returns a copy of the map, sorted by key.
|
#
|
public
|
last(): Pair
Returns the last pair of the map.
Returns the last pair of the map.
Returns
The last pair of the map.
Throws
|
#
|
public
|
map(callable $callback): Map
Returns the result of applying a callback function to each value of
the map.
Returns the result of applying a callback function to each value of
the map.
Parameters
| $callback |
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.
callback ( mixed $key , mixed $value ) : mixed
|
Returns
The result of applying a callback to each value in the
map.
|
#
|
public
|
merge(iterable $values): Map
Returns the result of associating all keys of a given traversable
object or array with their corresponding values,…
Returns the result of associating all keys of a given traversable
object or array with their corresponding values, combined with the
current instance.
Parameters
| $values |
A traversable object or an array.
|
Returns
The result of associating all keys of a given traversable
object or array with their corresponding values, combined with the
current instance.
|
#
|
public
|
pairs(): Sequence
Returns a Ds\Sequence containing all the pairs of the map.
Returns a Ds\Sequence containing all the pairs of the map.
Returns
Ds\Sequence containing all the pairs of the map.
|
#
|
public
|
put(mixed $key, mixed $value)
Associates a key with a value, overwriting a previous association if
one exists.
Associates a key with a value, overwriting a previous association if
one exists.
Parameters
| $key |
The key to associate the value with.
|
| $value |
The value to be associated with the key.
|
|
#
|
public
|
putAll(iterable $pairs)
Associates all key-value pairs of a traversable object or array.
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.
Parameters
| $pairs |
traversable object or array.
|
|
#
|
public
|
reduce(callable $callback, mixed $initial)
Reduces the map to a single value using a callback function.
Reduces the map to a single value using a callback function.
Parameters
| $initial |
The initial value of the carry value. Can be
NULL.
|
|
#
|
public
|
remove(mixed $key, mixed $default = null): mixed
Removes and returns a value by key, or return an optional default
value if the key could not be found.
Removes and returns a value by key, or return an optional default
value if the key could not be found.
Parameters
| $key |
The key to remove.
|
| $default |
The optional default value, returned if the key
could not be found.
|
Returns
The value that was removed, or the default value if
provided and the key could not be found in the map.
Throws
|
#
|
public
|
reverse()
Reverses the map in-place.
Reverses the map in-place.
|
#
|
public
|
reversed(): Map
Returns a reversed copy of the map.
Returns a reversed copy of the map.
Returns
A reversed copy of the map.
|
#
|
public
|
skip(int $position): Pair
Returns the pair at a given zero-based position.
Returns the pair at a given zero-based position.
Parameters
| $position |
The zero-based positional index to return.
|
Returns
Returns the Ds\Pair at the given position.
Throws
|
#
|
public
|
slice(int $index, int|null $length = null): Map
Returns a subset of the map defined by a starting index and length.
Returns a subset of the map defined by a starting index and length.
Parameters
| $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.
|
Returns
A subset of the map defined by a starting index and
length.
|
#
|
public
|
sort(callable|null $comparator = null)
Sorts the map in-place by value, using an optional comparator
function.
Sorts the map in-place by value, using an optional comparator
function.
Parameters
| $comparator |
The comparison function must return
an integer less than, equal to, or greater than zero if the first
argument is considered to be respectively less than, equal to, or
greater than the second. Note that before PHP 7.0.0 this integer had
to be in the range from -2147483648 to 2147483647.
|
|
#
|
public
|
sorted(callable|null $comparator = null): Map
Returns a copy, sorted by value using an optional comparator function.
Returns a copy, sorted by value using an optional comparator function.
Parameters
| $comparator |
The comparison function must return
an integer less than, equal to, or greater than zero if the first
argument is considered to be respectively less than, equal to, or
greater than the second. Note that before PHP 7.0.0 this integer had
to be in the range from -2147483648 to 2147483647.
|
|
#
|
public
|
sum(): float|int
Returns the sum of all values in the map.
Returns the sum of all values in the map.
Note: Arrays and objects are considered equal to zero when
calculating the sum.
Returns
The sum of all the values in the map as either a
float or int depending on the values in the map.
|
#
|
public
|
union(Map $map): Map
Creates a new map using values from the current instance and another
map.
Creates a new map using values from the current instance and 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.
Parameters
| $map |
The other map, to combine with the current instance.
|
Returns
A new map containing all the pairs of the current
instance as well as another map.
|
#
|
public
|
values(): Sequence
Returns a sequence containing all the values of the map, in the same
order.
Returns a sequence containing all the values of the map, in the same
order.
Returns
A Ds\Sequence containing all the values of the map.
|
#
|
public
|
xor(Map $map): Map
Creates a new map containing keys of the current instance as well as
another map, but not of both.
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)}
Parameters
Returns
A new map containing keys in the current instance as well
as another map, but not in both.
|
#
|