hphp/hack/hhi/collections/Vector.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  * Vector is a stack-like collection. HHVM provides a native implementation
  20  * for this class. The PHP class definition below is not actually used at run
  21  * time; it is simply provided for the typechecker and for developer reference.
  22  *
  23  * Like all objects in PHP, Vectors have reference-like semantics. When a
  24  * caller passes a Vector to a callee, the callee can modify the Vector and the
  25  * caller will see the changes. Vectors do not have "copy-on-write" semantics.
  26  *
  27  * Vectors only support integer keys. If a non-integer key is used, an
  28  * exception will be thrown.
  29  *
  30  * Vectors suoport "$m[$k]" style syntax for getting and setting values by
  31  * key. Vectors also support "isset($m[$k])" and "empty($m[$k])" syntax, and
  32  * they provide similar semantics as arrays. Elements can be added to a Vector
  33  * using "$m[] = .." syntax.
  34  *
  35  * Vectors do not support iterating while new elements are being added or
  36  * elements are being removed. When a new element is added or removed, all
  37  * iterators that point to the Vector shall be considered invalid.
  38  *
  39  * Vectors do not support taking elements by reference. If binding assignment
  40  * (=&) is used with an element of a Vector, or if an element of a Vector is
  41  * passed by reference, of if a Vector is used with foreach by reference, an
  42  * exception will be thrown.
  43  */
  44
  45 final class Vector<Tv> implements MutableVector<Tv> {
  46   /**
  47    * Creates a Vector from the given Traversable, or an empty Vector
  48    * if "null" is passed.
  49    */
  50   public function __construct(?Traversable<Tv> $it);
  51
  52   /**
  53    * Returns an array containing the values from this Vector.
  54    */
  55   public function toArray(): array<Tv>;
  56
  57   /**
  58    * Returns an array containing the values from this Vector.
  59    */
  60   public function toValuesArray(): array;
  61
  62   /**
  63    * Returns an array whose values are the keys from this Vector.
  64    */
  65   public function toKeysArray(): array;
  66
  67   public function toVector(): Vector<Tv>;
  68   public function toImmVector(): ImmVector<Tv>;
  69   public function toMap(): Map<int, Tv>;
  70   public function toImmMap(): ImmMap<int, Tv>;
  71   public function toSet(): Set<Tv>;
  72   public function toImmSet(): ImmSet<Tv>;
  73   public function immutable(): ImmVector<Tv>;
  74   public function lazy(): KeyedIterable<int, Tv>;
  75   public function values(): Vector<Tv>;
  76   public function keys(): Vector<int>;
  77   public function map<Tu>((function(Tv): Tu) $callback): Vector<Tu>;
  78   public function mapWithKey<Tu>((function(int, Tv): Tu) $callback): Vector<Tu>;
  79   public function filter((function(Tv): bool) $callback): Vector<Tv>;
  80   public function filterWithKey((function(int, Tv): bool) $callback):
  81     Vector<Tv>;
  82   public function zip<Tu>(Traversable<Tu> $traversable): Vector<Pair<Tv, Tu>>;
  83
  84   /**
  85    * Returns a Vector containing the first n values of this Vector.
  86    */
  87   public function take(int $n): Vector<Tv>;
  88
  89   /**
  90    * Returns a Vector containing the values of this Vector up to but not
  91    * including the first value that produces false when passed to the specified
  92    * callback.
  93    */
  94   public function takeWhile((function(Tv): bool) $fn): Vector<Tv>;
  95
  96   public function skip(int $n): Vector<Tv>;
  97   public function skipWhile((function(Tv): bool) $fn): Vector<Tv>;
  98   public function slice(int $start, int $len): Vector<Tv>;
  99   public function concat<Tu super Tv>(Traversable<Tu> $traversable): Vector<Tu>;
 100   public function firstValue(): ?Tv;
 101   public function firstKey(): ?int;
 102   public function lastValue(): ?Tv;
 103   public function lastKey(): ?int;
 104
 105   /**
 106    * Returns true if the Vector is empty, false otherwise.
 107    */
 108   public function isEmpty(): bool;
 109
 110   /**
 111    * Returns the number of elements in this Vector.
 112    */
 113   public function count(): int;
 114
 115   /**
 116    * Returns the value at the specified key. If the key is not present,
 117    * an exception is thrown. "$v = $vec->at($k)" is semantically equivalent
 118    * to "$v = $vec[$k]".
 119    */
 120   public function at(int $k): Tv;
 121
 122   /**
 123    * Returns the value at the specified key. If the key is not present,
 124    * null is returned.
 125    */
 126   public function get(int $k): ?Tv;
 127
 128   /**
 129    * Stores a value into the Vector with the specified key, overwriting the
 130    * previous value associated with the key. If the key is not present,
 131    * an exception is thrown. "$vec->set($k,$v)" is semantically equivalent
 132    * to "$vec[$k] = $v" (except that set() returns the Vector).
 133    */
 134   public function set(int $k, Tv $v): Vector<Tv>;
 135
 136   public function setAll(?KeyedTraversable<int, Tv> $it): Vector<Tv>;
 137
 138   /**
 139    * Remove all the elements from this Vector.
 140    */
 141   public function clear(): Vector<Tv>;
 142
 143   /**
 144    * Returns true if the specified key is present in the Vector, returns
 145    * false otherwise.
 146    */
 147   public function containsKey<Tu super int>(Tu $k): bool;
 148
 149   /**
 150    * Append a copy of a value to the end of the Vector, assigning the next
 151    * available integer key. "$vec->add($v)" is semantically equivalent to
 152    * "$vec[] = $v" (except that add() returns the Vector).
 153    */
 154   public function add(Tv $value): Vector<Tv>;
 155
 156   public function addAll(?Traversable<Tv> $it): Vector<Tv>;
 157
 158   /**
 159    * Adds the keys of the specified container to this Vector and returns itself.
 160    */
 161   public function addAllKeysOf<Tv2>(
 162     ?KeyedContainer<Tv,Tv2> $container,
 163   ): Vector<Tv>;
 164
 165   /**
 166    * Removes the specified key from this Vector. This will cause elements
 167    * with higher keys to be renumbered.
 168    */
 169   public function removeKey(int $k): Vector<Tv>;
 170
 171   /**
 172    * Remove the last element of this Vector and return it. This function
 173    * throws an exception if this Vector is empty.
 174    */
 175   public function pop(): Tv;
 176
 177   /**
 178    * Resize this Vector to contain 'sz' elements. If 'sz' is smaller than
 179    * the current size of this Vector, elements are removed from the end of
 180    * this Vector. If 'sz' is greater than the current size of this Vector,
 181    * this Vector is extended by appending as many copies of 'value' as
 182    * needed to reach a size of 'sz' elements.
 183    */
 184   public function resize(int $sz, Tv $value): void;
 185
 186   /**
 187    * Reserves enough memory to accommodate 'sz' elements. If 'sz' is less than or
 188    * equal to the current capacity of this Vector, does nothing.
 189    */
 190   public function reserve(int $sz): void;
 191
 192   /**
 193    * Returns an iterator that points to beginning of this Vector.
 194    */
 195   public function getIterator(): KeyedIterator<int, Tv>;
 196
 197   /**
 198    * Reverse the elements of this Vector in place.
 199    */
 200   public function reverse(): void;
 201
 202   /**
 203    * Splice this Vector in place. This function provides the functionality
 204    * of array_splice() for Vectors. Note that this function modifies this
 205    * Vector in place.
 206    */
 207   public function splice(int $offset, ?int $len = null): void;
 208
 209   /**
 210    * Returns the index of the first element that matches the search value.
 211    * If no element matches the search value, this function returns -1.
 212    */
 213   public function linearSearch<Tu super Tv>(Tu $search_value): int;
 214
 215   /**
 216    * Shuffles the values of the Vector randomly in place.
 217    */
 218   public function shuffle(): void;
 219
 220   /**
 221    * Returns a Vector containing the values from the specified array.
 222    */
 223   <<__Deprecated('Use `new Vector()` instead.')>>
 224   public static function fromArray<T>(array<T, Tv> $arr): Vector<Tv>;
 225
 226   public static function fromItems(?Traversable<Tv> $items): Vector<Tv>;
 227
 228   /**
 229    * Returns a Vector built from the keys of the specified container.
 230    */
 231   public static function fromKeysOf<Tk,Tv2>(
 232     ?KeyedContainer<Tk,Tv2> $container
 233   ): Vector<Tk>;
 234
 235   public function __toString(): string;
 236
 237   public function items(): Iterable<Tv>;
 238 }
 239
 240 class VectorIterator<+Tv> implements KeyedIterator<int, Tv> {
 241   public function __construct();
 242   public function rewind(): void;
 243   public function current(): Tv;
 244   public function key(): int;
 245   public function next(): void;
 246   public function valid(): bool;
 247 }