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.

Maps do not support taking elements by reference. If binding assignment (=&) is used with an element of a Map, or if an element of a Map is passed by reference, of if a Map is used with foreach by reference, an exception will be thrown.

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
• ->__get(mixed $name): mixed
• ->__isset(mixed $name): bool
• ->__set(mixed $name, mixed $value): mixed
• ->__toString(): string
  Returns the string version of the current Map, which is "Map"
• ->__unset(mixed $name): mixed
• ->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(): Rx\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(): Rx\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(): Rx\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
• ->toArray(): array<Tk, Tv>
  Returns an array containing the key/value pairs from the current Map
• ->toDArray(): darray<Tk, Tv>
• ->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