Map.hhi

<?hh
/**
 * Copyright (c) 2014, Facebook, Inc.
 * All rights reserved.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the "hack" directory of this source tree.
 *
 */

/**
 * This file provides type information for some of HHVM's builtin classes.
 *
 * YOU SHOULD NEVER INCLUDE THIS FILE ANYWHERE!!!
 */

namespace HH {

  /**
   * `Map` is an ordered dictionary-style collection. HHVM provides a native
   * implementation for this class. The PHP class definition below is not
   * actually used at run time; it is simply provided for the typechecker and for
   * developer reference.
   *
   * Like all objects in PHP, `Map`s have reference-like semantics. When a caller
   * passes a `Map` to a callee, the callee can modify the `Map` and the caller
   * will see the changes. `Map`s do not have "copy-on-write" semantics.
   *
   * `Map`s preserve insertion order of key/value pairs. When iterating over a
   * `Map`, the key/value pairs appear in the order they were inserted. Also,
   * `Map`s do not automagically convert integer-like `string` keys (ex. `"123"`)
   * into integer keys.
   *
   * `Map`s only support `int` keys and `string` keys. If a key of a different
   * type is used, an exception will be thrown.
   *
   * `Map`s support `$m[$k]` style syntax for getting and setting values by key.
   * `Map`s also support `isset($m[$k])` and `empty($m[$k])` syntax, and they
   * provide similar semantics as arrays. Adding an element with square bracket
   * syntax `[]` is supported either by providing a key between the brackets or
   * a `Pair` on the right-hand side. e.g.,
   * `$m[$k] = $v` is supported
   * `$m[] = Pair {$k, $v}` is supported
   * `$m[] = $v` is not supported.
   *
   * `Map`s do not support iterating while new keys are being added or elements
   * are being removed. When a new key is added or an element is removed, all
   * iterators that point to the `Map` shall be considered invalid.
   *
   * `Map`s do not support taking elements by reference. If binding assignment
   * (`=&`) is used with an element of a `Map`, or if an element of a `Map` is
   * passed by reference, of if a `Map` is used with `foreach` by reference, an
   * exception will be thrown.
   *
   * @guide /hack/collections/introduction
   * @guide /hack/collections/classes
   */

  final class Map<Tk as arraykey, Tv> implements \MutableMap<Tk, Tv> {
    /**
     * Creates a `Map` from the given `KeyedTraversable`, or an empty `Map` if
     * `null` is passed.
     *
     * @param $it - any `Traversable` object from which to create a `Map`
     *              (e.g., `array`). If `null`, then an empty `Map` is created.
     */
    <<__Rx, __AtMostRxAsArgs>>
    public function __construct(
      <<__MaybeMutable, __OnlyRxIfImpl(\HH\Rx\KeyedTraversable::class)>>
      ?KeyedTraversable<Tk, Tv> $it,
    );

    /**
     * Returns an `array` containing the key/value pairs from the current `Map`.
     *
     * @return - an `array` containing the key and value pairs from the current
     *           `Map`.
     */
    <<__Rx, __MaybeMutable, __PHPStdLib>>
    public function toArray(): array<Tk, Tv>;

    /**
     * Returns an `array` containing the values from the current `Map`.
     *
     * @return - an integer-indexed `array` containing the values from the
     *           current `Map`.
     */
    <<__Rx, __MaybeMutable>>
    public function toValuesArray(): varray<Tv>;

    /**
     * Returns an `array` whose values are the keys of the current `Map`.
     *
     * @return - an integer-indexed `array` containing the keys from the current
     *           `Map`.
     */
    <<__Rx, __MaybeMutable>>
    public function toKeysArray(): varray<Tk>;

    /**
     * Returns a `Vector` with the values of the current `Map`.
     *
     * @return - a `Vector` that contains the values of the current `Map`.
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function toVector(): Vector<Tv>;

    /**
     * Returns an immutable vector (`ImmVector`) with the values of the current
     * `Map`.
     *
     * @return - an `ImmVector` that is an immutable copy of the current `Map`.
     */
    <<__Rx, __MaybeMutable>>
    public function toImmVector(): ImmVector<Tv>;

    /**
     * Returns a deep copy of the current `Map`.
     *
     * @return - a `Map` that is a deep copy of the current `Map`.
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function toMap(): Map<Tk, Tv>;

    /**
     * Returns a deep, immutable copy (`ImmMap`) of the current `Map`.
     *
     * @return - an `ImmMap` that is a copy of this `Map`.
     */
    <<__Rx, __MaybeMutable>>
    public function toImmMap(): ImmMap<Tk, Tv>;

    /**
     * Returns a `Set` based on the values of the current `Map`.
     *
     * @return - a `Set` with the current values of the current `Map`.
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function toSet(): Set<Tv> where Tv as arraykey ;

    /**
     * Returns an immutable set (`ImmSet`) based on the values of the current
     * `Map`.
     *
     * @return - an `ImmSet` with the current values of the current `Map`.
     */
    <<__Rx, __MaybeMutable>>
    public function toImmSet(): ImmSet<Tv> where Tv as arraykey ;

    /**
     * Returns a deep, immutable copy (`ImmMap`) of this `Map`.
     *
     * This method is interchangeable with `toImmMap()`.
     *
     * @return - an `ImmMap` that is a deep copy of this `Map`.
     */
    <<__Rx, __MaybeMutable>>
    public function immutable(): ImmMap<Tk, Tv>;

    /**
     * Returns a lazy, access elements only when needed view of the current
     * `Map`.
     *
     * Normally, memory is allocated for all of the elements of the `Map`. With
     * a lazy view, memory is allocated for an element only when needed or used
     * in a calculation like in `map()` or `filter()`.
     *
     * @return - a `KeyedIterable` representing the lazy view into the current
     *           `Map`.
     *
     * @guide /hack/collections/examples
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function lazy(): \HH\Rx\KeyedIterable<Tk, Tv>;

    /**
     * Returns a `Vector` containing the values of the current `Map`.
     *
     * This method is interchangeable with `toVector()`.
     *
     * @return - a `Vector` containing the values of the current `Map`.
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function values(): Vector<Tv>;

    /**
     * Returns a `Vector` containing the keys of the current `Map`.
     *
     * @return - a `Vector` containing the keys of the current `Map`.
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function keys(): Vector<Tk>;

    /**
     * Returns a `Map` after an operation has been applied to each value in the
     * current `Map`.
     *
     * Every value in the current `Map` is affected by a call to `map()`, unlike
     * `filter()` where only values that meet a certain criteria are affected.
     *
     * The keys will remain unchanged from the current `Map` to the returned
     * `Map`.
     *
     * @param $callback - The callback containing the operation to apply to the
     *                    current `Map` values.
     *
     * @return - a `Map` containing key/value pairs after a user-specified
     *           operation is applied.
     *
     * @guide /hack/collections/examples
     */
    <<__Rx, __AtMostRxAsArgs, __MutableReturn, __MaybeMutable>>
    public function map<Tu>(
      <<__AtMostRxAsFunc>> (function(Tv): Tu) $callback,
    ): Map<Tk, Tu>;

    /**
     * Returns a `Map` after an operation has been applied to each key and
     * value in the current `Map`.
     *
     * Every key and value in the current `Map` is affected by a call to
     * `mapWithKey()`, unlike `filterWithKey()` where only values that meet a
     * certain criteria are affected.
     *
     * The keys will remain unchanged from the current `Map` to the returned
     * `Map`. The keys are only used to help in the mapping operation.
     *
     * @param $callback - The callback containing the operation to apply to the
     *                    current `Map` keys and values.
     *
     * @return - a `Map` containing the values after a user-specified operation
     *           on the current `Map`'s keys and values is applied.
     */
    <<__Rx, __AtMostRxAsArgs, __MutableReturn, __MaybeMutable>>
    public function mapWithKey<Tu>(
      <<__AtMostRxAsFunc>> (function(Tk, Tv): Tu) $callback,
    ): Map<Tk, Tu>;

    /**
     * Returns a `Map` containing the values of the current `Map` that meet
     * a supplied condition.
     *
     * Only values that meet a certain criteria are affected by a call to
     * `filter()`, while all values are affected by a call to `map()`.
     *
     * The keys associated with the current `Map` remain unchanged in the returned
     * `Map`.
     *
     * @param $callback - The callback containing the condition to apply to the
     *                    current `Map` values.
     *
     * @return - a `Map` containing the values after a user-specified condition
     *           is applied.
     *
     * @guide /hack/collections/examples
     */
    <<__Rx, __AtMostRxAsArgs, __MutableReturn, __MaybeMutable>>
    public function filter(
      <<__AtMostRxAsFunc>> (function(Tv): bool) $callback,
    ): Map<Tk, Tv>;

    /**
     * Returns a `Map` containing the values of the current `Map` that meet
     * a supplied condition applied to its keys and values.
     *
     * Only keys and values that meet a certain criteria are affected by a call to
     * `filterWithKey()`, while all values are affected by a call to
     * `mapWithKey()`.
     *
     * The keys associated with the current `Map` remain unchanged in the
     * returned `Map`; the keys will be used in the filtering process only.
     *
     * @param $callback - The callback containing the condition to apply to the
     *                    current `Map` keys and values.
     *
     * @return - a `Map` containing the values after a user-specified condition
     *           is applied to the keys and values of the current `Map`.
     *
     */
    <<__Rx, __AtMostRxAsArgs, __MutableReturn, __MaybeMutable>>
    public function filterWithKey(
      <<__AtMostRxAsFunc>> (function(Tk, Tv): bool) $callback,
    ): Map<Tk, Tv>;

    /**
     * Returns a `Map` where each value is a `Pair` that combines the value
     * of the current `Map` and the provided `Traversable`.
     *
     * If the number of values of the current `Map` are not equal to the number
     * of elements in the `Traversable`, then only the combined elements up to
     * and including the final element of the one with the least number of
     * elements is included.
     *
     * The keys associated with the current `Map` remain unchanged in the
     * returned `Map`.
     *
     * @param $traversable - The `Traversable` to use to combine with the
     *                       elements of the current `Map`.
     *
     * @return - The `Map` that combines the values of the current `Map` with
     *           the provided `Traversable`.
     */
    <<__Rx, __AtMostRxAsArgs, __MutableReturn, __MaybeMutable>>
    public function zip<Tu>(
      <<__MaybeMutable, __OnlyRxIfImpl(\HH\Rx\Traversable::class)>>
      Traversable<Tu> $traversable,
    ): Map<Tk, Pair<Tv, Tu>>;

    /**
     * Returns a `Map` containing the first `n` key/values of the current `Map`.
     *
     * The returned `Map` will always be a proper subset of the current `Map`.
     *
     * `n` is 1-based. So the first element is 1, the second 2, etc.
     *
     * @param $n - The last element that will be included in the `Map`.
     *
     * @return - A `Map` that is a proper subset of this `Map` up to `n` elements.
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function take(int $n): Map<Tk, Tv>;

    /**
     * Returns a `Map` containing the keys and values of the current `Map` up to
     * but not including the first value that produces `false` when passed to the
     * specified callback.
     *
     * The returned `Map` will always be a proper subset of the current `Map`.
     *
     * @param $fn - The callback that is used to determine the stopping condition.
     *
     * @return - A `Map` that is a proper subset of the current `Map` up until
     *           the callback returns `false`.
     */
    <<__Rx, __AtMostRxAsArgs, __MutableReturn, __MaybeMutable>>
    public function takeWhile(
      <<__AtMostRxAsFunc>> (function(Tv): bool) $fn,
    ): Map<Tk, Tv>;

    /**
     * Returns a `Map` containing the values after the `n`-th element of the
     * current `Map`.
     *
     * The returned `Map` will always be a proper subset of the current `Map`.
     *
     * `n` is 1-based. So the first element is 1, the second 2, etc.
     *
     * @param $n - The last element to be skipped; the `$n+1` element will be the
     *             first one in the returned `Map`.
     *
     * @return - A `Map` that is a proper subset of the current `Map` containing
     *           values after the specified `n`-th element.
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function skip(int $n): Map<Tk, Tv>;

    /**
     * Returns a `Map` containing the values of the current `Map` starting after
     * and including the first value that produces `true` when passed to the
     * specified callback.
     *
     * The returned `Map` will always be a proper subset of this `Map`.
     *
     * @param $fn - The callback used to determine the starting element for the
     *              current `Map`.
     *
     * @return - A `Map` that is a proper subset of the current `Map` starting
     *           after the callback returns `true`.
     */
    <<__Rx, __AtMostRxAsArgs, __MutableReturn, __MaybeMutable>>
    public function skipWhile(
      <<__AtMostRxAsFunc>> (function(Tv): bool) $fn,
    ): Map<Tk, Tv>;

    /**
     * Returns a subset of the current `Map` starting from a given key location
     * up to, but not including, the element at the provided length from the
     * starting key location.
     *
     * `$start` is 0-based. `$len` is 1-based. So `slice(0, 2)` would return the
     * keys and values at key location 0 and 1.
     *
     * The returned `Map` will always be a proper subset of the current `Map`.
     *
     * @param $start - The starting key location of the current `Map` for the
     *                 returned `Map`.
     * @param $len - The length of the returned `Map`.
     *
     * @return - A `Map` that is a proper subset of the current `Map` starting at
     *           `$start` up to but not including the element `$start + $len`.
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function slice(int $start, int $len): Map<Tk, Tv>;

    /**
     * Returns a `Vector` that is the concatenation of the values of the current
     * `Map` and the values of the provided `Traversable`.
     *
     * The provided `Traversable` is concatenated to the end of the current `Map`
     * to produce the returned `Vector`.
     *
     * @param $traversable - The `Traversable` to concatenate to the current
     *                       `Map`.
     *
     * @return - The integer-indexed concatenated `Vector`.
     *
     * @guide /hack/generics/constraints
     */
    <<__Rx, __AtMostRxAsArgs, __MutableReturn, __MaybeMutable>>
    public function concat<Tu super Tv>(
      <<__MaybeMutable, __OnlyRxIfImpl(\HH\Rx\Traversable::class)>>
      Traversable<Tu> $traversable,
    ): Vector<Tu>;

    /**
     * Returns the first value in the current `Map`.
     *
     * @return - The first value in the current `Map`,  or `null` if the `Map` is
     *           empty.
     */
    <<__Rx, __MaybeMutable>>
    public function firstValue(): ?Tv;

    /**
     * Returns the first key in the current `Map`.
     *
     * @return - The first key in the current `Map`, or `null` if the `Map` is
     *           empty.
     */
    <<__Rx, __MaybeMutable>>
    public function firstKey(): ?Tk;

    /**
     * Returns the last value in the current `Map`.
     *
     * @return - The last value in the current `Map`, or `null` if the `Map` is
     *           empty.
     */
    <<__Rx, __MaybeMutable>>
    public function lastValue(): ?Tv;

    /**
     * Returns the last key in the current `Map`.
     *
     * @return - The last key in the current `Map`, or `null` if the `Map` is
     *           empty.
     */
    <<__Rx, __MaybeMutable>>
    public function lastKey(): ?Tk;

    /**
     * Checks if the current `Map` is empty.
     *
     * @return - `true` if the current `Map` is empty; `false` otherwise.
     */
    <<__Rx, __MaybeMutable>>
    public function isEmpty(): bool;

    /**
     * Provides the number of elements in the current `Map`.
     *
     * @return - The number of elements in the current `Map`.
     */
    <<__Rx, __MaybeMutable>>
    public function count(): int;

    /**
     * Returns the value at the specified key in the current `Map`.
     *
     * If the key is not present, an exception is thrown. If you don't want an
     * exception to be thrown, use `get()` instead.
     *
     * `$v = $map->at($k)` is equivalent to `$v = $map[$k]`.
     *
     * @param $k - the key from which to retrieve the value.
     *
     * @return - The value at the specified key; or an exception if the key does
     *           not exist.
     */
    <<__Rx, __MaybeMutable>>
    public function at(Tk $k): Tv;

    /**
     * Returns the value at the specified key in the current `Map`.
     *
     * If the key is not present, `null` is returned. If you would rather have an
     * exception thrown when a key is not present, then use `at()`.
     *
     * @param $k - the key from which to retrieve the value.
     *
     * @return - The value at the specified key; or `null` if the key does not
     *           exist.
     */
    <<__Rx, __MaybeMutable>>
    public function get(Tk $k): ?Tv;

    /**
     * Stores a value into the current `Map` with the specified key, overwriting
     * the previous value associated with the key.
     *
     * This method is equivalent to `Map::add()`. If the key to set does not exist,
     * it is created. This is inconsistent with, for example, `Vector::set()`
     * where if the key is not found, an exception is thrown.
     *
     * `$map->set($k,$v)` is equivalent to `$map[$k] = $v` (except that `set()`
     * returns the current `Map`).
     *
     * Future changes made to the current `Map` ARE reflected in the returned
     * `Map`, and vice-versa.
     *
     * @param $k - The key to which we will set the value.
     * @param $v - The value to set.
     *
     * @return - Returns itself.
     */
    <<__Rx, __Mutable, __ReturnsVoidToRx>>
    public function set(Tk $k, Tv $v): Map<Tk, Tv>;

    /**
     * For every element in the provided `Traversable`, stores a value into the
     * current `Map` associated with each key, overwriting the previous value
     * associated with the key.
     *
     * This method is equivalent to `Map::addAll()`. If a key to set does not
     * exist in the Map that does exist in the `Traversable`, it is created. This
     * is inconsistent with, for example, the method `Vector::setAll()` where if
     * a key is not found, an exception is thrown.
     *
     * Future changes made to the current `Map` ARE reflected in the returned
     * `Map`, and vice-versa.
     *
     * @param $k - The `Traversable` with the new values to set. If `null` is
     *             provided, no changes are made.
     *
     * @return - Returns itself.
     */
    <<__Rx, __Mutable, __AtMostRxAsArgs, __ReturnsVoidToRx>>
    public function setAll(
      <<__MaybeMutable, __OnlyRxIfImpl(\HH\Rx\KeyedTraversable::class)>>
      ?KeyedTraversable<Tk, Tv> $it,
    ): Map<Tk, Tv>;

    /**
     * Remove all the elements from the current `Map`.
     *
     * Future changes made to the current `Map` ARE reflected in the returned
     * `Map`, and vice-versa.
     *
     * @return - Returns itself.
     */
    <<__Rx, __Mutable, __ReturnsVoidToRx>>
    public function clear(): Map<Tk, Tv>;

    /**
     * Determines if the specified key is in the current `Map`.
     *
     * This function is interchangeable with `containsKey()`.
     *
     * @param $k - The key to check.
     *
     * @return - `true` if the specified key is present in the current `Map`;
     *           returns `false` otherwise.
     *
     * @guide /hack/generics/constraints
     */
    <<__Rx, __MaybeMutable>>
    public function contains(mixed $k): bool;

    /**
     * Determines if the specified key is in the current `Map`.
     *
     * This function is interchangeable with `contains()`.
     *
     * @param $k - The key to check.
     *
     * @return - `true` if the specified key is present in the current `Map`;
     *           returns `false` otherwise.
     *
     * @guide /hack/generics/constraints
     */
    <<__Rx, __MaybeMutable>>
    public function containsKey(mixed $k): bool;

    /**
     * Add a key/value pair to the end of the current `Map`.
     *
     * This method is equivalent to `Map::set()`. If the key in the  `Pair`
     * exists in the `Map`,  the value associated with it is overwritten.
     *
     * `$map->add($p)` is equivalent to both `$map[$k] = $v` and
     * `$map[] = Pair {$k, $v}` (except that `add()` returns the `Map`).
     *
     * Future changes made to the current `Map` ARE reflected in the returned
     * `Map`, and vice-versa.
     *
     * @param $p - The key/value Pair to add to the current `Map`.
     *
     * @return - Returns itself.
     */
    <<__Rx, __Mutable, __ReturnsVoidToRx>>
    public function add(Pair<Tk, Tv> $p): Map<Tk, Tv>;

    /**
     * For every element in the provided `Traversable`, add a key/value pair into
     * the current `Map`.
     *
     * This method is equivalent to `Map::setAll()`. If a key in the `Traversable`
     * exists in the `Map`, then the value associated with that key in the `Map`
     * is overwritten.
     *
     * Future changes made to the current `Map` ARE reflected in the returned
     * `Map`, and vice-versa.
     *
     * @param $k - The `Traversable` with the new key/value `Pair` to set. If
     *             `null` is provided, no changes are made.
     *
     * @return - Returns itself.
     */
    <<__Rx, __Mutable, __AtMostRxAsArgs, __ReturnsVoidToRx>>
    public function addAll(
      <<__MaybeMutable, __OnlyRxIfImpl(\HH\Rx\Traversable::class)>>
      ?Traversable<Pair<Tk, Tv>> $it,
    ): Map<Tk, Tv>;

    /**
     * Reserves enough memory to accommodate a given number of elements.
     *
     * Reserves enough memory for `sz` elements. If `sz` is less than or
     * equal to the current capacity of this `Map`, this method does nothing.
     *
     * @param $sz - The pre-determined size you want for the current `Map`.
     */
    <<__Rx, __Mutable>>
    public function reserve(int $sz): void;

    /**
     * Removes the specified key (and associated value) from the current `Map`.
     *
     * This method is interchangeable with `removeKey()`.
     *
     * Future changes made to the current `Map` ARE reflected in the returned
     * `Map`, and vice-versa.
     *
     * @param $k - The key to remove.
     *
     * @return - Returns itself.
     */
    <<__Rx, __Mutable, __ReturnsVoidToRx>>
    public function remove(Tk $k): Map<Tk, Tv>;

    /**
     * Removes the specified key (and associated value) from the current `Map`.
     *
     * This method is interchangeable with `remove()`.
     *
     * Future changes made to the current `Map` ARE reflected in the returned
     * `Map`, and vice-versa.
     *
     * @param $k - The key to remove.
     *
     * @return - Returns itself.
     */
    <<__Rx, __Mutable, __ReturnsVoidToRx>>
    public function removeKey(Tk $k): Map<Tk, Tv>;

    /**
     * Returns a new `Map` with the keys that are in the current `Map`, but not
     * in the provided `KeyedTraversable`.
     *
     * @param $traversable - The `KeyedTraversable` on which to compare the keys.
     *
     * @return - A `Map` containing the keys (and associated values) of the
     *           current `Map` that are not in the `KeyedTraversable`.
     */
    <<__Rx, __AtMostRxAsArgs, __MutableReturn, __MaybeMutable>>
    public function differenceByKey(
      <<__MaybeMutable, __OnlyRxIfImpl(\HH\Rx\KeyedTraversable::class)>>
      KeyedTraversable<Tk, Tv> $traversable,
    ): Map<Tk, Tv>;

    /**
     * Returns an iterator that points to beginning of the current `Map`.
     *
     * @return - A `KeyedIterator` that allows you to traverse the current `Map`.
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function getIterator(): \HH\Rx\KeyedIterator<Tk, Tv>;

    /**
     * Returns a `Map` containing the key/value pairs from the specified `array`.
     *
     * This function is deprecated. Use `new `Map`($arr)` instead.
     *
     * @param $arr - The `array` to convert to a `Map`.
     *
     * @return - A `Map` with the key/value pairs from the provided `array`.
     */
    <<__Deprecated('Use `new Map($arr)` instead.')>>
    public static function fromArray(darray<Tk, Tv> $arr): Map<Tk, Tv>;

    /**
     * Creates a `Map` from the given `Traversable`, or an empty `Map` if
     * `null` is passed.
     *
     * This is the static method version of the `Map::__construct()` constructor.
     *
     * @param $items - any `Traversable` object from which to create a `Map`
     *                 (e.g., `array`). If `null`, then an empty `Map` is created.
     *
     * @return - A `Map` with the key/value pairs from the `Traversable`; or an
     *           empty `Map` if the `Traversable` is `null`.
     */
    <<__Rx, __AtMostRxAsArgs, __MutableReturn>>
    public static function fromItems(
      <<__MaybeMutable, __OnlyRxIfImpl(\HH\Rx\Traversable::class)>>
      ?Traversable<Pair<Tk, Tv>> $items,
    ): Map<Tk, Tv>;

    /**
     * Returns the `string` version of the current `Map`, which is `"Map"`.
     *
     * @return - The `string` `"Map"`.
     */
    <<__Rx, __MaybeMutable>>
    public function __toString(): string;

    /**
     * Returns an `Iterable` view of the current `Map`.
     *
     * The `Iterable` returned is one that produces the key/values from the
     * current `Map`.
     *
     * @return - The `Iterable` view of the current `Map`.
     */
    <<__Rx, __MutableReturn, __MaybeMutable>>
    public function items(): \HH\Rx\Iterable<Pair<Tk, Tv>>;
    <<__Rx, __MaybeMutable>>
    /* HH_FIXME[0002] */
  public function toVArray(): varray<Tv>;
    <<__Rx, __MaybeMutable>>
    /* HH_FIXME[0001] */
  public function toDArray(): darray<Tk, Tv>;
  }

} // namespace HH

namespace {

  /**
   * @internal
   *
   * Methods and functions should take and return the KeyedIterator interface.
   */
  class MapIterator<Tk, +Tv> implements HH\Rx\KeyedIterator<Tk, Tv> {
    <<__Rx>>
    public function __construct();
    <<__Rx, __MaybeMutable>>
    public function current(): Tv;
    <<__Rx, __MaybeMutable>>
    public function key(): Tk;
    <<__Rx, __MaybeMutable>>
    public function valid(): bool;
    <<__Rx, __Mutable>>
    public function next(): void;
    <<__Rx, __Mutable>>
    public function rewind(): void;
  }

} // namespace