hphp/hack/hhi/collections/ImmMap.hhi

   1 <?hh
   2 /**
   3  * Copyright (c) 2014, Facebook, Inc.
   4  * All rights reserved.
   5  *
   6  * This source code is licensed under the MIT license found in the
   7  * LICENSE file in the "hack" directory of this source tree.
   8  *
   9  */
  10 <<file:__EnableUnstableFeatures('readonly')>>
  11
  12 /**
  13  * This file provides type information for some of HHVM's builtin classes.
  14  *
  15  * YOU SHOULD NEVER INCLUDE THIS FILE ANYWHERE!!!
  16  */
  17
  18 namespace HH {
  19
  20 /**
  21  * `ImmMap` is an immutable `Map`. HHVM provides a native implementation for
  22  * this class. The PHP class definition below is not actually used at run time;
  23  * it is simply provided for the typechecker and for developer reference.
  24  *
  25  * A `ImmMap` cannot be mutated. No elements can be added or removed from it,
  26  * nor can elements be overwritten using assignment (i.e. `$c[$k] = $v` is
  27  * not allowed).
  28  *
  29  * Construct it with a `Traversable`:
  30  *
  31  * ```
  32  * $a = dict['a' => 1, 'b' => 2];
  33  * $fm = new ImmMap($a);
  34  * ```
  35  *
  36  * or use the literal syntax
  37  *
  38  * ```
  39  * $fm = ImmMap {'a' => 1, 'b' => 2};
  40  * ```
  41  *
  42  * @guide /hack/collections/introduction
  43  * @guide /hack/collections/classes
  44  */
  45 <<__SupportDynamicType>>
  46 final class ImmMap<Tk as arraykey, +Tv> implements \ConstMap<Tk, Tv> {
  47   /**
  48    * Creates an `ImmMap` from the given `KeyedTraversable`, or an empty
  49    * `ImmMap` if `null` is passed.
  50    *
  51    * @param $it - any `Traversable` object from which to create an `ImmMap`
  52    *             (e.g., `array`). If `null`, then an empty `ImmMap` is created.
  53    */
  54   public function __construct(?KeyedTraversable<Tk, Tv> $it)[];
  55
  56   /**
  57    * Returns an `array` containing the values from the current `ImmMap`.
  58    *
  59    * @return - an integer-indexed `array` containing the values from the
  60    *           current `ImmMap`.
  61    */
  62   public function toValuesArray()[]: varray<Tv>;
  63
  64   /**
  65    * Returns an `array` whose values are the keys of the current `ImmMap`.
  66    *
  67    * @return - an integer-indexed `array` where the values are the keys from
  68    *           the current `ImmMap`.
  69    */
  70   public function toKeysArray()[]: varray<Tk>;
  71
  72   /**
  73    * Returns an immutable vector (`ImmVector`) with the values of the current
  74    * `ImmMap`.
  75    *
  76    * @return - an `ImmVector` that contains the values of the current `ImmMap`.
  77    */
  78   public function toImmVector()[]: ImmVector<Tv>;
  79
  80   /**
  81    * Returns an immutable copy (`ImmMap`) of the current `ImmMap`.
  82    *
  83    * @return - an `ImmMap` that is a copy of the current `ImmMap`.
  84    */
  85   public function toImmMap()[]: ImmMap<Tk, Tv>;
  86
  87   /**
  88    * Returns an immutable set (`ImmSet`) based on the values of the current
  89    * `ImmMap`.
  90    *
  91    * @return - an `ImmSet` with the current values of the current `ImmMap`.
  92    */
  93   public function toImmSet()[]: ImmSet<Tv> where Tv as arraykey;
  94
  95   /**
  96    * Returns an immutable copy (`ImmMap`) of the current `ImmMap`.
  97    *
  98    * This method is interchangeable with `toImmMap()`.
  99    *
 100    * @return - an `ImmMap` representing a copy of the current `ImmMap`.
 101    */
 102   public function immutable()[]: ImmMap<Tk, Tv>;
 103
 104   /**
 105    * Returns a lazy, access elements only when needed view of the current
 106    * `ImmMap`.
 107    *
 108    * Normally, memory is allocated for all of the elements of an `ImmMap`. With
 109    * a lazy view, memory is allocated for an element only when needed or used
 110    * in a calculation like in `map()` or `filter()`.
 111    *
 112    * @return - a `KeyedIterable` representing the lazy view into the current
 113    *           `ImmMap`.
 114    *
 115    * @guide /hack/collections/examples
 116    */
 117   public function lazy()[]: \HH\Rx\KeyedIterable<Tk, Tv>;
 118
 119   /**
 120    * Returns an ImmVector containing the values of the current `ImmMap`.
 121    *
 122    * This method is interchangeable with toImmVector().
 123    *
 124    * @return - an ImmVector containing the values of the current `ImmMap`.
 125    */
 126   public function values()[]: ImmVector<Tv>;
 127
 128   /**
 129    * Returns an ImmVector containing, as values, the keys of the current `ImmMap`.
 130    *
 131    * @return - an ImmVector containing, as values, the keys of the current
 132    *           `ImmMap`.
 133    */
 134   public readonly function keys()[]: ImmVector<Tk>;
 135
 136   /**
 137    * Returns an `ImmMap` after an operation has been applied to each value in
 138    * the current `ImmMap`.
 139    *
 140    * Every value in the current `ImmMap` is affected by a call to `map()`,
 141    * unlike `filter()` where only values that meet a certain criteria are
 142    * affected.
 143    *
 144    * The keys will remain unchanged from this `ImmMap` to the returned `ImmMap`.
 145    *
 146    * @param $fn - The callback containing the operation to apply to the
 147    *                    current `ImmMap` values.
 148    *
 149    * @return - an `ImmMap` containing key/value pairs after a user-specified
 150    *           operation is applied.
 151    *
 152    * @guide /hack/collections/examples
 153    */
 154   public function map<Tu>((function(Tv)[_]: Tu) $fn)[ctx $fn]: ImmMap<Tk, Tu>;
 155
 156   /**
 157    * Returns an `ImmMap` after an operation has been applied to each key and
 158    * value in current `ImmMap`.
 159    *
 160    * Every key and value in the current `ImmMap` is affected by a call to
 161    * `mapWithKey()`, unlike `filterWithKey()` where only values that meet a
 162    * certain criteria are affected.
 163    *
 164    * The keys will remain unchanged from the current `ImmMap` to the returned
 165    * `ImmMap`. The keys are only used to help in the operation.
 166    *
 167    * @param $fn - The callback containing the operation to apply to the
 168    *                    current `ImmMap` keys and values.
 169    *
 170    * @return - an `ImmMap` containing the values after a user-specified
 171    *           operation on the current `ImmMap`'s keys and values is applied.
 172    */
 173   public function mapWithKey<Tu>((function(Tk, Tv)[_]: Tu) $fn)[ctx $fn]:
 174     ImmMap<Tk, Tu>;
 175
 176   /**
 177    * Returns an `ImmMap` containing the values of the current `ImmMap` that
 178    * meet a supplied condition.
 179    *
 180    * Only values that meet a certain criteria are affected by a call to
 181    * `filter()`, while all values are affected by a call to `map()`.
 182    *
 183    * The keys associated with the current `ImmMap` remain unchanged in the
 184    * returned `Map`.
 185    *
 186    * @param $fn - The callback containing the condition to apply to the
 187    *                    current `ImmMap` values.
 188    *
 189    * @return - an `ImmMap` containing the values after a user-specified
 190    *           condition is applied.
 191    *
 192    * @guide /hack/collections/examples
 193    */
 194   public function filter((function(Tv)[_]: bool) $fn)[ctx $fn]: ImmMap<Tk, Tv>;
 195
 196   /**
 197    * Returns an `ImmMap` containing the values of the current `ImmMap` that
 198    * meet a supplied condition applied to its keys and values.
 199    *
 200    * Only keys and values that meet a certain criteria are affected by a call to
 201    * `filterWithKey()`, while all values are affected by a call to
 202    * `mapWithKey()`.
 203    *
 204    * The keys associated with the current `ImmMap` remain unchanged in the
 205    * returned `ImmMap`; the keys will be used in the filtering process only.
 206    *
 207    * @param $fn - The callback containing the condition to apply to the
 208    *                    current `ImmMap` keys and values.
 209    *
 210    * @return - an `ImmMap` containing the values after a user-specified
 211    *           condition is applied to the keys and values of the current
 212    *           `ImmMap`.
 213    *
 214    */
 215   public function filterWithKey((function(Tk, Tv)[_]: bool) $fn)[ctx $fn]:
 216     ImmMap<Tk, Tv>;
 217
 218   /**
 219    * Returns an `ImmMap` where each value is a `Pair` that combines the value
 220    * of the current `ImmMap` and the provided `Traversable`.
 221    *
 222    * If the number of values of the current `ImmMap` are not equal to the
 223    * number of elements in the `Traversable`, then only the combined elements
 224    * up to and including the final element of the one with the least number of
 225    * elements is included.
 226    *
 227    * The keys associated with the current `ImmMap` remain unchanged in the
 228    * returned `ImmMap`.
 229    *
 230    * @param $traversable - The `Traversable` to use to combine with the
 231    *                       elements of the current `ImmMap`.
 232    *
 233    * @return - The `ImmMap` that combines the values of the current `ImmMap`
 234    *           with the provided `Traversable`.
 235    */
 236   public function zip<Tu>(Traversable<Tu> $traversable)[]:
 237     ImmMap<Tk, Pair<Tv, Tu>>;
 238
 239   /**
 240    * Returns an `ImmMap` containing the first `n` key/values of the current
 241    * `ImmMap`.
 242    *
 243    * The returned `ImmMap` will always be a proper subset of the current
 244    * `ImmMap`.
 245    *
 246    * `n` is 1-based. So the first element is 1, the second 2, etc.
 247    *
 248    * @param $n - The last element that will be included in the returned
 249    *             `ImmMap`.
 250    *
 251    * @return - An `ImmMap` that is a proper subset of the current `ImmMap` up
 252    *           to `n` elements.
 253    */
 254   public function take(int $n)[]: ImmMap<Tk, Tv>;
 255
 256   /**
 257    * Returns an `ImmMap` containing the keys and values of the current `ImmMap`
 258    * up to but not including the first value that produces `false` when passed
 259    * to the specified callback.
 260    *
 261    * The returned `ImmMap` will always be a proper subset of the current
 262    * `ImmMap`.
 263    *
 264    * @param $fn - The callback that is used to determine the stopping condition.
 265    *
 266    * @return - An `ImmMap` that is a proper subset of the current `ImmMap` up
 267    *           until when the callback returns `false`.
 268    */
 269   public function takeWhile((function(Tv)[_]: bool) $fn)[ctx $fn]: ImmMap<Tk, Tv>;
 270
 271   /**
 272    * Returns an `ImmMap` containing the values after the `n`-th element of the
 273    * current `ImmMap`.
 274    *
 275    * The returned `ImmMap` will always be a proper subset of the current
 276    * `ImmMap`.
 277    *
 278    * `n` is 1-based. So the first element is 1, the second 2, etc.
 279    *
 280    * @param $n - The last element to be skipped; the `$n+1` element will be the
 281    *             first one in the returned `ImmMap`.
 282    *
 283    * @return - An `ImmMap` that is a proper subset of the current `ImmMap`
 284    *           containing values after the specified `n`-th element.
 285    */
 286   public function skip(int $n)[]: ImmMap<Tk, Tv>;
 287
 288   /**
 289    * Returns an `ImmMap` containing the values of the current `ImmMap` starting
 290    * after and including the first value that produces `true` when passed to
 291    * the specified callback.
 292    *
 293    * The returned `ImmMap` will always be a proper subset of the current
 294    * `ImmMap`.
 295    *
 296    * @param $fn - The callback used to determine the starting element for the
 297    *              `ImmMap`.
 298    *
 299    * @return - An `ImmMap` that is a proper subset of the current `ImmMap`
 300    *           starting after the callback returns `true`.
 301    */
 302   public function skipWhile((function(Tv)[_]: bool) $fn)[ctx $fn]: ImmMap<Tk, Tv>;
 303
 304   /**
 305    * Returns a subset of the current `ImmMap` starting from a given key
 306    * location up to, but not including, the element at the provided length from
 307    * the starting key location.
 308    *
 309    * `$start` is 0-based. `$len` is 1-based. So `slice(0, 2)` would return the
 310    * keys and values at key location 0 and 1.
 311    *
 312    * The returned `ImmMap` will always be a proper subset of the current
 313    * `ImmMap`.
 314    *
 315    * @param $start - The starting key location of the current `ImmMap` for the
 316    *                 returned `ImmMap`.
 317    * @param $len - The length of the returned `ImmMap`.
 318    *
 319    * @return - An `ImmMap` that is a proper subset of the current `ImmMap`
 320    *           starting at `$start` up to but not including the element
 321    *           `$start + $len`.
 322    */
 323   public function slice(int $start, int $len)[]: ImmMap<Tk, Tv>;
 324
 325   /**
 326    * Returns an ImmVector that is the concatenation of the values of the
 327    * current `ImmMap` and the values of the provided `Traversable`.
 328    *
 329    * The provided `Traversable` is concatenated to the end of the current
 330    * `ImmMap` to produce the returned `ImmVector`.
 331    *
 332    * @param $traversable - The `Traversable` to concatenate to this `ImmMap`.
 333    *
 334    * @return - The integer-indexed concatenated `ImmVector`.
 335    *
 336    * @guide /hack/generics/constraints
 337    */
 338   public function concat<Tu super Tv>(Traversable<Tu> $traversable)[]:
 339     ImmVector<Tu>;
 340
 341   /**
 342    * Returns the first value in the current `ImmMap`.
 343    *
 344    * @return - The first value in the current `ImmMap`, or `null` if the current
 345    *           `ImmMap` is empty.
 346    */
 347   public function firstValue()[]: ?Tv;
 348
 349   /**
 350    * Returns the first key in the current `ImmMap`.
 351    *
 352    * @return - The first key in the current `ImmMap`, or `null` if the current
 353    *           `ImmMap` is empty.
 354    */
 355   public readonly function firstKey()[]: ?Tk;
 356
 357   /**
 358    * Returns the last value in the current `ImmMap`.
 359    *
 360    * @return - The last value in the current `ImmMap`, or `null` if the current
 361    *           `ImmMap` is empty.
 362    */
 363   public function lastValue()[]: ?Tv;
 364
 365   /**
 366    * Returns the last key in the current `ImmMap`.
 367    *
 368    * @return - The last key in the current `ImmMap`, or `null` if the current
 369    *           `ImmMap` is empty.
 370    */
 371   public readonly function lastKey()[]: ?Tk;
 372
 373   /**
 374    * Checks if the current `ImmMap` is empty.
 375    *
 376    * @return - `true` if the current `ImmMap` is empty; `false` otherwise.
 377    */
 378   public readonly function isEmpty()[]: bool;
 379
 380   /**
 381    * Provides the number of elements in the current `ImmMap`.
 382    *
 383    * @return - The number of elements in current `ImmMap`.
 384    */
 385   public readonly function count()[]: int;
 386
 387   /**
 388    * Returns the value at the specified key in the current `ImmMap`.
 389    *
 390    * If the key is not present, an exception is thrown. If you don't want an
 391    * exception to be thrown, use `get()` instead.
 392    *
 393    * `$v = $map->at($k)` is semantically equivalent to `$v = $map[$k]`.
 394    *
 395    * @param $k - the key from which to retrieve the value.
 396    *
 397    * @return - The value at the specified key; or an exception if the key does
 398    *           not exist.
 399    */
 400   public function at(Tk $k)[]: Tv;
 401
 402   /**
 403    * Returns the value at the specified key in the current `ImmMap`.
 404    *
 405    * If the key is not present, null is returned. If you would rather have an
 406    * exception thrown when a key is not present, then use `at()`.
 407    *
 408    * @param $k - the key from which to retrieve the value.
 409    *
 410    * @return - The value at the specified key; or `null` if the key does not
 411    *           exist.
 412    */
 413   public function get(Tk $k)[]: ?Tv;
 414
 415   /**
 416    * Determines if the specified key is in the current `ImmMap`.
 417    *
 418    * This function is interchangeable with `containsKey()`.
 419    *
 420    * @param $k - The key to check.
 421    *
 422    * @return - `true` if the specified key is present in the current `ImmMap`;
 423    *           `false` otherwise.
 424    *
 425    * @guide /hack/generics/constraints
 426    */
 427   public readonly function contains(mixed $k)[]: bool;
 428
 429   /**
 430    * Determines if the specified key is in the current `ImmMap`.
 431    *
 432    * This function is interchangeable with `contains()`.
 433    *
 434    * @param $k - The key to check.
 435    *
 436    * @return - `true` if the specified key is present in the current `ImmMap`;
 437    *           `false` otherwise.
 438    *
 439    * @guide /hack/generics/constraints
 440    */
 441   public readonly function containsKey(mixed $k)[]: bool;
 442
 443   /**
 444    * Returns a new `ImmMap` with the keys that are in the current `ImmMap`, but
 445    * not in the provided `KeyedTraversable`.
 446    *
 447    * @param $traversable - The `KeyedTraversable` on which to compare the keys.
 448    *
 449    * @return - An `ImmMap` containing the keys (and associated values) of the
 450    *           current `ImmMap` that are not in the `KeyedTraversable`.
 451    */
 452   public function differenceByKey(
 453     KeyedTraversable<mixed, mixed> $traversable
 454   )[]: ImmMap<Tk, Tv>;
 455
 456   /**
 457    * Returns an iterator that points to beginning of the current `ImmMap`.
 458    *
 459    * @return - A `KeyedIterator` that allows you to traverse the current
 460    *           `ImmMap`.
 461    */
 462   public function getIterator()[]: \HH\Rx\KeyedIterator<Tk, Tv>;
 463
 464   /**
 465    * Creates an `ImmMap` from the given `Traversable`, or an empty `ImmMap`
 466    * if `null` is passed.
 467    *
 468    * This is the static method version of the `ImmMap::__construct()`
 469    * constructor.
 470    *
 471    * @param $items - any Traversable object from which to create an `ImmMap`
 472    *                 (e.g., `array`). If `null`, then an empty `ImmMap` is
 473    *                 created.
 474    *
 475    * @return - An `ImmMap` with the key/value pairs from the `Traversable`; or
 476    *           an empty `ImmMap` if the `Traversable` is `null`.
 477    */
 478   public static function fromItems(?Traversable<Pair<Tk, Tv>> $items)[]:
 479     ImmMap<Tk, Tv>;
 480
 481   /**
 482    * Returns the `string` version of the current `ImmMap`, which is `"ImmMap"`.
 483    *
 484    * @return - The `string` `"ImmMap"`.
 485    */
 486   public function __toString()[]: string;
 487
 488   /**
 489    * Returns an `Iterable` view of the current `ImmMap`.
 490    *
 491    * The `Iterable` returned is one that produces the key/values from the
 492    * current `ImmMap`.
 493    *
 494    * @return - The `Iterable` view of the current `ImmMap`.
 495    */
 496   public function items()[]: \HH\Rx\Iterable<Pair<Tk, Tv>>;
 497  /* HH_FIXME[0002] */
 498   public function toVArray()[]: varray<Tv>; /* HH_FIXME[0001] */
 499   public function toDArray()[]: darray<Tk, Tv>;
 500 }
 501
 502 } // namespace HH