| blob | 16abbf44d8271548176f258ee1dd888c159072e7 |
1 <?hh // partial
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 */
12 /**
13 * This file provides type information for some of PHP's predefined interfaces
14 *
15 * YOU SHOULD NEVER INCLUDE THIS FILE ANYWHERE!!!
16 */
18 /**
19 * Represents an entity that can be iterated over using `foreach`, without
20 * requiring a key.
21 *
22 * The iteration variable will have a type of `T`.
23 *
24 * In addition to Hack collections, PHP `array`s and anything that implement
25 * `Iterator` are `Traversable`.
26 *
27 * In general, if you are implementing your own Hack class, you will want to
28 * implement `Iterable` instead of `Traversable` since `Traversable` is more
29 * of a bridge for PHP `array`s to work well with Hack collections.
30 *
31 * @guide /hack/collections/introduction
32 * @guide /hack/collections/interfaces
33 */
34 interface Traversable<+Tv> {}
36 /**
37 * Represents an entity that can be iterated over using `foreach`, allowing
38 * a key.
39 *
40 * The iteration variables will have a type of `Tk` for the key and `Tv` for the
41 * value.
42 *
43 * In addition to Hack collections, PHP `array`s and anything that implement
44 * `KeyedIterator` are `KeyedTraversable`.
45 *
46 * In general, if you are implementing your own Hack class, you will want to
47 * implement `KeyedIterable` instead of `KeyedTraversable` since
48 * `KeyedTraversable` is more of a bridge for PHP `array`s to work well with
49 * Hack collections.
50 *
51 * @guide /hack/collections/introduction
52 * @guide /hack/collections/interfaces
53 */
54 interface KeyedTraversable<+Tk, +Tv> extends Traversable<Tv> {}
56 /**
57 * Represents an entity that can be iterated over using `foreach`, without
58 * requiring a key, except it does not include objects that implement
59 * `Iterator`.
60 *
61 * The iteration variable will have a type of `T`.
62 *
63 * In addition to Hack collections, PHP `array`s are `Container`s.
64 *
65 * @guide /hack/collections/introduction
66 * @guide /hack/collections/interfaces
67 */
68 interface Container<+Tv> extends Traversable<Tv> {}
70 /**
71 * Represents an entity that can be iterated over using `foreach`, allowing
72 * a key, except it does not include objects that implement `KeyedIterator` nor
73 * `Set` and `ImmSet`.
74 *
75 * The iteration variables will have a type of `Tk` for the key and `Tv` for the
76 * value.
77 *
78 * In addition to Hack collections, PHP `array`s are `KeyedContainer`s.
79 *
80 * @guide /hack/collections/introduction
81 * @guide /hack/collections/interfaces
82 */
83 interface KeyedContainer<+Tk, +Tv> extends Container<Tv>, KeyedTraversable<Tk, Tv> {}
85 /**
86 * Represents an entity that can be indexed using square-bracket syntax.
87 *
88 * Square bracket syntax is:
89 *
90 * ```
91 * $indexish[$key]
92 * ```
93 *
94 * At this point, this includes entities with keys of `int` and `string`.
95 *
96 * In addition to Hack collections, PHP `array`s are `Indexish`.
97 *
98 * @guide /hack/collections/introduction
99 * @guide /hack/collections/interfaces
100 * @guide /hack/collections/read-write
101 */
102 interface Indexish<+Tk, +Tv> extends KeyedContainer<Tk, Tv> {}
104 /**
105 * For those entities that are `Traversable`, the `Iterator` interfaces provides
106 * the methods of iteration.
107 *
108 * If a class implements `Iterator`, then it provides the infrastructure to be
109 * iterated over using a `foreach` loop.
110 *
111 * @guide /hack/collections/introduction
112 * @guide /hack/collections/interfaces
113 *
114 * @link http://php.net/manual/en/class.iterator.php
115 */
116 interface Iterator<+Tv> extends Traversable<Tv> {
117 /**
118 * Return the current value at the current iterator position.
119 *
120 * @return - The current value of type `Tv`.
121 */
122 public function current(): Tv;
123 /**
124 * Move the iterator position to the next element.
125 *
126 */
127 public function next(): void;
128 /**
129 * Rewind the iterator position to its beginning.
130 *
131 * This rewinds back to the first element of the `Iterator`.
132 */
133 public function rewind(): void;
134 /**
135 * Checks to see if the current iterator position is valid.
136 *
137 * This method is called after `rewind()` and `next()` to check if the
138 * current iterator position is valid.
139 *
140 * @return - `true` if the position is valid; `false` otherwise.
141 */
142 public function valid(): bool;
143 }
145 /**
146 * Allows for the iteration over the values provided by an `async` function.
147 *
148 * If an `async` function returns an `AsyncIterator<T>`, then you can iterate
149 * over the `T` values returned from that function.
150 *
151 * ```
152 * async function countdown(int $start): AsyncIterator<int> { ... }
153 *
154 * async function use_countdown(): Awaitable<void> {
155 * $async_iter = countdown(100);
156 * foreach ($async_gen await as $value) { ... }
157 * }
158 * ```
159 *
160 * @guide /hack/async/introduction
161 * @guide /hack/async/guidelines
162 */
163 interface AsyncIterator<+Tv> {
164 /**
165 * Move the async iterator to the next `Awaitable` position.
166 *
167 * ```
168 * foreach ($async_iter await $async_iter->next() $value)
169 * ```
170 *
171 * The above is the longhand syntax for `await as $value`.
172 *
173 * @return - The next `Awaitable` in the iterator sequence.
174 */
175 public function next(): Awaitable<?(mixed, Tv)>;
176 }
178 /**
179 * Allows for the iteration over the keys and values provided by an `async`
180 * function.
181 *
182 * If an `async` function returns an `AsyncIterator<Tk, Tv>`, then you can
183 * iterate over the `Tk` and `Tv` values returned from that function.
184 *
185 * ```
186 * async function countdown(int $start): AsyncIterator<int, string> { ... }
187 *
188 * async function use_countdown(): Awaitable<void> {
189 * $async_iter = countdown(100);
190 * foreach ($async_gen await as $num => $str) { ... }
191 * }
192 * ```
193 *
194 * @guide /hack/async/introduction
195 * @guide /hack/async/guidelines
196 */
197 interface AsyncKeyedIterator<+Tk, +Tv> extends AsyncIterator<Tv> {
198 /**
199 * Move the async iterator to the next `Awaitable` position.
200 *
201 * ```
202 * foreach ($async_iter await $async_iter->next() $key=>$value)
203 * ```
204 *
205 * The above is the longhand syntax for `await as $key=>$value`.
206 *
207 * @return - The next `Awaitable` in the iterator sequence.
208 */
209 public function next(): Awaitable<?(Tk, Tv)>;
210 }
212 /**
213 * For those entities that are `KeyedTraversable`, the `KeyedIterator`
214 * interfaces provides the methods of iteration, included being able to get
215 * the key.
216 *
217 * If a class implements `KeyedIterator`, then it provides the infrastructure
218 * to be iterated over using a `foreach` loop.
219 *
220 * @guide /hack/collections/introduction
221 * @guide /hack/collections/interfaces
222 */
223 interface KeyedIterator<+Tk, +Tv> extends KeyedTraversable<Tk,Tv>, Iterator<Tv> {
224 /**
225 * Return the current key at the current iterator position.
226 *
227 * @return - The current key of type `Tk`.
228 */
229 public function key(): Tk;
230 }
232 /**
233 * Represents objects that can produce an `Iterator` object to iterate over
234 * their contents using `foreach`.
235 *
236 * Normally, this interface won't be used in type annotations; rather `Iterable`
237 * or `Traversable` will be the better interface.
238 *
239 * @guide /hack/collections/introduction
240 * @guide /hack/collections/interfaces
241 *
242 * @link http://php.net/manual/en/class.iteratoraggregate.php
243 */
244 interface IteratorAggregate<+Tv> extends Traversable<Tv> {
245 /**
246 * Returns an iterator to be used to iterate over the object's elements.
247 *
248 * @return - An `Iterator` for iteration.
249 */
250 public function getIterator(): Iterator<Tv>;
251 }
253 /**
254 * Represents any entity that can be iterated over using something like
255 * `foreach`. The entity does not necessarily have to have a key, just values.
256 *
257 * `Iterable` does not include `array`s.
258 *
259 * @guide /hack/collections/introduction
260 * @guide /hack/collections/interfaces
261 */
262 interface Iterable<+Tv> extends IteratorAggregate<Tv> {
263 /**
264 * Returns an iterator that points to beginning of the current `Iterable`.
265 *
266 * @return - An `Iterator` that allows you to traverse the current `Iterable`.
267 */
268 public function getIterator(): Iterator<Tv>;
269 /**
270 * Returns an `array` converted from the current `Iterable`.
271 *
272 * @return - an array converted from the current `Iterable`.
273 */
274 public function toArray(): array;
275 /**
276 * Returns an `array` with the values from the current `Iterable`.
277 *
278 * The keys in the current `Iterable` are discarded and replaced with integer
279 * indices, starting with 0.
280 *
281 * @return - an `array` containing the values from the current `Iterable`.
282 */
283 public function toValuesArray(): array;
284 /* HH_FIXME[4120]: While this violates our variance annotations, we are
285 * returning a copy of the underlying collection, so it is actually safe
286 * See #6853603. */
287 /**
288 * Returns a `Vector` converted from the current `Iterable`.
289 *
290 * Any keys in the current `Iterable` are discarded and replaced with integer
291 * indices, starting with 0.
292 *
293 * @return - a `Vector` converted from the current `Iterable`.
294 */
295 public function toVector(): Vector<Tv>;
296 /**
297 * Returns an immutable vector (`ImmVector`) converted from the current
298 * `Iterable`.
299 *
300 * Any keys in the current `Iterable` are discarded and replaced with integer
301 * indices, starting with 0.
302 *
303 * @return - an `ImmVector` converted from the current `Iterable`.
304 */
305 public function toImmVector(): ImmVector<Tv>;
306 /* HH_FIXME[4120]: While this violates our variance annotations, we are
307 * returning a copy of the underlying collection, so it is actually safe.
308 * See #6853603. */
309 /**
310 * Returns a `Set` converted from the current `Iterable`.
311 *
312 * Any keys in the current `Iterable` are discarded.
313 *
314 * @return - a `Set` converted from the current `Iterable`.
315 */
316 public function toSet(): Set<Tv>;
317 /**
318 * Returns an immutable set (`ImmSet`) converted from the current `Iterable`.
319 *
320 * Any keys in the current `Iterable` are discarded.
321 *
322 * @return - an `ImmSet` converted from the current `Iterable`.
323 */
324 public function toImmSet(): ImmSet<Tv>;
325 /**
326 * Returns a lazy, access elements only when needed view of the current
327 * `Iterable`.
328 *
329 * Normally, memory is allocated for all of the elements of the `Iterable`.
330 * With a lazy view, memory is allocated for an element only when needed or
331 * used in a calculation like in `map()` or `filter()`.
332 *
333 * @return - an `Iterable` representing the lazy view into the current
334 * `Iterable`.
335 *
336 * @guide /hack/collections/examples
337 */
338 public function lazy(): Iterable<Tv>;
339 /**
340 * Returns an `Iterable` containing the current `Iterable`'s values.
341 *
342 * Any keys are discarded.
343 *
344 * @return An `Iterable` with the values of the current `Iterable`.
345 */
346 public function values(): Iterable<Tv>;
347 /**
348 * Returns an `Iterable` containing the values after an operation has been
349 * applied to each value in the current `Iterable`.
350 *
351 * Every value in the current `Iterable` is affected by a call to `map()`,
352 * unlike `filter()` where only values that meet a certain criteria are
353 * affected.
354 *
355 * @param $fn - The callback containing the operation to apply to the
356 * `Iterable` values.
357 *
358 * @return - an `Iterable` containing the values after a user-specified
359 * operation is applied.
360 *
361 * @guide /hack/collections/examples
362 */
363 public function map<Tu>((function(Tv): Tu) $fn): Iterable<Tu>;
364 /**
365 * Returns an `Iterable` containing the values of the current `Iterable` that
366 * meet a supplied condition.
367 *
368 * Only values that meet a certain criteria are affected by a call to
369 * `filter()`, while all values are affected by a call to `map()`.
370 *
371 * @param $fn - The callback containing the condition to apply to the
372 * `Itearble` values.
373 *
374 * @return - an `Iterable` containing the values after a user-specified
375 * condition is applied.
376 *
377 * @guide /hack/collections/examples
378 */
379 public function filter((function(Tv): bool) $fn): Iterable<Tv>;
380 /**
381 * Returns an `Iterable` where each element is a `Pair` that combines the
382 * element of the current `Iterable` and the provided `Traversable`.
383 *
384 * If the number of elements of the `Iterable` are not equal to the number of
385 * elements in the `Traversable`, then only the combined elements up to and
386 * including the final element of the one with the least number of elements
387 * is included.
388 *
389 * @param $traversable - The `Traversable` to use to combine with the
390 * elements of the current `Iterable`.
391 *
392 * @return - The `Iterable` that combines the values of the current
393 * `Itearable` with the provided `Traversable`.
394 */
395 public function zip<Tu>(Traversable<Tu> $traversable): Iterable<Pair<Tv, Tu>>;
396 /**
397 * Returns an `Iterable` containing the first `n` values of the current
398 * `Iterable`.
399 *
400 * The returned `Iterable` will always be a proper subset of the current
401 * `Iterable`.
402 *
403 * `$n` is 1-based. So the first element is 1, the second 2, etc.
404 *
405 * @param $n - The last element that will be included in the returned
406 * `Iterable`.
407 *
408 * @return - An `Iterable that is a proper subset of the current `Iterable`
409 * up to `n` elements.
410 */
411 public function take(int $n): Iterable<Tv>;
412 /**
413 * Returns an `Iterable` containing the values of the current `Iterable` up
414 * to but not including the first value that produces `false` when passed to
415 * the specified callback.
416 *
417 * The returned `Iterable` will always be a proper subset of the current
418 * `Iterable`.
419 *
420 * @param $fn - The callback that is used to determine the stopping
421 * condition.
422 *
423 * @return - An `Iterable` that is a proper subset of the current `Iterable`
424 * up until the callback returns `false`.
425 */
426 public function takeWhile((function(Tv): bool) $fn): Iterable<Tv>;
427 /**
428 * Returns an `Iterable` containing the values after the `n`-th element of the
429 * current `Iterable`.
430 *
431 * The returned `Iterable` will always be a proper subset of the current
432 * `Iterable`.
433 *
434 * `$n` is 1-based. So the first element is 1, the second 2, etc.
435 *
436 * @param $n - The last element to be skipped; the `$n+1` element will be
437 * the first one in the returned `Iterable`.
438 *
439 * @return - An `Iterable` that is a proper subset of the current `Iterable`
440 * containing values after the specified `n`-th element.
441 */
442 public function skip(int $n): Iterable<Tv>;
443 /**
444 * Returns an `Iterable` containing the values of the current `Iterable`
445 * starting after and including the first value that produces `true` when
446 * passed to the specified callback.
447 *
448 * The returned `Iterable` will always be a proper subset of the current
449 * `Iterable`.
450 *
451 * @param $fn - The callback used to determine the starting element for the
452 * returned `Iterable`.
453 *
454 * @return - An `Iterable` that is a proper subset of the current `Iterable`
455 * starting after the callback returns `true`.
456 */
457 public function skipWhile((function(Tv): bool) $fn): Iterable<Tv>;
458 /**
459 * Returns a subset of the current `Iterable` starting from a given key up
460 * to, but not including, the element at the provided length from the
461 * starting key.
462 *
463 * `$start` is 0-based. `$len` is 1-based. So `slice(0, 2)` would return the
464 * elements at key 0 and 1.
465 *
466 * The returned `Iterable` will always be a proper subset of the current
467 * `Iterable`.
468 *
469 * @param $start - The starting key of the current `Iterable` to begin the
470 * returned `Iterable`.
471 * @param $len - The length of the returned `Iterable`.
472 *
473 * @return - An `Iterable` that is a proper subset of the current `Iterable`
474 * starting at `$start` up to but not including the element
475 * `$start + $len`.
476 */
477 public function slice(int $start, int $len): Iterable<Tv>;
478 /**
479 * Returns an `Iterable` that is the concatenation of the values of the
480 * current `Iterable` and the values of the provided `Traversable`.
481 *
482 * The values of the provided `Traversable` is concatenated to the end of the
483 * current `Iterable` to produce the returned `Iterable`.
484 *
485 * @param $traversable - The `Traversable` to concatenate to the current
486 * `Iterable`.
487 *
488 * @return - The concatenated `Iterable`.
489 *
490 * @guide /hack/generics/constraints
491 */
492 public function concat<Tu super Tv>(
493 Traversable<Tu> $traversable
494 ): Iterable<Tu>;
495 /**
496 * Returns the first value in the current `Iterable`.
497 *
498 * @return - The first value in the current `Iterable`, or `null` if the
499 * current `Iterable` is empty.
500 */
501 public function firstValue(): ?Tv;
502 /**
503 * Returns the last value in the current `Iterable`.
504 *
505 * @return - The last value in the current `Iterable`, or `null` if the
506 * current `Iterable` is empty.
507 */
508 public function lastValue(): ?Tv;
509 }
511 /**
512 * Represents any entity that can be iterated over using something like
513 * `foreach`. The entity is required to have a key in addition to values.
514 *
515 * `KeyedIterable` does not include `array`s.
516 *
517 * @guide /hack/collections/introduction
518 * @guide /hack/collections/interfaces
519 */
520 interface KeyedIterable<Tk, +Tv> extends KeyedTraversable<Tk, Tv>, Iterable<Tv> {
521 /**
522 * Returns an iterator that points to beginning of the current
523 * `KeyedIterable`.
524 *
525 * @return - A `KeyedIterator` that allows you to traverse the current
526 * `KeyedIterable`.
527 */
528 public function getIterator(): KeyedIterator<Tk, Tv>;
529 /**
530 * Returns an `array` with the keys from the current `KeyedIterable`.
531 *
532 * @return - an `array` containing the values from the current
533 * `KeyedIterable`.
534 */
535 public function toKeysArray(): array;
536 /* HH_FIXME[4120]: While this violates our variance annotations, we are
537 * returning a copy of the underlying collection, so it is actually safe
538 * See #6853603. */
539 /**
540 * Returns a `Map` based on the keys and values of the current
541 * `KeyedIterable`.
542 *
543 * @return - a `Map` that has the keys and associated values of the current
544 * `KeyedIterable`.
545 */
546 public function toMap(): Map<Tk, Tv>;
547 /**
548 * Returns an immutable map (`ImmMap`) based on the keys and values of the
549 * current `KeyedIterable`.
550 *
551 * @return - an `ImmMap` that has the keys and associated values of the
552 * current `KeyedIterable`.
553 */
554 public function toImmMap(): ImmMap<Tk, Tv>;
555 /**
556 * Returns a lazy, access elements only when needed view of the current
557 * `KeyedIterable`.
558 *
559 * Normally, memory is allocated for all of the elements of the
560 * `KeyedIterable`. With a lazy view, memory is allocated for an element only
561 * when needed or used in a calculation like in `map()` or `filter()`.
562 *
563 * @return - a `KeyedIterable` representing the lazy view into the current
564 * `KeyedIterable`.
565 *
566 * @guide /hack/collections/examples
567 */
568 public function lazy(): KeyedIterable<Tk, Tv>;
569 /**
570 * Returns an `Iterable` containing the current `KeyedIterable`'s values.
571 *
572 * Any keys are discarded.
573 *
574 * @return An `Iterable` with the values of the current `KeyedIterable`.
575 */
576 public function values(): Iterable<Tv>;
577 /**
578 * Returns an `Iterable` containing the current `KeyedIterable`'s keys.
579 *
580 * Any values are discarded.
581 *
582 * @return An `Iterable` with the keys of the current `KeyedIterable`.
583 */
584 public function keys(): Iterable<Tk>;
585 /**
586 * Returns a `KeyedIterable` containing the values after an operation has been
587 * applied to each value in the current `KeyedIterable`.
588 *
589 * Every value in the current `KeyedIterable` is affected by a call to
590 * `map()`, unlike `filter()` where only values that meet a certain criteria
591 * are affected.
592 *
593 * @param $fn - The callback containing the operation to apply to the
594 * `KeyedIterable` values.
595 *
596 * @return - a `KeyedIterable` containing the values after a user-specified
597 * operation is applied.
598 *
599 * @guide /hack/collections/examples
600 */
601 public function map<Tu>((function(Tv): Tu) $fn): KeyedIterable<Tk, Tu>;
602 /**
603 * Returns a `KeyedIterable` containing the values after an operation has
604 * been applied to each key and value in the current `KeyedIterable`.
605 *
606 * Every key and value in the current `KeyedIterable` is affected by a call to
607 * `mapWithKey()`, unlike `filterWithKey()` where only values that meet a
608 * certain criteria are affected.
609 *
610 * @param $fn - The callback containing the operation to apply to the
611 * `KeyedIterable` keys and values.
612 *
613 * @return - a `KeyedIterable` containing the values after a user-specified
614 * operation on the current `KeyedIterable`'s keys and values is
615 * applied.
616 */
617 public function mapWithKey<Tu>((function(Tk, Tv): Tu) $fn):
618 KeyedIterable<Tk, Tu>;
619 /**
620 * Returns a `KeyedIterable` containing the values of the current
621 * `KeyedIterable` that meet a supplied condition.
622 *
623 * Only values that meet a certain criteria are affected by a call to
624 * `filter()`, while all values are affected by a call to `map()`.
625 *
626 * @param $fn - The callback containing the condition to apply to the
627 * `KeyedItearble` values.
628 *
629 * @return - a `KeyedIterable` containing the values after a user-specified
630 * condition is applied.
631 *
632 * @guide /hack/collections/examples
633 */
634 public function filter((function(Tv): bool) $fn): KeyedIterable<Tk, Tv>;
635 /**
636 * Returns a `KeyedIterable` containing the values of the current
637 * `KeyedIterable` that meet a supplied condition applied to its keys and
638 * values.
639 *
640 * Only keys and values that meet a certain criteria are affected by a call to
641 * `filterWithKey()`, while all values are affected by a call to
642 * `mapWithKey()`.
643 *
644 * @param $fn - The callback containing the condition to apply to the
645 * `KeyedIterable` keys and values.
646 *
647 * @return - a `KeyedIterable` containing the values after a user-specified
648 * condition is applied to the keys and values of the current
649 * `KeyedIterable`.
650 *
651 */
652 public function filterWithKey((function(Tk, Tv): bool) $fn):
653 KeyedIterable<Tk, Tv>;
654 /**
655 * Returns a `KeyedIterable` where each element is a `Pair` that combines the
656 * element of the current `KeyedIterable` and the provided `Traversable`.
657 *
658 * If the number of elements of the `KeyedIterable` are not equal to the
659 * number of elements in the `Traversable`, then only the combined elements
660 * up to and including the final element of the one with the least number of
661 * elements is included.
662 *
663 * @param $traversable - The `Traversable` to use to combine with the
664 * elements of the current `KeyedIterable`.
665 *
666 * @return - The `KeyedIterable` that combines the values of the current
667 * `KeyedItearable` with the provided `Traversable`.
668 */
669 public function zip<Tu>(Traversable<Tu> $traversable):
670 KeyedIterable<Tk, Pair<Tv, Tu>>;
671 /**
672 * Returns a `KeyedIterable` containing the first `n` values of the current
673 * `KeyedIterable`.
674 *
675 * The returned `KeyedIterable` will always be a proper subset of the current
676 * `Iterable`.
677 *
678 * `$n` is 1-based. So the first element is 1, the second 2, etc.
679 *
680 * @param $n - The last element that will be included in the returned
681 * `KeyedIterable`.
682 *
683 * @return - A `KeyedIterable that is a proper subset of the current
684 * `KeyedIterable` up to `n` elements.
685 */
686 public function take(int $n): KeyedIterable<Tk, Tv>;
687 /**
688 * Returns a `KeyedIterable` containing the values of the current
689 * `KeyedIterable` up to but not including the first value that produces
690 * `false` when passed to the specified callback.
691 *
692 * The returned `KeyedIterable` will always be a proper subset of the current
693 * `KeyedIterable`.
694 *
695 * @param $fn - The callback that is used to determine the stopping
696 * condition.
697 *
698 * @return - A `KeyedIterable` that is a proper subset of the current
699 * `KeyedIterable` up until the callback returns `false`.
700 */
701 public function takeWhile((function(Tv): bool) $fn): KeyedIterable<Tk, Tv>;
702 /**
703 * Returns a `KeyedIterable` containing the values after the `n`-th element
704 * of the current `KeyedIterable`.
705 *
706 * The returned `KeyedIterable` will always be a proper subset of the current
707 * `KeyedIterable`.
708 *
709 * `$n` is 1-based. So the first element is 1, the second 2, etc.
710 *
711 * @param $n - The last element to be skipped; the `$n+1` element will be
712 * the first one in the returned `KeyedIterable`.
713 *
714 * @return - A `KeyedIterable` that is a proper subset of the current
715 * `KeyedIterable` containing values after the specified `n`-th
716 * element.
717 */
718 public function skip(int $n): KeyedIterable<Tk, Tv>;
719 /**
720 * Returns a `KeyedIterable` containing the values of the current
721 * `KeyedIterable` starting after and including the first value that produces
722 * `true` when passed to the specified callback.
723 *
724 * The returned `KeyedIterable` will always be a proper subset of the current
725 * `KeyedIterable`.
726 *
727 * @param $fn - The callback used to determine the starting element for the
728 * returned `KeyedIterable`.
729 *
730 * @return - A `KeyedIterable` that is a proper subset of the current
731 * `KeyedIterable` starting after the callback returns `true`.
732 */
733 public function skipWhile((function(Tv): bool) $fn): KeyedIterable<Tk, Tv>;
734 /**
735 * Returns a subset of the current `KeyedIterable` starting from a given key
736 * up to, but not including, the element at the provided length from the
737 * starting key.
738 *
739 * `$start` is 0-based. `$len` is 1-based. So `slice(0, 2)` would return the
740 * elements at key 0 and 1.
741 *
742 * The returned `KeyedIterable` will always be a proper subset of the current
743 * `KeyedIterable`.
744 *
745 * @param $start - The starting key of the current `KeyedIterable` to begin
746 * the returned `KeyedIterable`.
747 * @param $len - The length of the returned `KeyedIterable`.
748 *
749 * @return - A `KeyedIterable` that is a proper subset of the current
750 * `KeyedIterable` starting at `$start` up to but not including the
751 * element `$start + $len`.
752 */
753 public function slice(int $start, int $len): KeyedIterable<Tk, Tv>;
754 /**
755 * Returns an `Iterable` that is the concatenation of the values of the
756 * current `KeyedIterable` and the values of the provided `Traversable`.
757 *
758 * The values of the provided `Traversable` is concatenated to the end of the
759 * current `KeyedIterable` to produce the returned `Iterable`.
760 *
761 * @param $traversable - The `Traversable` to concatenate to the current
762 * `KeyedIterable`.
763 *
764 * @return - The concatenated `Iterable`.
765 *
766 * @guide /hack/generics/constraints
767 */
768 public function concat<Tu super Tv>(
769 Traversable<Tu> $traversable
770 ): Iterable<Tu>;
771 /**
772 * Returns the first value in the current `KeyedIterable`.
773 *
774 * @return - The first value in the current `KeyedIterable`, or `null` if the
775 * current `KeyedIterable` is empty.
776 */
777 public function firstValue(): ?Tv;
778 /**
779 * Returns the first key in the current `KeyedIterable`.
780 *
781 * @return - The first key in the current `KeyedIterable`, or `null` if the
782 * current `KeyedIterable` is empty.
783 */
784 public function firstKey(): ?Tk;
785 /**
786 * Returns the last value in the current `KeyedIterable`.
787 *
788 * @return - The last value in the current `KeyedIterable`, or `null` if the
789 * current `KeyedIterable` is empty.
790 */
791 public function lastValue(): ?Tv;
792 /**
793 * Returns the last key in the current `KeyedIterable`.
794 *
795 * @return - The last key in the current `KeyedIterable`, or `null` if the
796 * current `KeyedIterable` is empty.
797 */
798 public function lastKey(): ?Tk;
799 }
801 interface Serializable {
802 public function serialize(): string;
803 public function unserialize($serialized): void;
804 }
806 interface Countable {
807 public function count(): int;
808 }
810 abstract final class dict<+Tk as arraykey, +Tv> implements Indexish<Tk, Tv> {}
812 interface RecursiveIterator<Tv> extends Iterator<Tv> {
813 public function getChildren(): this;
814 public function hasChildren(): bool;
815 }
817 interface SeekableIterator<Tv> extends Iterator<Tv> {
818 public function seek(int $position): void;
819 }
821 interface OuterIterator<Tv> extends Iterator<Tv> {
822 public function getInnerIterator(): Iterator<Tv>;
823 }
825 interface ArrayAccess<Tk, Tv> {
826 public function offsetExists(Tk $key): bool;
827 public function offsetGet(Tk $key): Tv;
828 public function offsetSet(Tk $key, Tv $val): void;
829 public function offsetUnset(Tk $key): void;
830 }
832 interface Awaitable<+T> {
833 public function getWaitHandle(): WaitHandle<T>;
834 }
836 /**
837 * @see http://www.php.net/manual/en/jsonserializable.jsonserialize.php
838 */
839 interface JsonSerializable {
840 /**
841 * Return data which can be serialized with json_encode.
842 */
843 public function jsonSerialize(): mixed;
844 }
846 /**
847 * XHPChild is the base type of values that can be children of XHP elements.
848 * Most primitive types implement XHPChild: string, int, float, and array.
849 *
850 * Classes that implement XHPChild must do so by implementing the XHPChildClass
851 * subinterface.
852 */
853 interface XHPChild {}
855 /**
856 * Stringish is a type that matches strings as well as string-convertible
857 * objects: that is, objects that provide the __toString method
858 */
859 interface Stringish {
860 public function __toString(): string;
861 }
863 /**
864 * Classes that implement IMemoizeParam may be used as parameters on
865 * <<__Memoize>> functions
866 *
867 * @guide /hack/attributes/introduction
868 * @guide /hack/attributes/special
869 */
870 interface IMemoizeParam {
871 /**
872 * Serialize this object to a string that can be used as a
873 * dictionary key to differentiate instances of this class.
874 */
875 public function getInstanceKey(): string;
876 }