map
===============================================================================

%% A `map` is a collection of key-value pairs, where each key is unique and maps to a corresponding value. Maps are useful for storing and retrieving data based on keys.


1. Syntax
-------------------------------------------------------------------------------

You can define maps using curly braces `{}` with a colon `:` to separate keys from values.

```
{"a": 1}                 -- A single key-value pair
{"a": 10, "b": 20}       -- Multiple key-value pairs
{"a": {"b": 2}}          -- Nested maps
{
  "a": 10
  "b": 20
  "c": 30
}                        -- Multi-line format
```

Evaluates to:

```mech
{"a": 1}                 -- A single key-value pair
{"a": 10, "b": 20}       -- Multiple key-value pairs
{"a": {"b": 2}}          -- Nested maps
{
  "a": 10
  "b": 20
  "c": 30
}                        -- Multi-line format
```

2. Kind
-------------------------------------------------------------------------------

The kind of a map describes the type of its keys and values:

```mech:disabled
<{K:V}>
```

Where `K` is the kind of the keys, and `V` is the kind of the values. For example:

```mech:disabled
<{string:u8}>                 -- A map from strings to unsigned 8-bit integers
<{string:{string:u8}}>       -- A nested map
<{u8:f64}>                   -- A map from unsigned 8-bit integers to 64-bit floats, can only hold 256 keys
```

3. Construction
-------------------------------------------------------------------------------

Maps can be constructed using map literals.


(3.1) Map Literals

```mech
m := {"a": 10, "b": 20}
```

4. Accessing Elements
-------------------------------------------------------------------------------

Elements in a map are accessed using square brackets `[]` with the key.

```mech:ex 4.1
m := {"a": 10, "b": 20}
m{"a"}     -- Returns 10
```

If the key does not exist, the result is `none`.

For nested maps, use multiple brackets:

```mech:ex 4.2
m := {"a": {"b": 2}}
m{"a"}{"b"}   -- Returns 2
```

5. Assigning Elements
-------------------------------------------------------------------------------

Maps can be modified if they are declared mutable with `~`.

```mech:ex 5.1
~m := {"a": 10}
m{"a"} = 42     -- Updates key "a"
m{"b"} = 17     -- Adds key "b"
m
```