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