Collections

Table of Contents

The PHP language provides one primary mechanism for expressing containers of elements: the PHP array. Traditionally, the term "array" in programming languages is thought of as a collection of elements, indexed using consecutive integers (starting at 0 or 1), and possibly of a fixed size (e.g., Java). PHP arrays are significantly different than the traditional concept of arrays. A PHP array is essentially a dictionary-style collection associating keys with values that maintains insertion order. The keys can be either integers or strings; the values can be of any type. PHP arrays are dynamically-sized and grow as needed without requiring a function call to increase their size/capacity. In all Hack documentation, the term "array" will be considered to refer to a PHP array unless explicitly noted otherwise. Arrays in PHP are created using the array() language construct. Here are a few examples:

<?php

// Simple array with the values 1, 2, 3 and default
// indexed by integers, starting with 0
$arr1 = array(123);

// Another simple array with the values "a", "b", "c"
// and again default indexed by integers
$arr2 = array("a""b""c");

// Array with strings as both keys and values
$arr3 = array("a" => "aaa""b" => "bbb""c" => "ccc");

// Array containing the values 1, 2, 3 but now indexed
// by a mix of integer keys and string keys
$arr4 = array("foo" => 173 => 2"bar" => 3);

// Array having mixed-typed values, default indexed by
// integers.
$arr5 = array(1"hello", array(23), "goodbye");

// Dynamically grow arrays by just adding new values. The
// keys do not have to be sequential or of the same type.
$arr1[] = 4// The key will be 3
$arr1[4] = 5;
$arr2["bap"] = 6;
$arr3["d"] = "ddd";
$arr4[] = "blah"// The key will be 74
$arr5[9] = 3;

Even with the relatively simple examples above, it is easy to see that PHP arrays are different than the "arrays" in other popular programming languages. In addition to offering dictionary-like operations, PHP arrays also offer stack-like operations. For example, values on PHP arrays can be pushed, popped or shifted.

Hack adds container types and interfaces to PHP. Building on Hack's support for generics, Hack adds first class, built-in parameterized collections such as vectors and maps. Collections are specialized for data storage and retrieval. Collections implement many of the same interfaces and are extendable to create even more specialized collections.

While arrays are geared towards a "one size fits all" model, Hack collections try to provide more specificity in their usage. Like arrays, the values held in a collection can generally be of any type (e.g., the value of a Vector can be a scalar, any PHP object, an array, even another Vector).

Note:

In Hack and PHP5, arrays are not objects. Hack collections are typed as objects. So,

<?hh
$a 
= array(12);
$v Vector {12};
var_dump(is_object($a));
var_dump(is_object($v));

The above example will output:

bool(false)
bool(true)

Currently, Hack implements the following concrete collection types:

  • Vector: An ordered, index-based list collection.

  • ImmVector: An immutable, ordered, index-based list collection.

  • Map: An ordered dictionary-style collection.

  • ImmMap: An immutable, ordered dictionary-style collection.

  • Set: A list-based collection that stores unique values.

  • ImmSet: An immutable, list-based collection that stores unique values.

  • Pair: An index-based collection that can hold exactly two elements.

Note:

All of the above classes are final. You will need to use some sort of composition pattern or define new classes if you want to do something such as add new helper methods.

The primary interfaces implemented by these collections (except Pair) have two incarnations: the normal, read-write interface implemented by the classes above and a read-only interface. The read-write interface is prefixed by Mutable and the read-only interface is prefixed by Const.

Here is an example of using Hack collections:

<?hh

function main_col() {

  
$vector Vector {510};

  
$vector->add(15);
  
$vector->add(20);

  
$vector[] = 25;

  
$vector->removeKey(2);

  foreach (
$vector as $item) {
    echo 
$item "\n";
  }
}

main_col();

The above example will output:

5
10
20
25

To Top