hphp/hack/hhi/collections/ImmMap.hhi

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