HH\Map

Map is an ordered dictionary-style collection

HHVM provides a native implementation for this class. The PHP class definition below is not actually used at run time; it is simply provided for the typechecker and for developer reference.

Like all objects in PHP, Maps have reference-like semantics. When a caller passes a Map to a callee, the callee can modify the Map and the caller will see the changes. Maps do not have "copy-on-write" semantics.

Maps preserve insertion order of key/value pairs. When iterating over a Map, the key/value pairs appear in the order they were inserted. Also, Maps do not automagically convert integer-like string keys (ex. "123") into integer keys.

Maps only support int keys and string keys. If a key of a different type is used, an exception will be thrown.

Maps support $m[$k] style syntax for getting and setting values by key. Maps also support isset($m[$k]) and empty($m[$k]) syntax, and they provide similar semantics as arrays. Adding an element with square bracket syntax [] is supported either by providing a key between the brackets or a Pair on the right-hand side. e.g., $m[$k] = $v is supported $m[] = Pair {$k, $v} is supported $m[] = $v is not supported.

Maps do not support iterating while new keys are being added or elements are being removed. When a new key is added or an element is removed, all iterators that point to the Map shall be considered invalid.

Guides

• Introduction
• Classes

Interface Synopsis

namespace HH;

final class Map implements \MutableMap<Tk, Tv> {...}

Public Methods

• ::fromArray(darray<Tk, Tv> $arr): Map<Tk, Tv>
  Returns a Map containing the key/value pairs from the specified array
• ::fromItems(?Traversable<Pair<Tk, Tv>> $iterable): Map<Tk, Tv>
  Creates a Map from the given Traversable, or an empty Map if null is passed
• ->__construct(?KeyedTraversable<Tk, Tv> $iterable = NULL): void
  Creates a Map from the given KeyedTraversable, or an empty Map if null is passed
• ->__toString(): string
  Returns the string version of the current Map, which is "Map"
• ->add(Pair<Tk, Tv> $val): Map<Tk, Tv>
  Add a key/value pair to the end of the current Map
• ->addAll(?Traversable<Pair<Tk, Tv>> $iterable): Map<Tk, Tv>
  For every element in the provided Traversable, add a key/value pair into the current Map
• ->at(Tk $key): Tv
  Returns the value at the specified key in the current Map
• ->clear(): Map<Tk, Tv>
  Remove all the elements from the current Map
• ->concat<Tu super Tv>(Traversable<Tu> $traversable): Vector<Tu>
  Returns a Vector that is the concatenation of the values of the current Map and the values of the provided Traversable
• ->contains(mixed $key): bool
  Determines if the specified key is in the current Map
• ->containsKey(mixed $key): bool
  Determines if the specified key is in the current Map
• ->count(): int
  Provides the number of elements in the current Map
• ->differenceByKey(KeyedTraversable<Tk, Tv> $traversable): Map<Tk, Tv>
  Returns a new Map with the keys that are in the current Map, but not in the provided KeyedTraversable
• ->filter((function(Tv): bool) $callback): Map<Tk, Tv>
  Returns a Map containing the values of the current Map that meet a supplied condition
• ->filterWithKey((function(Tk, Tv): bool) $callback): Map<Tk, Tv>
  Returns a Map containing the values of the current Map that meet a supplied condition applied to its keys and values
• ->firstKey(): ?Tk
  Returns the first key in the current Map
• ->firstValue(): ?Tv
  Returns the first value in the current Map
• ->get(Tk $key): ?Tv
  Returns the value at the specified key in the current Map
• ->getIterator(): KeyedIterator<Tk, Tv>
  Returns an iterator that points to beginning of the current Map
• ->immutable(): ImmMap<Tk, Tv>
  Returns a deep, immutable copy (ImmMap) of this Map
• ->isEmpty(): bool
  Checks if the current Map is empty
• ->items(): Iterable<Pair<Tk, Tv>>
  Returns an Iterable view of the current Map
• ->keys(): Vector<Tk>
  Returns a Vector containing the keys of the current Map
• ->lastKey(): ?Tk
  Returns the last key in the current Map
• ->lastValue(): ?Tv
  Returns the last value in the current Map
• ->lazy(): KeyedIterable<Tk, Tv>
  Returns a lazy, access elements only when needed view of the current Map
• ->map<Tu>((function(Tv): Tu) $callback): Map<Tk, Tu>
  Returns a Map after an operation has been applied to each value in the current Map
• ->mapWithKey<Tu>((function(Tk, Tv): Tu) $callback): Map<Tk, Tu>
  Returns a Map after an operation has been applied to each key and value in the current Map
• ->remove(Tk $key): Map<Tk, Tv>
  Removes the specified key (and associated value) from the current Map
• ->removeKey(Tk $key): Map<Tk, Tv>
  Removes the specified key (and associated value) from the current Map
• ->reserve(int $sz): void
  Reserves enough memory to accommodate a given number of elements
• ->retain(mixed $callback): Map
  Ensures that this Map contains only keys/values for which the specified callback returns true when passed the value
• ->retainWithKey(mixed $callback): Map
  Ensures that this Map contains only keys/values for which the specified callback returns true when passed the key and the value
• ->set(Tk $key, Tv $value): Map<Tk, Tv>
  Stores a value into the current Map with the specified key, overwriting the previous value associated with the key
• ->setAll(?KeyedTraversable<Tk, Tv> $iterable): Map<Tk, Tv>
  For every element in the provided Traversable, stores a value into the current Map associated with each key, overwriting the previous value associated with the key
• ->skip(int $n): Map<Tk, Tv>
  Returns a Map containing the values after the n-th element of the current Map
• ->skipWhile((function(Tv): bool) $fn): Map<Tk, Tv>
  Returns a Map containing the values of the current Map starting after and including the first value that produces true when passed to the specified callback
• ->slice(int $start, int $len): Map<Tk, Tv>
  Returns a subset of the current Map starting from a given key location up to, but not including, the element at the provided length from the starting key location
• ->take(int $n): Map<Tk, Tv>
  Returns a Map containing the first n key/values of the current Map
• ->takeWhile((function(Tv): bool) $callback): Map<Tk, Tv>
  Returns a Map containing the keys and values of the current Map up to but not including the first value that produces false when passed to the specified callback
• ->toDArray(): darray<Tk, Tv>
  Returns a darray built from the keys and values from this Map
• ->toImmMap(): ImmMap<Tk, Tv>
  Returns a deep, immutable copy (ImmMap) of the current Map
• ->toImmSet(): ImmSet<Tv>
  Returns an immutable set (ImmSet) based on the values of the current Map
• ->toImmVector(): ImmVector<Tv>
  Returns an immutable vector (ImmVector) with the values of the current Map
• ->toKeysArray(): varray<Tk>
  Returns an array whose values are the keys of the current Map
• ->toMap(): Map<Tk, Tv>
  Returns a deep copy of the current Map
• ->toSet(): Set<Tv>
  Returns a Set based on the values of the current Map
• ->toVArray(): varray<Tv>
• ->toValuesArray(): varray<Tv>
  Returns an array containing the values from the current Map
• ->toVector(): Vector<Tv>
  Returns a Vector with the values of the current Map
• ->values(): Vector<Tv>
  Returns a Vector containing the values of the current Map
• ->zip<Tu>(Traversable<Tu> $traversable): Map<Tk, Pair<Tv, Tu>>
  Returns a Map where each value is a Pair that combines the value of the current Map and the provided Traversable