Arrays And Collections: Introduction

Hack includes diverse range of array-like data structures.

Hack arrays are value types for storing iterable data. The types available are vec, dict and keyset. When in doubt, use Hack arrays.

Collections are object types for storing iterable data. The types available include Vector, Map, Set, Pair and helper interfaces.

Quickstart

You can create Hack arrays as follows:

$v = vec[2, 1, 2];

$k = keyset[2, 1];

$d = dict['a' => 1, 'b' => 3];

There are many helpful functions in the C, Vec, Keyset and Dict namespaces.

// The C namespace contains generic functions that are relevant to
// all array and collection types.
C\count(vec[]); // 0
C\is_empty(keyset[]); // true

// The Vec, Keyset and Dict namespaces group functions according
// to their return type.
Vec\keys(dict['x' => 1]); // vec['x']
Keyset\keys(dict['x' => 1]); // keyset['x']

Vec\map(keyset[1, 2], $x ==> $x + 1); // vec[2, 3]

Arrays Cheat Sheet

Operation vec dict keyset
Initialize empty $v = vec[]; $d = dict[]; $k = keyset[];
Literal $v = vec[1, 2, 3]; $d = dict['foo' => 1]; $k = keyset['foo', 'bar'];
From Another Container* $v = vec($container); $d = dict($keyed_container); $k = keyset($container);
Keys from Container* $v = Vec\keys($container); N/A $k = Keyset\keys($container);
Add Elements $v[] = 4; $d['baz'] = 2; $k[] = 'baz';
Bulk Add Elements $v = Vec\concat($t1, $t2) $d = Dict\merge($kt1, $kt2) $k = Keyset\union($t1, $t2)
Remove Elements Remove-at-index is unsupported; Vec\drop($v,$n), Vec\take($v,$n); $first=C\pop_front(inout $x), $last=C\pop_back(inout $x) unset($d['baz']); unset($k['baz']);
Key Existence C\contains_key($v, 1) C\contains_key($d, 'foo') C\contains_key($k, 'foo')
Value Existence C\contains($v, 3) C\contains($d, 2) Use C\contains_key($k, 'foo')
Equality (Order-Dependent) $v1 === $v2 $d1 === $d2 $k1 === $k2
Equality (Order-Independent) N/A Dict\equal($d1, $d2) Keyset\equal($k1, $k2)
Count Elements (i.e., length, size of array) C\count($v) C\count($d) C\count($k)
Type Signature vec<Tv> dict<Tk, Tv> keyset<Tk>
Type Refinement $v is vec<_> $d is dict<_, _> $k is keyset<_>
Awaitable Consolidation Vec\from_async($v) Dict\from_async($d) Keyset\from_async($x)

Arrays Conversion Cheat sheet

Prefer to use Hack arrays whenever possible. When interfacing with legacy APIs that expect older Containers, it may be easier to convert. Here's how:

Converting To Vector To Map To Set
dict N/A new Map($d) N/A
dict keys Vector::fromKeysOf($d) N/A Set::fromKeysOf($d)
dict values new Vector($d) N/A new Set($d)
vec new Vector($v) new Map($v) new Set($v)
keyset new Vector($k) new Map($k) new Set($k)