Literal Syntax

Hack adds special syntax for creating instances of collection classes, called collection literal syntax. It consists of the name of the class, followed by a brace-enclosed list of items. The items are separated by commas. In Map literals, each item is the key, followed by =>, followed by the value, just as in PHP array literal syntax:

$vector = Vector {'one', 'two', 'three'};
$map = Map {'one' => 1, 'two' => 2, 'three' => 3};
$set = Set {'one', 'two', 'three'};
$pair = Pair {'one', 'two'};

Collection literal syntax is allowed in any position where regular PHP array() syntax is allowed, including in the initializer expressions of object and class properties. This is the reason why it exists: even though collection literal syntax entails object creation (which usually isn’t allowed in these positions), it is legal anywhere array() is legal. For example:

class Pluralizer {
  private static Map<string, string> $cache = Map {};
}

Collection literals in this position are not allowed to contain any expression that is itself not allowed in this position. array() syntax has the same restriction. For example, this is not valid syntax, because function calls are not valid class property initializers:

class Pluralizer {
  // Syntax error
  private static Map<string, string> $cache =
    Map {'child' => fetch_plural_from_db('child')};
}

Note that although the collection classes are generic, there are no type arguments in literal syntax:

$vec = Vector<int> {1, 2, 3};  // Syntax error

Instead, the typechecker will silently track the types of the collection’s contents, and only check for errors when you pass the collection through a type annotation (e.g., by assigning it to a property with a type annotation). See “Unresolved Types, Revisited” for full details.

Reading and Writing

The square-bracket syntax that you use with arrays is also what you use with Vector, Map, and Pair:

$vector = Vector {'zero', 'one', 'two'};
echo $vector[1];  // Prints 'one'

$map = Map {};
$map['zero'] = 0;

$pair = Pair {'first', 'second'};
echo $pair[0];  // Prints 'first'

If you try to read an element that doesn’t exist, or to set an element in a Vector that is beyond the Vector’s bounds, an OutOfBoundsException will be thrown. Accessing elements by reference (as in $ref = &$array[0] in regular PHP) is not allowed with collections; doing so results in a fatal error.

You can’t use this syntax to modify Sets. You can use it to read from Sets, but you shouldn’t. The most common operation on a Set is to test whether a value is in it, and the square-bracket syntax is unsuitable for that: if the value is not in the Set, it will throw an OutOfBoundsException. For membership testing, use the contains() method (see “Type Annotations for Collections”) instead:

if ($the_list->contains($user_id)) {
  echo "You're on the list";
}

Arrays have a quirky behavior wherein keys that are strings containing the representation of an integer² are treated as the integer instead. For example:

$array = array('3' => 'three');
echo $array[3];  // Prints 'three'

$array = array(3 => 'three');
echo $array['3'];  // Prints 'three'

Hack collections do not do this. Map and Set treat the string "3" and the integer 3 as distinct keys, and if you use anything other than an integer to index into a Vector or Pair, an InvalidArgumentException will be thrown.

To test whether a key exists in a Map or an element exists in a Set, you can use the containsKey() and contains() methods, respectively:

$map = Map {'one' => 'un', 'two' => 'deux'};
if ($map->containsKey('two')) {
  echo "We know how to say 'two' in French!";
}

$set = Set {'one', 'two'};
if ($set->contains('one')) {
  echo "'one' is in the set";
}

You can also use isset and empty to test if a key or element exists, but you should always use containsKey() or contains() if possible. isset and empty aren’t allowed in Hack strict mode—see “isset, empty, and unset” for the reasons why. The only reason you may want to use them on collections is so that you can write code that accepts both arrays and collections seamlessly.

Like empty arrays, empty collections of any type evaluate to false when converted to bool. In particular, they’re treated as false in conditional statements like if and while, and in ternary expressions:

$vector = Vector {};
if ($vector) {
  // Code in here will not be executed
}

$description = ($vector ? (string)$vector : '[none]');

$vector = Vector {'zero', 'one'};
foreach ($vector as $value) {
  echo $value;
}

$map = Map {'one' => 'un', 'two' => 'deux'};
foreach ($map as $eng => $fr) {
  echo $eng . ' in French is ' . $fr;
}

// Old code with array
$array = array(0, 1, 2);
foreach ($array as &$value) {
  $value *= 10;
}

// Equivalent code with Vector
$vector = Vector {0, 1, 2};
foreach ($vector as $index => $value) {
  $vector[$index] = $value * 10;
}

$vector = Vector {'zero'};
$vector[] = 'one';
print_r($vector);  // Prints: "HHVector Object( [0] => zero, [1] => one )"

$set = Set {'eins'};
$set[] = 'eins';  // Value is already in $set; nothing happens
print_r($set);    // Prints: "HHSet Object( eins )"

$map = Map {};
$map[] = Pair {'one', 'eins'};
print_r($map)  // Prints: "HHMap Object( [one] => eins )"

$vec = Vector {'first', 'second', 'third'};
$vec->removeKey(1);
print_r($vec);  // Prints: "HHVector Object( [0] => first, [1] => third )"

$map = Map {'one' => 'un', 'two' => 'deux'};
unset($map['one']);
print_r($map);  // Prints: "HHMap Object( [two] => deux )"

$arr = array('zero', 'one', 'two');
unset($arr[1]);
print_r($arr);  // Prints: "Array( [0] => zero, [2] => two )"

$vector = Vector {1, 2};
$another_variable = $vector;
var_dump($vector === $another_variable);  // true

$other = Vector {1, 2};
var_dump($vector === $other);  // false

$vector = Vector {'one', 'two'};
list($one, $two) = $vector;

$map = Map {1 => 'one', 0 => 'zero'};
list($zero, $one) = $map;  // $zero is 'zero' and $one is 'one'

Core Interfaces

The core collection interfaces are:

Traversable<T>

Anything that can be iterated over using foreach without a key is Traversable. Within such a foreach, the iteration variable will have type T. This is the only thing Traversable guarantees; it does not declare any methods.

The most important thing about Traversable is that regular PHP arrays are Traversable. This is unusual, because arrays are not objects and, in general, only objects can implement interfaces. Traversable is special-cased in the runtime to have this behavior.

In addition to arrays and collections, Traversable includes objects that implement Iterator.

Traversable can help bridge the gap between arrays and collections. If the only thing you do with a function argument is iterate over it using foreach without a key, irrespective of whether it’s an array, a collection, or something else, you should annotate it as Traversable.

Note that if you’re implementing your own class that you want to be usable with foreach, you should not make it implement Traversable. Use Iterable (described shortly) instead.

KeyedTraversable<Tk, Tv> extends Traversable<Tv>

KeyedTraversable is similar to Traversable, but additionally indicates that it’s valid to include a key in the foreach statement. Regular PHP arrays are KeyedTraversable. The following example shows the difference between Traversable and KeyedTraversable:

function notKeyed(Traversable<T> $traversable): void {
  // Not valid
  foreach ($traversable as $key => $value) {
    // ...
  }
}

function keyed(KeyedTraversable<Tk, Tv> $traversable): void {
  // Valid
  foreach ($traversable as $key => $value) {
    // $key is of type Tk
    // $value is of type Tv
  }
}

Container<T> extends Traversable<T>

Container is exactly like Traversable, except that it does not include objects that implement Iterator. In other words, it includes only arrays and instances of collection classes. The only thing you can do with a Container is to iterate over it with foreach.

KeyedContainer<Tk, Tv> extends KeyedTraversable<Tk, Tv>

Similarly, KeyedContainer is like KeyedTraversable, except that it is restricted to arrays and collection classes other than Set and ImmSet.

Indexish<Tk, Tv> extends KeyedTraversable<Tk, Tv>

Indexish signifies anything that can be indexed into using square-bracket syntax: $indexish[$key]. It declares no methods. Like Traversable and KeyedTraversable, it is a special interface that is “implemented” by arrays as well as collections and other objects that support this syntax.

IteratorAggregate<T> extends Traversable<T>

This interface is for objects that can produce an Iterator object to iterate over their contents. Unlike the previous three interfaces, it is not implemented by arrays. It’s very unlikely that you’ll ever use IteratorAggregate in type annotations—either Iterable or Traversable is probably more appropriate. The interface declares a single method:

• getIterator(): Iterator<T> returns an iterator over the object’s contents. The Iterator interface is the one from standard PHP.

Iterable<T> extends IteratorAggregate<T>

This is where the real capabilities of collections begin to come in. The Iterable interface declares several methods:

• toArray(): array converts the collection to an array. Note that the return value does not have a type argument: it’s simply array instead of array<T>.

• toValuesArray(): array converts the collection to an array but discards the keys, replacing them with the integers 0 to n–1, in order.

• toVector(): Vector<T> converts the collection to a Vector. This is very similar to toValuesArray(); if the collection has keys (i.e., is a Map), the keys will be discarded.

• toImmVector(): ImmVector<T>: converts to an immutable Vector.

• toSet(): Set<T> converts the collection to a Set, discarding the keys, if any.

• toImmSet(): ImmSet<T> converts to an immutable Set.

• values(): Iterable<T> returns an Iterable object yielding the collection’s values (discarding keys).

• map<Tm>(function(T): Tm $callback): Iterable<Tm> returns an Iterable object yielding the collection’s values after they have been passed through the given function. It is much like the standard PHP array_map() function. Here’s an example that multiplies the elements of a Vector by 10:

  $nums = Vector {1, 2, 3};
  print_r($nums->map(function($x) { return $x * 10; }));

  HHVector Object
  (
      [0] => 10
      [1] => 20
      [2] => 30
  )

• filter(function(T): bool $callback): Iterable<T> returns an Iterable object yielding the values from the collection that make the given function return true. Here’s an example of picking out even numbers from a Vector:

  $nums = Vector {1, 2, 3, 4};
  print_r($nums->filter(function($x) { return $x % 2 === 0; }));

  HHVector Object
  (
      [0] => 2
      [1] => 4
  )

• zip<Tz>(Traversable<Tz> $traversable): Iterable<Pair<T, Tz>> returns an Iterable object that pairs up the values from this collection and the values from the passed-in Traversable. An example is the best way to explain it:

  $english = Vector {'one', 'two', 'three'};
  $french = Vector {'un', 'deux', 'trois'};
  print_r($english->zip($french));

  This will output:

  HHVector Object
  (
      [0] => HHPair Object
          (
              [0] => one
              [1] => un
          )
  
      [1] => HHPair Object
          (
              [0] => two
              [1] => deux
          )
  
      [2] => HHPair Object
          (
              [0] => three
              [1] => trois
          )
  
  )

  If the two collections have different counts, the resulting Iterable will have the smaller count.

KeyedIterable<Tk, Tv> extends Iterable<Tv>

This is analogous to Iterable, but with the key’s type included. It adds some new methods and overrides some from Iterable with different return types. The new methods are listed first:

• toKeysArray(): array returns an array of the Iterable’s keys.

• toMap(): Map<Tk, Tv> returns the Iterable converted to a Map.

• keys(): Iterable<Tk>* returns an Iterable over this Iterable’s keys.

• mapWithKey<Tm>(function(Tk, Tv): Tm $callback): KeyedIterable<Tk, Tm> is like map() but passes keys to the callback function as well as values.

• filterWithKey(function(Tk, Tv): bool $callback): KeyedIterable<Tk, Tv> is like filter() but passes keys to the callback function as well as values.

• getIterator(): KeyedIterator<Tk, Tv> is an override with a more specific return type.

• map<Tm>(function(T): Tm $callback): KeyedIterable<Tk, Tu> is an override with a more specific return type.

• filter(function(T): bool $callback): Iterable<T> is an override with a more specific return type.

• zip<Tz>(Traversable<Tz> $traversable): Iterable<Pair<T, Tz>> is an override with a more specific return type.

General Collection Interfaces

There are three core interfaces that declare the most basic collection functionality. You’ll essentially never use these in type annotations, as they’re too nonspecific to be useful that way, but we’ll look at them here to learn these core functions:

ConstCollection<T>

A read-only collection of values of type T. It says nothing about uniqueness of values, ordering, underlying implementation, or anything.

Every concrete collection class implements this interface (indirectly). It may seem unsuitable for Map, because it only has one type parameter and Map needs two (one for keys and one for values), but Maps do implement ConstCollection: a Map with key type Tk and value type Tv implements ConstCollection<Pair<Tk, Tv>>.

This interface declares three methods:

• count(): int returns the number of values in the collection.

• isEmpty(): bool returns whether the collection is empty.

• items(): Iterable<T> returns a value that can be iterated over using foreach, and will yield every value in the collection.

OutputCollection<T>

This interface declares two methods that allow adding values to the collection (every mutable collection class implements this):

• add(T $value): this adds the given value to the collection and returns the collection itself.

• addAll(?Traversable<T> $values): this iterates over the given Traversable and adds each resulting value to the collection. It returns the collection itself.

Collection<T> extends ConstCollection<T>, OutputCollection<T>

This interface declares no methods; it just serves to combine the read-only behavior of ConstCollection and the write-only behavior of OutputCollection.

Specific Collection Interfaces

Now, at last, we’ll get into specific collection functionality. We’ll look at six collection interfaces and the methods they declare.³ They’re meant to describe functionality independent of implementation. For now, there’s only one concrete implementation of each, but there may be others in the future—for example, one can imagine a linked list–based class that implements MutableVector.

All of these interfaces either directly or indirectly extend KeyedIterable, which declares several methods with KeyedIterable as their return type, such as map() and filter(). All of these interfaces override such methods with specific return types—for example, ConstVector<T> declares filter(function(T): bool $callback): ConstVector<T>. These overridden methods are omitted in the following list:

ConstSet<T> extends ConstCollection<T>, KeyedIterable<mixed, T>

This represents a read-only set of values of type T.⁴ It declares only one method directly:

• contains(T $value): bool returns whether the given value is in the set. The semantics are the same as === comparison: the result is true if and only if there is a value `in the set that compares identical to $value using ===.

MutableSet<T> extends ConstSet<T>, Collection<T>

This represents a modifiable set of values of type T. It extends ConstSet and declares two methods directly:

• clear(): this removes all values from the set, and returns the set.

• remove(T $value): this removes the given value from the set (doing nothing if the value is not in the set), and returns the set. As with contains(), the semantics are the same as === comparison.

ConstVector<T> extends ConstCollection<T>, KeyedIterable<int, T>

This represents a read-only sequence of values of type T, indexed by integers. It declares three methods directly:

• at(int $index): T returns the value at the given index, or throws an exception if the index is out of bounds.

• containsKey(int $index): bool returns whether the given index is in bounds.

• get(int $index): ?T returns the value at the given index, or null if the index is out of bounds.

MutableVector<T> extends ConstVector<T>, Collection<T>

This represents a modifiable sequence of values of type T. It extends ConstVector and adds these methods:

• clear(): this removes all values from the vector.

• removeKey(int $index): this removes the value at the given index. In line with vector semantics, the values at higher indices will all be shifted down by one, so that the indices remain contiguous.

• set(int $index, T value): this sets the given value at the given index, throwing an exception if the index is out of bounds. If you want to extend the vector, use add().

• setAll(KeyedTraversable<int, T> $kt): this iterates over the given KeyedTraversable and calls set() with each key/value pair in it.

ConstMap<Tk, Tv> extends ConstCollection<Pair<Tk, Tv>>, KeyedIterable<Tk, Tv>

This represents a read-only mapping of keys of type Tk to values of type Tv. It declares methods that resemble those of ConstSet and ConstVector:

• at(Tk $key): Tv returns the value for the given key, or throws an exception if the key isn’t in the map.

• contains(Tk $key): bool returns whether the given key exists in the map.

• containsKey(Tk $key): bool is the same as contains(). The duplication of methods is just a quirk of the inheritance hierarchy of these interfaces.

• get(Tk $key): ?Tv returns the value for the given key, or null if the key isn’t in the map.

MutableMap<Tk, Tv> extends ConstMap<Tk, Tv>

This represents a modifiable mapping of keys to values. Again, the methods that it declares are a combination of the methods from MutableVector and MutableSet:

• clear(): this removes all keys and values from the map.

• remove(Tk $key): this removes the value at the given key.

• removeKey(Tk $key): this is exactly the same as remove().

• set(Tk $key, Tv $value): this sets the given value at the given key.

• setAll(KeyedTraversable<Tk, Tv> $kt): this iterates over the given KeyedTraversable and calls set() with each key/value pair in it.

Concrete Collection Classes

Finally, to bring all this together, we’ll look at the full type-annotated APIs to all the collection classes. Each one implements one of the six interfaces from the previous section, and adds a few more useful methods.

Only methods defined by the classes themselves, and not declared by any of the interfaces we just saw, are listed here:

ImmVector<T> implements ConstVector<T>

• __construct(?Traversable<T> $values) creates a new ImmVector with the contents of the given Traversable.

• linearSearch(T $value): int performs a linear search for the given value within the ImmVector and returns the index at which the value was found, or -1 if it wasn’t found.

• __toString(): string just returns "ImmVector".

Vector<T> implements MutableVector<T>

• __construct(?Traversable<T> $values) creates a new Vector with the contents of the given Traversable.

• linearSearch(T $value): int performs a linear search for the given value within the Vector and returns the index at which the value was found, or -1 if it wasn’t found.

• pop(): T removes the last value from the Vector and returns it.

• reserve(int $size): void hints to the Vector that it should reallocate memory to hold the given number of values. The Vector may not do exactly that; this is just a hint.

• resize(int $size, T $value): void changes the size of the Vector to the passed size. If the new size is smaller than the current size, values at the end of the Vector are removed. If the new size is larger, the new values are set to $value.

• reverse(): void reverses the Vector in place.

• shuffle(): void randomly rearranges the values in the Vector.

• splice(int $offset, ?int $len = NULL): void removes $len values from the Vector, starting at $offset. If $len is not passed, it removes every value from $offset to the end of the Vector. This is similar to the built-in function array_splice().

• __toString(): string just returns "Vector".

ImmSet<T> implements ConstSet<T>

• __construct(?Traversable<T> $values) creates a new ImmSet with the contents of the given Traversable.

• fromArrays(...): ImmSet<T> is a static method that takes a variable number of arguments, which must all be arrays, and creates an ImmSet from all their contents.

• fromItems(?Traversable<T> $items): ImmSet<T> is a static method that creates an ImmSet from the given Traversable.

• __toString(): string just returns "ImmSet".

Set<T> implements MutableSet<T>

• __construct(?Traversable<T> $values) creates a new ImmSet with the contents of the given Traversable.

• fromArrays(...): Set<T> is a static method that takes a variable number of arguments, which must all be arrays, and creates an ImmSet from all their contents.

• fromItems(?Traversable<T> $items): Set<T> is a static method that creates an ImmSet from the given Traversable.

• removeAll(?Traversable<T> $values): Set<T> removes all the values in the given Traversable from the set, and returns the set itself.

• __toString(): string just returns "Set".

ImmMap<Tk, Tv> implements ConstMap<Tk, Tv>

• __construct(?KeyedTraversable<Tk, Tv> $values) creates a new ImmMap with the contents of the given Traversable.

• fromItems(?Traversable<Pair<Tk, Tv>> $items): ImmMap<T> is a static method that creates an ImmMap from the given Traversable.

• __toString(): string just returns "ImmMap".

Map<Tk, Tv> implements MutableMap<Tk, Tv>

• __construct(?KeyedTraversable<Tk, Tv> $values) creates a new ImmMap with the contents of the given Traversable.

• fromItems(?Traversable<Pair<Tk, Tv>> $items): ImmMap<T> is a static method that creates an ImmMap from the given Traversable.

• __toString(): string just returns "Map".

Conversion to Arrays

All Hack collections can be converted to arrays with a cast expression, or with the toArray() method:

$vector = Vector {'first', 'second'};
print_r((array)$vector);      // Prints: Array( [0] => first, [1] => second )
print_r($vector->toArray());  // Same

The conversions are straightforward:

• Vectors and ImmVectors convert to arrays where the keys are the integer indices of the values, in the same order.

• Maps and ImmMaps convert to arrays with the same key/value pairs, in the same order.

• Sets and ImmSets convert to arrays with each key mapping to itself, in the same order.

• Pairs convert to arrays with the keys 0 and 1 (integers) in that order, mapping to the corresponding values.

There is a small wrinkle in the case of integer-like string keys (see “Reading and Writing”) in Maps and Sets. If the Map or Set contains keys that conflict with each other in this way, an E_WARNING-level error will be raised. The conflicting keys will reduce to one integer key in the resulting array, and it will map to the last value under the conflicting keys:

<?php
$map = Map {10 => 'int', '10' => 'string'};
$array = (array)$map;
// Warning: Map::toArray() for a map containing both int(10) and string('10')
var_dump($array);  // Prints: array(1) { [10]=> string(6) "string" }

$set = Set {10, "10"}
$array = (array)$set;
// Warning: Set::toArray() for a map containing both int(10) and string('10')
var_dump($array);  // Prints: array(1) { [10]=> string(2) "10" }

Use with Built-In and User Functions

Hack has a lot of built-in functions that can take arrays as arguments. There are several different ways in which these have been adapted to work with collections.

function examine(array $items) {
  if (is_array($items)) {
    echo "It's an array!";
  }
}

examine(Vector {1, 2, 3});

Notice: Argument 1 to examine() must be of type array, HHVector given;
argument 1 was implicitly cast to array
It's an array!