Shapes: Functions

The internal, abstract final class Shapes provides some static methods that can operate on a shape of any type. These methods are described below:

idx()

public static function idx(S $shape, arraykey $index) : ?Tv; 
public static function idx(S $shape, arraykey $index, Tv $default) : Tv; 

This method searches shape $shape (whose type is designated here as S) for the field named $index. If the field exists, its value is returned; otherwise, a default value is returned. For a field of type T, the function returns a value of type ?T. A default value $default can be provided; however, if that argument is omitted, the value null is used. $index must be a single-quoted string or a class constant of type string or int.

<?hh

namespace Hack\UserDocumentation\Shapes\Functions\Examples\fIdx;

class C {
  const string KEYX = 'x';
  const string KEYY = 'y';
  const int KEYINTX = 10;
  const int KEYINTY = 23;
  const int KEYINTZ = 50;
}

function run(): void {
  echo "======== Shapes::idx ========\n";

  $s = shape('x' => 10, 'y' => 20);

  $v = Shapes::idx($s, 'x');    // field exists, return 10
  echo "\$v = " . (($v == null)? "null" : $v) ."\n";

  $v = Shapes::idx($s, 'y');    // field exists, return 20
  echo "\$v = " . (($v == null)? "null" : $v) ."\n";

  // field does not exist; return implict default, null
  $v = Shapes::idx($s, 'z');
  echo "\$v = " . (($v == null)? "null" : $v) ."\n";

  // field does not exist; return explicit default, -99
  $v = Shapes::idx($s, 'z', -99);
  echo "\$v = " . (($v == null)? "null" : $v) ."\n";

  echo "----------------------------\n";

  $s = shape(C::KEYINTX => 10, C::KEYINTY => 20);

  $v = Shapes::idx($s, C::KEYINTX);   // field exists, return 10
  echo "\$v = " . (($v == null)? "null" : $v) ."\n";

  $v = Shapes::idx($s, C::KEYINTY); // field exists, return 20
  echo "\$v = " . (($v == null)? "null" : $v) ."\n";

  // field does not exist; return implict default, null
  $v = Shapes::idx($s, C::KEYINTZ);
  echo "\$v = " . (($v == null)? "null" : $v) ."\n";

  // field does not exist; return explicit default, -99
  $v = Shapes::idx($s, C::KEYINTZ, -99);
  echo "\$v = " . (($v == null)? "null" : $v) ."\n";
}

run();
Output
======== Shapes::idx ========
$v = 10
$v = 20
$v = null
$v = -99
----------------------------
$v = 10
$v = 20
$v = null
$v = -99

keyExists()

public static function keyExists(S $shape, arraykey $index): bool; 

This method searches shape $shape (whose type is designated here as S) for the field named $index. If the field exists, true is returned; otherwise, false is returned. $index must be a single-quoted string or a class constant of type string or int.

<?hh

namespace Hack\UserDocumentation\Shapes\Functions\Examples\fKeyExists;

class C {
  const string KEYX = 'x';
  const string KEYY = 'y';
  const int KEYINTX = 10;
  const int KEYINTY = 23;
  const int KEYINTZ = 50;
}

function run(): void {
  echo "\n======== Shapes::keyExists ========\n\n";

  $s = shape('id' => "23456", 'url' => "www.example.com", 'count' => 23);

  $v = Shapes::keyExists($s, 'url');    // field exists, return true
  echo "keyExists(\$s, 'x') = " . $v ."\n";

  $v = Shapes::keyExists($s, 'name');   // does not exist, return false
  echo "keyExists(\$s, 'name') = " . $v ."\n";
}

run();
Output
======== Shapes::keyExists ========

keyExists($s, 'x') = 1
keyExists($s, 'name') =

removeKey()

public static function removeKey(S $shape, arraykey $index): void; 

Given a shape $shape (whose type is designated here as S) and a field name $index, this method removes the specified field from that shape. If the field specified does not exist, the removal request is ignored. $index must be a single-quoted string or a class constant of type string or int.

<?hh

namespace Hack\UserDocumentation\Shapes\Functions\Examples\fRemoveKey;

class C {
  const string KEYX = 'x';
  const string KEYY = 'y';
  const int KEYINTX = 10;
  const int KEYINTY = 23;
  const int KEYINTZ = 50;
}

function run(): void {
  echo "\n======== Shapes::removeKey ========\n\n";

  $s = shape();
  var_dump($s);
  Shapes::removeKey($s, 'name');  // no such field, so request ignored
  $a = Shapes::toArray($s);
  echo "# elements in array = " . count($a) . "\n";
  var_dump($s, $a);
  echo "----------------------------\n";

  $s = shape('x' => 10, 'y' => 20);
  var_dump($s);
  Shapes::removeKey($s, C::KEYX); // field 'x' removed
  $a = Shapes::toArray($s);
  echo "# elements in array = " . count($a) . "\n";
  var_dump($s, $a);
  echo "----------------------------\n";

  $s = shape('id' => "23456", 'url' => "www.example.com", 'count' => 23);
  var_dump($s);
  Shapes::removeKey($s, 'url');   // field 'url' removed
  $a = Shapes::toArray($s);
  echo "# elements in array = " . count($a) . "\n";
  var_dump($s, $a);
}

run();
Output
======== Shapes::removeKey ========

array(0) {
}
# elements in array = 0
array(0) {
}
array(0) {
}
----------------------------
array(2) {
  ["x"]=>
  int(10)
  ["y"]=>
  int(20)
}
# elements in array = 1
array(1) {
  ["y"]=>
  int(20)
}
array(1) {
  ["y"]=>
  int(20)
}
----------------------------
array(3) {
  ["id"]=>
  string(5) "23456"
  ["url"]=>
  string(15) "www.example.com"
  ["count"]=>
  int(23)
}
# elements in array = 2
array(2) {
  ["id"]=>
  string(5) "23456"
  ["count"]=>
  int(23)
}
array(2) {
  ["id"]=>
  string(5) "23456"
  ["count"]=>
  int(23)
}

toArray()

public static function toArray(S $shape): array<arraykey, mixed>; 

This method returns an array of type array<arraykey, mixed> containing one element for each field in the shape $shape. Each element's key and value are the name and value, respectively, of the corresponding field. The order of the elements in the array is the same as the order in which the fields were inserted into the shape.

<?hh

namespace Hack\UserDocumentation\Shapes\Functions\Examples\fToArray;

class C {
  const string KEYX = 'x';
  const string KEYY = 'y';
  const int KEYINTX = 10;
  const int KEYINTY = 23;
  const int KEYINTZ = 50;
}

function run(): void {
  echo "\n======== Shapes::toArray ========\n\n";

  $s = shape();
  $a = Shapes::toArray($s);   // returns an array of 0 elements
  echo "# elements in array = " . count($a) . "\n";
  var_dump($s, $a);
  echo "----------------------------\n";

  $s = shape('x' => 10, 'y' => 20);
  $a = Shapes::toArray($s);
  echo "# elements in array = " . count($a) . "\n";
  var_dump($s, $a);
  echo "----------------------------\n";

  $s = shape('y' => 20, 'x' => 10);
  $a = Shapes::toArray($s);
  echo "# elements in array = " . count($a) . "\n";
  var_dump($s, $a);
  echo "----------------------------\n";

  $s = shape('id' => "23456", 'url' => "www.example.com", 'count' => 23);
  // returns an array of 3 elements, of type string, string, and int, respectively
  $a = Shapes::toArray($s);
  echo "# elements in array = " . count($a) . "\n";
}

run();
Output
======== Shapes::toArray ========

# elements in array = 0
array(0) {
}
array(0) {
}
----------------------------
# elements in array = 2
array(2) {
  ["x"]=>
  int(10)
  ["y"]=>
  int(20)
}
array(2) {
  ["x"]=>
  int(10)
  ["y"]=>
  int(20)
}
----------------------------
# elements in array = 2
array(2) {
  ["y"]=>
  int(20)
  ["x"]=>
  int(10)
}
array(2) {
  ["y"]=>
  int(20)
  ["x"]=>
  int(10)
}
----------------------------
# elements in array = 3