hphp/hack/hhi/collections/Set.hhi

   1 <?hh // decl
   2 /**
   3  * Copyright (c) 2014, Facebook, Inc.
   4  * All rights reserved.
   5  *
   6  * This source code is licensed under the BSD-style license found in the
   7  * LICENSE file in the "hack" directory of this source tree. An additional grant
   8  * of patent rights can be found in the PATENTS file in the same directory.
   9  *
  10  */
  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 /**
  19  * `Set` is an ordered set-style collection. HHVM provides a native
  20  * implementation for this class. The PHP class definition below is not
  21  * actually used at run time; it is simply provided for the typechecker and
  22  * for developer reference.
  23  *
  24  * Like all objects in PHP, `Set`s have reference-like semantics. When a caller
  25  * passes a `Set` to a callee, the callee can modify the `Set` and the caller
  26  * will see the changes. `Set`s do not have "copy-on-write" semantics.
  27  *
  28  * `Set`s preserve insertion order of the elements. When iterating over a
  29  * `Set`, the elements appear in the order they were inserted. Also, `Set`s do
  30  * not automagically convert integer-like strings (ex. "123") into integers.
  31  *
  32  * `Set`s only support `int` values and `string` values. If a value of a
  33  * different type is used, an exception will be thrown.
  34  *
  35  * In general, Sets do not support `$c[$k]` style syntax. Adding an element
  36  * using `$c[] = ..` syntax is supported.
  37  *
  38  * `Set` do not support iteration while elements are being added or removed.
  39  * When an element is added or removed, all iterators that point to the `Set`
  40  * shall be considered invalid.
  41  *
  42  * `Set`s do not support taking elements by reference. If binding assignment
  43  * (`=&`) is used when adding a new element to a `Set` (ex. `$c[] =& ...`), or
  44  * if a `Set` is used with `foreach` by reference, an exception will be thrown.
  45  *
  46  * @guide /hack/collections/introduction
  47  * @guide /hack/collections/classes
  48  */
  49
  50 final class Set<Tv> implements MutableSet<Tv> {
  51   /**
  52    * Creates a `Set` from the given `Traversable`, or an empty `Set` if `null`
  53    * is passed.
  54    *
  55    * @param $it - any `Traversable` object from which to create the `Set`
  56    *              (e.g., `array`). If `null`, then an empty `Set` is created.
  57    */
  58   public function __construct(?Traversable<Tv> $it);
  59
  60   /**
  61    * Returns an `array` containing the values from the current `Set`.
  62    *
  63    * For the returned `array`, each key is the same as its associated value.
  64    *
  65    * @return - an `array` containing the values from the current `Set`, where
  66    *           each key of the `array` are the same as each value.
  67    */
  68   public function toArray(): array<Tv, Tv>;
  69
  70   /**
  71    * Returns an `array` containing the values from the current `Set`.
  72    *
  73    * `Set`s don't have keys. So this method just returns the values.
  74    *
  75    * This method is interchangeable with `toValuesArray()`.
  76    *
  77    * @return - an integer-indexed `array` containing the values from the
  78    *           current `Set`.
  79    */
  80   public function toKeysArray(): array<Tv>;
  81
  82   /**
  83    * Returns an `array` containing the values from the current `Set`.
  84    *
  85    * This method is interchangeable with `toKeysArray()`.
  86    *
  87    * @return - an integer-indexed `array` containing the values from the
  88    *           current `Set`.
  89    */
  90   public function toValuesArray(): array<Tv>;
  91
  92   /**
  93    * Returns a `Vector` of the current `Set` values.
  94    *
  95    * @return - a `Vector` (integer-indexed) that contains the values of the
  96    *           current `Set`.
  97    */
  98   public function toVector(): Vector<Tv>;
  99
 100   /**
 101    * Returns an immutable vector (`ImmVector`) with the values of the current
 102    * `Set`.
 103    *
 104    * @return - an `ImmVector` (integer-indexed) with the values of the current
 105    *           `Set`.
 106    */
 107   public function toImmVector(): ImmVector<Tv>;
 108
 109   /**
 110    * Returns a `Map` based on the values of the current `Set`.
 111    *
 112    * Each key of the `Map` will be the same as its value.
 113    *
 114    * @return - a `Map` that that contains the values of the current `Set`, with
 115    *           each key of the `Map` being the same as its value.
 116    */
 117   public function toMap(): Map<mixed, Tv>;
 118
 119   /**
 120    * Returns an immutable map (`ImmMap`) based on the values of the current
 121    * `Set`.
 122    *
 123    * Each key of the `Map` will be the same as its value.
 124    *
 125    * @return - an `ImmMap` that that contains the values of the current `Set`,
 126    *           with each key of the Map being the same as its value.
 127    */
 128   public function toImmMap(): ImmMap<mixed, Tv>;
 129
 130   /**
 131    * Returns a deep copy of the current `Set`.
 132    *
 133    * @return - a `Set` that is a deep copy of the current `Set`.
 134    */
 135   public function toSet(): Set<Tv>;
 136
 137   /**
 138    * Returns an immutable (`ImmSet`), deep copy of the current `Set`.
 139    *
 140    * This method is interchangeable with `immutable()`.
 141    *
 142    * @return - an `ImmSet` that is a deep copy of the current `Set`.
 143    */
 144   public function toImmSet(): ImmSet<Tv>;
 145
 146   /**
 147    * Returns an immutable (`ImmSet`), deep copy of the current `Set`.
 148    *
 149    * This method is interchangeable with `toImmSet()`.
 150    *
 151    * @return - an `ImmSet` that is a deep copy of the current `Set`.
 152    */
 153   public function immutable(): ImmSet<Tv>;
 154
 155   /**
 156    * Returns a lazy, access elements only when needed view of the current
 157    * `Set`.
 158    *
 159    * Normally, memory is allocated for all of the elements of the `Set`. With
 160    * a lazy view, memory is allocated for an element only when needed or used
 161    * in a calculation like in `map()` or `filter()`.
 162    *
 163    * @return - an `KeyedIterable` representing the lazy view into the current
 164    *           `Set`, where the keys are the same as the values.
 165    *
 166    * @guide /hack/collections/examples
 167    */
 168   public function lazy(): KeyedIterable<mixed, Tv>;
 169
 170   /**
 171    * Returns a `Vector` containing the values of the current `Set`.
 172    *
 173    * This method is interchangeable with `toVector()` and `keys()`.
 174    *
 175    * @return - a `Vector` (integer-indexed) containing the values of the
 176    *           current `Set`.
 177    */
 178   public function values(): Vector<Tv>;
 179
 180   /**
 181    * Returns a `Vector` containing the values of the current `Set`.
 182    *
 183    * `Set`s don't have keys, so this will return the values.
 184    *
 185    * This method is interchangeable with `toVector()` and `values()`.
 186    *
 187    * @return - a `Vector` (integer-indexed) containing the values of the
 188    *           current `Set`.
 189    */
 190   public function keys(): Vector<mixed>;
 191
 192   /**
 193    * Returns a `Set` containing the values after an operation has been applied
 194    * to each value in the current `Set`.
 195    *
 196    * Every value in the current `Set` is affected by a call to `map()`, unlike
 197    * `filter()` where only values that meet a certain criteria are affected.
 198    *
 199    * @param $callback - The callback containing the operation to apply to the
 200    *                    current `Set` values.
 201    *
 202    * @return - a `Set` containing the values after a user-specified operation
 203    *           is applied.
 204    *
 205    * @guide /hack/collections/examples
 206    */
 207   public function map<Tu>((function(Tv): Tu) $callback): Set<Tu>;
 208
 209   /**
 210    * Returns a `Set` containing the values after an operation has been applied
 211    * to each "key" and value in the current `Set`.
 212    *
 213    * Since `Set`s don't have keys, the callback uses the values as the keys
 214    * as well.
 215    *
 216    * Every value in the current `Set` is affected by a call to `mapWithKey()`,
 217    * unlike `filterWithKey()` where only values that meet a certain criteria are
 218    * affected.
 219    *
 220    * @param $callback - The callback containing the operation to apply to the
 221    *                    current `Set` keys and values.
 222    *
 223    * @return - a `Set` containing the values after a user-specified operation
 224    *           on the current `Set`'s values is applied.
 225    */
 226   public function mapWithKey<Tu>((function(mixed, Tv): Tu) $callback): Set<Tu>;
 227
 228   /**
 229    * Returns a `Set` containing the values of the current `Set` that meet
 230    * a supplied condition applied to each value.
 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    * @param $callback - The callback containing the condition to apply to the
 236    *                    current `Set` values.
 237    *
 238    * @return - a `Set` containing the values after a user-specified condition
 239    *           is applied.
 240    *
 241    * @guide /hack/collections/examples
 242    */
 243   public function filter((function(Tv): bool) $callback): Set<Tv>;
 244
 245   /**
 246    * Returns a `Set` containing the values of the current `Set` that meet
 247    * a supplied condition applied to its "keys" and values.
 248    *
 249    * Since `Set`s don't have keys, the callback uses the values as the keys
 250    * as well.
 251    *
 252    * Only values that meet a certain criteria are affected by a call to
 253    * `filterWithKey()`, while all values are affected by a call to
 254    * `mapWithKey()`.
 255    *
 256    * @param $callback - The callback containing the condition to apply to the
 257    *                    current `Set` keys and values.
 258    *
 259    * @return - a `Set` containing the values after a user-specified condition
 260    *           is applied to the values of the current `Set`.
 261    *
 262    */
 263   public function filterWithKey((function(mixed, Tv): bool) $callback): Set<Tv>;
 264
 265   /**
 266    * Alters the current `Set` so that it only contains the values that meet a
 267    * supplied condition on each value.
 268    *
 269    * This method is like `filter()`, but mutates the current `Set` too in
 270    * addition to returning a shallow copy of the current `Set`.
 271    *
 272    * Future changes made to the current `Set` ARE reflected in the returned
 273    * `Set`, and vice-versa.
 274    *
 275    * @param $callback - The callback containing the condition to apply to the
 276    *                    current `Set` values.
 277    *
 278    * @return - a shallow copy of the current `Set` containing the values after
 279    *           a user-specified condition is applied.
 280    */
 281   public function retain((function(Tv): bool) $callback): Set<Tv>;
 282
 283   /**
 284    * Alters the current `Set` so that it only contains the values that meet a
 285    * supplied condition on its "keys" and values.
 286    *
 287    * `Set`s don't have keys, so the `Set` values are used as the key in the
 288    * callback.
 289    *
 290    * This method is like `filterWithKey()`, but mutates the current `Set` too
 291    * in addition to returning a shallow copy of the current `Set`.
 292    *
 293    * Future changes made to the current `Set` ARE reflected in the returned
 294    * `Set`, and vice-versa.
 295    *
 296    * @param $callback - The callback containing the condition to apply to the
 297    *                    current `Set` values.
 298    *
 299    * @return - a shallow copy of the current `Set` containing the values after
 300    *           a user-specified condition is applied.
 301    */
 302   public function retainWithKey((function(mixed, Tv): bool) $callback): Set<Tv>;
 303
 304   /**
 305    * Throws an exception unless the current `Set` or the `Traversable` is
 306    * empty.
 307    *
 308    * Since `Set`s only support integers or strings as values, we cannot have
 309    * a `Pair` as a `Set` value. So in order to avoid an
 310    * `InvalidArgumentException`, either the current `Set` or the `Traversable`
 311    * must be empty so that we actually return an empty `Set`.
 312    *
 313    * @param $traversable - The `Traversable` to use to combine with the
 314    *                       elements of the current `Set`.
 315    *
 316    * @return - The `Set` that combines the values of the current `Set` with
 317    *           the provided `Traversable`; one of these must be empty or an
 318    *           exception is thrown.
 319    */
 320   public function zip<Tu>(Traversable<Tu> $traversable): Set<Pair<Tv, Tu>>;
 321
 322   /**
 323    * Returns a `Set` containing the first `n` values of the current `Set`.
 324    *
 325    * The returned `Set` will always be a proper subset of the current `Set`.
 326    *
 327    * `n` is 1-based. So the first element is 1, the second 2, etc.
 328    *
 329    * @param $n - The last element that will be included in the `Set`.
 330    *
 331    * @return - A `Set` that is a proper subset of the current `Set` up to `n`
 332    *           elements.
 333    */
 334   public function take(int $n): Set<Tv>;
 335
 336   /**
 337    * Returns a `Set` containing the values of the current `Set` up to but not
 338    * including the first value that produces `false` when passed to the
 339    * specified callback.
 340    *
 341    * The returned `Set` will always be a proper subset of the current `Set`.
 342    *
 343    * @param $fn - The callback that is used to determine the stopping condition.
 344    *
 345    * @return - A `Set` that is a proper subset of the current `Set` up until
 346    *           the callback returns `false`.
 347    */
 348   public function takeWhile((function(Tv): bool) $fn): Set<Tv>;
 349
 350   /**
 351    * Returns a `Set` containing the values after the `n`-th element of the
 352    * current `Set`.
 353    *
 354    * The returned `Set` will always be a proper subset of the current `Set`.
 355    *
 356    * `n` is 1-based. So the first element is 1, the second 2, etc.
 357    *
 358    * @param $n - The last element to be skipped; the `$n+1` element will be
 359    *             the first one in the returned `Set`.
 360    *
 361    * @return - A `Set` that is a proper subset of the current `Set` containing
 362    *           values after the specified `n`-th element.
 363    */
 364   public function skip(int $n): Set<Tv>;
 365
 366   /**
 367    * Returns a `Set` containing the values of the current `Set` starting after
 368    * and including the first value that produces `true` when passed to the
 369    * specified callback.
 370    *
 371    * The returned `Set` will always be a proper subset of the current `Set`.
 372    *
 373    * @param $fn - The callback used to determine the starting element for the
 374    *              `Set`.
 375    *
 376    * @return - A `Set` that is a proper subset of the current `Set` starting
 377    *           after the callback returns `true`.
 378    */
 379   public function skipWhile((function(Tv): bool) $fn): Set<Tv>;
 380
 381   /**
 382    * Returns a subset of the current `Set` starting from a given key up to, but
 383    * not including, the element at the provided length from the starting key.
 384    *
 385    * `$start` is 0-based. `$len` is 1-based. So `slice(0, 2)` would return the
 386    * elements at key 0 and 1.
 387    *
 388    * The returned `Set` will always be a proper subset of the current `Set`.
 389    *
 390    * @param $start - The starting value in the current `Set` for the returned
 391    *                 `Set`.
 392    * @param $len - The length of the returned `Set`.
 393    *
 394    * @return - A `Set` that is a proper subset of the current `Set` starting at
 395    *           `$start` up to but not including the element `$start + $len`.
 396    */
 397   public function slice(int $start, int $len): Set<Tv>;
 398
 399   /**
 400    * Returns a `Vector` that is the concatenation of the values of the current
 401    * `Set` and the values of the provided `Traversable`.
 402    *
 403    * The values of the provided `Traversable` is concatenated to the end of the
 404    * current `Set` to produce the returned `Vector`.
 405    *
 406    * @param $traversable - The `Traversable` to concatenate to the current
 407    *                       `Set`.
 408    *
 409    * @return - The concatenated `Vector`.
 410    *
 411    * @guide /hack/generics/constraints
 412    */
 413   public function concat<Tu super Tv>(Traversable<Tu> $traversable): Vector<Tu>;
 414
 415   /**
 416    * Returns the first value in the current `Set`.
 417    *
 418    * @return - The first value in the current `Set`, or `null` if the `Set` is
 419    *           empty.
 420    */
 421   public function firstValue(): ?Tv;
 422
 423   /**
 424    * Returns the first "key" in the current `Set`.
 425    *
 426    * Since `Set`s do not have keys, it returns the first value.
 427    *
 428    * This method is interchangeable with `firstValue()`.
 429    *
 430    * @return - The first value in the current `Set`, or `null` if the `Set` is
 431    *           empty.
 432    */
 433   public function firstKey(): mixed;
 434
 435   /**
 436    * Returns the last value in the current `Set`.
 437    *
 438    * @return - The last value in the current `Set`, or `null` if the current
 439    *           `Set` is empty.
 440    */
 441   public function lastValue(): ?Tv;
 442
 443   /**
 444    * Returns the last "key" in the current `Set`.
 445    *
 446    * Since `Set`s do not have keys, it returns the last value.
 447    *
 448    * This method is interchangeable with `lastValue()`.
 449    *
 450    * @return - The last value in the current `Set`, or `null` if the current
 451    *           `Set` is empty.
 452    */
 453   public function lastKey(): mixed;
 454
 455   /**
 456    * Checks if the current `Set` is empty.
 457    *
 458    * @return - `true` if the current `Set` is empty; `false` otherwise.
 459    */
 460   public function isEmpty(): bool;
 461
 462   /**
 463    * Provides the number of elements in the current `Set`.
 464    *
 465    * @return - The number of elements in the current `Set`.
 466    */
 467   public function count(): int;
 468
 469   /**
 470    * Remove all the elements from the current `Set`.
 471    *
 472    * Future changes made to the current `Set` ARE reflected in the returned
 473    * `Set`, and vice-versa.
 474    *
 475    * @return - A shallow, empty copy of the current `Set`. The current `Set` is
 476    *           also empty.
 477    */
 478   public function clear(): Set<Tv>;
 479
 480   /**
 481    * Determines if the specified value is in the current `Set`.
 482    *
 483    * @param $v - The value to check.
 484    * @return - `true` if the specified value is present in the current `Set`;
 485    *           `false` otherwise.
 486    */
 487   public function contains<Tu super Tv>(Tu $v): bool;
 488
 489   /**
 490    * Add the value to the current `Set`.
 491    *
 492    * `$set->add($v)` is semantically equivalent to `$set[] = $v` (except that
 493    * `add()` returns the `Set`).
 494    *
 495    * Future changes made to the current `Set` ARE reflected in the returned
 496    * `Set`, and vice-versa.
 497    *
 498    * @param $v - The value to add to the current `Set`
 499    *
 500    * @return - A shallow copy of the current `Set` with the added the value
 501    *           set. The current `Set` is also updated.
 502    */
 503   public function add(Tv $v): Set<Tv>;
 504
 505   /**
 506    * For every element in the provided `Traversable`, add the value into the
 507    * current `Set`.
 508    *
 509    * Future changes made to the original `Set` ARE reflected in the returned
 510    * `Set`, and vice-versa.
 511    *
 512    * @param $k - The `Traversable` with the new values to add. If `null` is
 513    *             provided, no changes are made.
 514    *
 515    * @return - A shallow copy of the current `Set` with the added the values
 516    *           set. The current `Set` is also updated.
 517    */
 518   public function addAll(?Traversable<Tv> $it): Set<Tv>;
 519
 520   /**
 521    * Adds the keys of the specified container to the current `Set` as new
 522    * values.
 523    *
 524    * Future changes made to the current `Set` ARE reflected in the returned
 525    * `Set`, and vice-versa.
 526    *
 527    * @param $container - The container with the new keys to add.
 528    *
 529    * @return - A shallow copy of the current `Set` with the new keys added; the
 530    *           current `Set` is also updated.
 531    */
 532   public function addAllKeysOf<Tv2>(
 533     ?KeyedContainer<Tv,Tv2> $container,
 534   ): Set<Tv>;
 535
 536   /**
 537    * Reserves enough memory to accommodate a given number of elements.
 538    *
 539    * Reserves enough memory for `sz` elements. If `sz` is less than or equal
 540    * to the current capacity of this `Set`, this method does nothing.
 541    *
 542    * @param $sz - The pre-determined size you want for the current `Set`.
 543    */
 544   public function reserve(int $sz): void;
 545
 546   /**
 547    * Removes the specified value from the current `Set`.
 548    *
 549    * Future changes made to the current `Set` ARE reflected in the returned
 550    * `Set`, and vice-versa.
 551    *
 552    * @param $v - The value to remove.
 553    *
 554    * @return - A shallow copy of the current `Set` with the value removed; the
 555    *           current `Set` is also updated.
 556    */
 557   public function remove(Tv $v): Set<Tv>;
 558
 559   /**
 560    * Removes the values in the current `Set` that are also in the `Traversable`.
 561    *
 562    * If a value in the `Traversable` doesn't exist in the current `Set`, that
 563    * value in the `Traversable` is ignored.
 564    *
 565    * Future changes made to the current `Set` ARE reflected in the returned
 566    * `Set`, and vice-versa.
 567    *
 568    * @param $other - The `Traversable` containing values that will be removed
 569    *                 from the `Set`.
 570    *
 571    * @return - A shallow copy of the current `Set` with the values removed; the
 572    *           current `Set` is also updated.
 573    */
 574   public function removeAll(Traversable<Tv> $other): Set<Tv>;
 575
 576   /**
 577    * Returns an iterator that points to beginning of the current `Set`.
 578    *
 579    * @return - A `KeyedIterator` that allows you to traverse the current `Set`.
 580    */
 581   public function getIterator(): KeyedIterator<mixed, Tv>;
 582
 583   /**
 584    * Returns a `Set` containing the values from the specified `array`.
 585    *
 586    * This function is deprecated. Use `new Set ($arr)` instead.
 587    *
 588    * @param $arr - The `array` to convert to a `Set`.
 589    *
 590    * @return - A `Set` with the values from the provided `array`.
 591    */
 592   <<__Deprecated('Use `new Set($arr)` instead.')>>
 593   public static function fromArray<T>(array<T, Tv> $arr): Set<Tv>;
 594
 595   /**
 596    * Returns a `Set` containing all the values from the specified `array`(s).
 597    *
 598    * @param ... - The `array`s to convert to a `Set`.
 599    *
 600    * @return - A `Set` with the values from the passed `array`(s).
 601    */
 602   public static function fromArrays(...): Set<Tv>;
 603
 604   /**
 605    * Creates a `Set` from the given `Traversable`, or an empty `Set` if `null`
 606    * is passed.
 607    *
 608    * This is the static method version of the `Set::__construct()` constructor.
 609    *
 610    * @param $items - any `Traversable` object from which to create a `Set`
 611    *                 (e.g., `array`). If `null`, then an empty `Set` is created.
 612    *
 613    * @return - A `Set` with the values from the `Traversable`; or an empty `Set`
 614    *           if the `Traversable` is `null`.
 615    */
 616   public static function fromItems<Tv2>(?Traversable<Tv2> $items): Set<Tv2>;
 617
 618   /**
 619    * Creates a `Set` from the keys of the specified container.
 620    *
 621    * The keys of the container will be the values of the `Set`.
 622    *
 623    * @param $container - The container with the keys used to create the `Set`.
 624    *
 625    * @return - A `Set` built from the keys of the specified container.
 626    */
 627   public static function fromKeysOf<Tk, Tv2>(
 628     ?KeyedContainer<Tk,Tv2> $container,
 629   ): Set<Tk>;
 630
 631   /**
 632    * Returns the `string` version of the current `Set`, which is `"Set"`.
 633    *
 634    * @return - The `string` `"Set"`.
 635    */
 636   public function __toString(): string;
 637
 638   /**
 639    * Returns an `Iterable` view of the current `Set`.
 640    *
 641    * The `Iterable` returned is one that produces the values from the current
 642    * `Set`.
 643    *
 644    * @return - The `Iterable` view of the current `Set`.
 645    */
 646   public function items(): Iterable<Tv>;
 647 }
 648
 649 /**
 650  * @internal
 651  *
 652  * Methods and functions should take and return the KeyedIterator interface.
 653  */
 654 class SetIterator<+Tv> implements KeyedIterator<mixed, Tv> {
 655   public function __construct();
 656   public function current(): Tv;
 657   public function key(): mixed;
 658   public function valid(): bool;
 659   public function next(): void;
 660   public function rewind(): void;
 661 }