# Dict

{/* Generated from types/std.Rtypes by `just docs-std`. Do not edit this file. */}

A dictionary maps keys to values, typed `Dict<K, V>`. See [Dictionaries and
sets](#dictionaries-and-sets) for the rules on keys.

```
@type Dict<K, V>
```

| Function | Summary |
| --- | --- |
| [`Dict.empty`](#dictempty) | A dictionary with no entries. |
| [`Dict.with_capacity`](#dictwith_capacity) | An empty dictionary with room for `capacity` entries, so inserting that many never grows it. |
| [`Dict.single`](#dictsingle) | A dictionary with one entry. |
| [`Dict.from_list`](#dictfrom_list) | A dictionary from `(key, value)` tuples; a later tuple replaces an earlier one with the same key. |
| [`Dict.to_list`](#dictto_list) | The entries as `(key, value)` tuples, in insertion order. |
| [`Dict.len`](#dictlen) | The number of entries. |
| [`Dict.is_empty`](#dictis_empty) | Whether the dictionary has no entries. |
| [`Dict.get`](#dictget) | The value for `key`, or `:Err(:KeyNotFound)`. |
| [`Dict.contains`](#dictcontains) | Whether the dictionary has an entry for `key`. |
| [`Dict.insert`](#dictinsert) | Adds an entry, or replaces the value of an existing key in place. |
| [`Dict.remove`](#dictremove) | Removes the entry for `key`, if there is one. |
| [`Dict.update`](#dictupdate) | Sets the entry for `key` from `f`, which gets `:Ok(value)` or `:Err(:Missing)` and returns either; `:Err` removes the entry. |
| [`Dict.keys`](#dictkeys) | The keys, in insertion order. |
| [`Dict.values`](#dictvalues) | The values, in insertion order. |
| [`Dict.walk`](#dictwalk) | Folds over the entries: `f` gets the state, a key and its value. |
| [`Dict.walk_until`](#dictwalk_until) | Folds the entries until `f` returns `:Break(state)`. |
| [`Dict.map`](#dictmap) | Replaces every value with `f` of its key and value. |
| [`Dict.join_map`](#dictjoin_map) | Unions the dictionaries `f` returns for each entry; a later entry's value wins. |
| [`Dict.keep_if`](#dictkeep_if) | The entries for which `predicate` of the key and value is `TRUE`. |
| [`Dict.drop_if`](#dictdrop_if) | The entries for which `predicate` is `FALSE`. |
| [`Dict.insert_all`](#dictinsert_all) | The entries of both; where a key is in both, `second`'s value wins. |
| [`Dict.keep_shared`](#dictkeep_shared) | The entries of `first` whose key and value are both in `second`. |
| [`Dict.remove_all`](#dictremove_all) | The entries of `first` whose key is not in `second`. |
| [`Dict.reserve`](#dictreserve) | The dictionary with room for `spare` more entries. |
| [`Dict.capacity`](#dictcapacity) | How many entries the dictionary holds before its storage must grow. |
| [`Dict.release_excess_capacity`](#dictrelease_excess_capacity) | The dictionary with no room beyond its entries. |
| [`Dict.clear`](#dictclear) | An empty dictionary of the same type. |

## `Dict.empty`

### Inline

```r
Dict.empty <- function<K: key, V>() -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn() -> Dict<K, V>
Dict.empty <- function()
```

A dictionary with no entries.

```r
Dict.empty()
#> Dict.empty()
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1803)

## `Dict.with_capacity`

### Inline

```r
Dict.with_capacity <- function<K: key, V>(capacity: integer) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(capacity: integer) -> Dict<K, V>
Dict.with_capacity <- function(capacity)
```

An empty dictionary with room for `capacity` entries, so inserting that many never grows it. The
room is rounded up to a power of two.

```r
Dict.capacity(Dict.insert(Dict.with_capacity(64L), "a", 1L))
#> 64L
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1812)

## `Dict.single`

### Inline

```r
Dict.single <- function<K: key, V>(key: K, value: V) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(key: K, value: V) -> Dict<K, V>
Dict.single <- function(key, value)
```

A dictionary with one entry.

```r
Dict.single("a", 1)
#> Dict.from_list(list(("a", 1)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1820)

## `Dict.from_list`

### Inline

```r
Dict.from_list <- function<K: key, V>(pairs: list[Tuple{K, V}]) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(pairs: list[Tuple{K, V}]) -> Dict<K, V>
Dict.from_list <- function(pairs)
```

A dictionary from `(key, value)` tuples; a later tuple replaces an earlier one with the same key.

```r
Dict.from_list(list(("a", 1), ("b", 2), ("a", 3)))
#> Dict.from_list(list(("a", 3), ("b", 2)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1828)

## `Dict.to_list`

### Inline

```r
Dict.to_list <- function<K: key, V>(dict: Dict<K, V>) -> list[Tuple{K, V}]
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>) -> list[Tuple{K, V}]
Dict.to_list <- function(dict)
```

The entries as `(key, value)` tuples, in insertion order.

```r
Dict.to_list(Dict.from_list(list(("a", 1), ("b", 2))))
#> list(("a", 1), ("b", 2))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1836)

## `Dict.len`

### Inline

```r
Dict.len <- function<K: key, V>(dict: Dict<K, V>) -> integer
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>) -> integer
Dict.len <- function(dict)
```

The number of entries.

```r
Dict.len(Dict.single("a", 1))
#> 1L
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1844)

## `Dict.is_empty`

### Inline

```r
Dict.is_empty <- function<K: key, V>(dict: Dict<K, V>) -> logical
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>) -> logical
Dict.is_empty <- function(dict)
```

Whether the dictionary has no entries.

```r
Dict.is_empty(Dict.empty())
#> TRUE
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1852)

## `Dict.get`

### Inline

```r
Dict.get <- function<K: key, V>(dict: Dict<K, V>, key: K) -> Result<V, :KeyNotFound>
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>, key: K) -> Result<V, :KeyNotFound>
Dict.get <- function(dict, key)
```

The value for `key`, or `:Err(:KeyNotFound)`.

```r
Dict.get(Dict.single("a", 1), "a")
#> :Ok(1)
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1860)

## `Dict.contains`

### Inline

```r
Dict.contains <- function<K: key, V>(dict: Dict<K, V>, key: K) -> logical
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>, key: K) -> logical
Dict.contains <- function(dict, key)
```

Whether the dictionary has an entry for `key`.

```r
Dict.contains(Dict.single("a", 1), "b")
#> FALSE
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1868)

## `Dict.insert`

### Inline

```r
Dict.insert <- function<K: key, V>(dict: Dict<K, V>, key: K, value: V) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>, key: K, value: V) -> Dict<K, V>
Dict.insert <- function(dict, key, value)
```

Adds an entry, or replaces the value of an existing key in place.

```r
Dict.insert(Dict.single("a", 1), "b", 2)
#> Dict.from_list(list(("a", 1), ("b", 2)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1876)

## `Dict.remove`

### Inline

```r
Dict.remove <- function<K: key, V>(dict: Dict<K, V>, key: K) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>, key: K) -> Dict<K, V>
Dict.remove <- function(dict, key)
```

Removes the entry for `key`, if there is one.

```r
Dict.remove(Dict.from_list(list(("a", 1), ("b", 2))), "a")
#> Dict.from_list(list(("b", 2)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1884)

## `Dict.update`

### Inline

```r
Dict.update <- function<K: key, V>(dict: Dict<K, V>, key: K, f: fn(Result<V, :Missing>) -> Result<V, :Missing>) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>, key: K, f: fn(Result<V, :Missing>) -> Result<V, :Missing>) -> Dict<K, V>
Dict.update <- function(dict, key, f)
```

Sets the entry for `key` from `f`, which gets `:Ok(value)` or `:Err(:Missing)` and returns
either; `:Err` removes the entry.

```r
Dict.update(Dict.single("hits", 1L), "hits", function(r) :Ok(Result.with_default(r, 0L) + 1L))
#> Dict.from_list(list(("hits", 2L)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1893)

## `Dict.keys`

### Inline

```r
Dict.keys <- function<K: key, V>(dict: Dict<K, V>) -> list[K]
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>) -> list[K]
Dict.keys <- function(dict)
```

The keys, in insertion order.

```r
Dict.keys(Dict.from_list(list(("a", 1), ("b", 2))))
#> list("a", "b")
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1901)

## `Dict.values`

### Inline

```r
Dict.values <- function<K: key, V>(dict: Dict<K, V>) -> list[V]
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>) -> list[V]
Dict.values <- function(dict)
```

The values, in insertion order.

```r
Dict.values(Dict.from_list(list(("a", 1), ("b", 2))))
#> list(1, 2)
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1909)

## `Dict.walk`

### Inline

```r
Dict.walk <- function<K: key, V, S>(dict: Dict<K, V>, state: S, f: fn(S, K, V) -> S) -> S
```

### Comments

```r
#: <K: key, V, S> fn(dict: Dict<K, V>, state: S, f: fn(S, K, V) -> S) -> S
Dict.walk <- function(dict, state, f)
```

Folds over the entries: `f` gets the state, a key and its value.

```r
Dict.walk(Dict.from_list(list(("a", 1), ("b", 2))), 0, function(total, k, v) total + v)
#> 3
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1917)

## `Dict.walk_until`

### Inline

```r
Dict.walk_until <- function<K: key, V, S>(dict: Dict<K, V>, state: S, f: fn(S, K, V) -> :Continue(S) | :Break(S)) -> S
```

### Comments

```r
#: <K: key, V, S> fn(dict: Dict<K, V>, state: S, f: fn(S, K, V) -> :Continue(S) | :Break(S)) -> S
Dict.walk_until <- function(dict, state, f)
```

Folds the entries until `f` returns `:Break(state)`.

```r
Dict.walk_until(Dict.from_list(list(("a", 1L), ("b", 5L), ("c", 2L))), 0L, function(total, k, v) if (v > 4L) :Break(total) else :Continue(total + v))
#> 1L
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1925)

## `Dict.map`

### Inline

```r
Dict.map <- function<K: key, A, B>(dict: Dict<K, A>, f: fn(K, A) -> B) -> Dict<K, B>
```

### Comments

```r
#: <K: key, A, B> fn(dict: Dict<K, A>, f: fn(K, A) -> B) -> Dict<K, B>
Dict.map <- function(dict, f)
```

Replaces every value with `f` of its key and value.

```r
Dict.map(Dict.from_list(list(("a", 1), ("b", 2))), function(k, v) v * 10)
#> Dict.from_list(list(("a", 10), ("b", 20)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1933)

## `Dict.join_map`

### Inline

```r
Dict.join_map <- function<K: key, V, X: key, Y>(dict: Dict<K, V>, f: fn(K, V) -> Dict<X, Y>) -> Dict<X, Y>
```

### Comments

```r
#: <K: key, V, X: key, Y> fn(dict: Dict<K, V>, f: fn(K, V) -> Dict<X, Y>) -> Dict<X, Y>
Dict.join_map <- function(dict, f)
```

Unions the dictionaries `f` returns for each entry; a later entry's value wins.

```r
Dict.join_map(Dict.from_list(list(("a", 1L), ("b", 2L))), function(k, v) Dict.single(v, k))
#> Dict.from_list(list((1L, "a"), (2L, "b")))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1941)

## `Dict.keep_if`

### Inline

```r
Dict.keep_if <- function<K: key, V>(dict: Dict<K, V>, predicate: fn(K, V) -> logical) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>, predicate: fn(K, V) -> logical) -> Dict<K, V>
Dict.keep_if <- function(dict, predicate)
```

The entries for which `predicate` of the key and value is `TRUE`.

```r
Dict.keep_if(Dict.from_list(list(("a", 1), ("b", 2))), function(k, v) v > 1)
#> Dict.from_list(list(("b", 2)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1949)

## `Dict.drop_if`

### Inline

```r
Dict.drop_if <- function<K: key, V>(dict: Dict<K, V>, predicate: fn(K, V) -> logical) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>, predicate: fn(K, V) -> logical) -> Dict<K, V>
Dict.drop_if <- function(dict, predicate)
```

The entries for which `predicate` is `FALSE`.

```r
Dict.drop_if(Dict.from_list(list(("a", 1), ("b", 2))), function(k, v) v > 1)
#> Dict.from_list(list(("a", 1)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1957)

## `Dict.insert_all`

### Inline

```r
Dict.insert_all <- function<K: key, V>(first: Dict<K, V>, second: Dict<K, V>) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(first: Dict<K, V>, second: Dict<K, V>) -> Dict<K, V>
Dict.insert_all <- function(first, second)
```

The entries of both; where a key is in both, `second`'s value wins.

```r
Dict.insert_all(Dict.single("a", 1), Dict.from_list(list(("a", 5), ("b", 2))))
#> Dict.from_list(list(("a", 5), ("b", 2)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1965)

## `Dict.keep_shared`

### Inline

```r
Dict.keep_shared <- function<K: key, V>(first: Dict<K, V>, second: Dict<K, V>) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(first: Dict<K, V>, second: Dict<K, V>) -> Dict<K, V>
Dict.keep_shared <- function(first, second)
```

The entries of `first` whose key and value are both in `second`.

```r
Dict.keep_shared(Dict.from_list(list(("a", 1), ("b", 2))), Dict.from_list(list(("a", 1), ("b", 0))))
#> Dict.from_list(list(("a", 1)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1973)

## `Dict.remove_all`

### Inline

```r
Dict.remove_all <- function<K: key, V>(first: Dict<K, V>, second: Dict<K, V>) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(first: Dict<K, V>, second: Dict<K, V>) -> Dict<K, V>
Dict.remove_all <- function(first, second)
```

The entries of `first` whose key is not in `second`.

```r
Dict.remove_all(Dict.from_list(list(("a", 1), ("b", 2))), Dict.single("a", 0))
#> Dict.from_list(list(("b", 2)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1981)

## `Dict.reserve`

### Inline

```r
Dict.reserve <- function<K: key, V>(dict: Dict<K, V>, spare: integer) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>, spare: integer) -> Dict<K, V>
Dict.reserve <- function(dict, spare)
```

The dictionary with room for `spare` more entries.

```r
Dict.reserve(Dict.single("a", 1L), 1000L)
#> Dict.from_list(list(("a", 1L)))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1989)

## `Dict.capacity`

### Inline

```r
Dict.capacity <- function<K: key, V>(dict: Dict<K, V>) -> integer
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>) -> integer
Dict.capacity <- function(dict)
```

How many entries the dictionary holds before its storage must grow.

```r
Dict.capacity(Dict.reserve(Dict.single("a", 1L), 9L))
#> 10L
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1997)

## `Dict.release_excess_capacity`

### Inline

```r
Dict.release_excess_capacity <- function<K: key, V>(dict: Dict<K, V>) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>) -> Dict<K, V>
Dict.release_excess_capacity <- function(dict)
```

The dictionary with no room beyond its entries. An empty dictionary keeps its smallest index,
which has room for 4.

```r
Dict.capacity(Dict.release_excess_capacity(Dict.reserve(Dict.single("a", 1L), 9L)))
#> 1L
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L2006)

## `Dict.clear`

### Inline

```r
Dict.clear <- function<K: key, V>(dict: Dict<K, V>) -> Dict<K, V>
```

### Comments

```r
#: <K: key, V> fn(dict: Dict<K, V>) -> Dict<K, V>
Dict.clear <- function(dict)
```

An empty dictionary of the same type.

```r
Dict.clear(Dict.single("a", 1L))
#> Dict.empty()
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L2014)