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
```