The Map class

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

Introduction

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.

Class synopsis

Ds\Map implements Ds\Collection {

/* Constants */

const int MIN_CAPACITY = 16 ;

/* Methods */

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 [, array $length ] )

public void sort ([ callable $comparator ] )

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

public number 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 )

}

Predefined Constants

Ds\Map::MIN_CAPACITY

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.