The Map class

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

class Ds\Map implements Ds\Collection, ArrayAccess {

/* Constants */

const int Ds\Map::MIN_CAPACITY = 16;

/* Methods */

public void allocate(int $capacity)

public void apply(callable $callback)

public int capacity()

public void clear()

public Ds\Map copy()

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

public Ds\Map filter(callable $callback = ?)

public Ds\Pair first()

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

public Ds\Set keys()

public void ksort(callable $comparator = ?)

public Ds\Map ksorted(callable $comparator = ?)

public Ds\Pair last()

public Ds\Map map(callable $callback)

public Ds\Map merge(mixed $values)

public Ds\Sequence pairs()

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

public Ds\Map reversed()

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

public array toArray()

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

public Ds\Sequence values()

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

}

Predefined Constants

Ds\Map::MIN_CAPACITY

Changelog

Version	Description
PECL ds 1.3.0	The class now implements ArrayAccess.

Table of Contents

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