This guide focuses on maps: creation, reading/writing by key, checking key presence, iterating keys/values, nesting, and common gotchas. It complements the quick overview in types.md with a deeper, example‑driven treatment.
## What is a map?
- Associative container of key → value pairs.
- Keys are typically strings; values can be any type (numbers, strings, arrays, maps, …).
- Mutable: assigning with m["k"] = v updates the map in place.
- Accessing a missing key yields nil (not an error). Use guards or has(m, key).
- Maps are not ordered; rely on keys(m) if you need a concrete list of keys.
Maps are not inherently ordered. To iterate, first obtain an array of keys or values.
```
user = { "name": "Ada", "age": 38 }
// iterate known keys (explicit order you choose)
order = ["name", "age"]
for i = 0; i < len(order); i = i + 1 {
k = order[i]
print(k + " = " + to_string(user[k]))
}
// discover keys from the map (order may depend on implementation)
ks = keys(user) // -> ["name", "age"] (example)
for i = 0; i < len(ks); i = i + 1 {
k = ks[i]
print(k + ": " + to_string(user[k]))
}
// values only
vs = values(user) // -> ["Ada", 38]
for i = 0; i < len(vs); i = i + 1 { print(to_string(vs[i])) }
```
Tip:
- If you need deterministic output, either define the order array explicitly or sort the result of keys(user) using your available utilities before looping.
## Copying vs. referencing
Maps are reference types. Assigning copies the reference, not the contents:
```
orig = { "a": 1 }
alias = orig
alias["a"] = 9
print(orig["a"]) // 9
// To make a shallow copy, rebuild from keys/values
src = { "x": 1, "y": 2 }
dst = {}
ks = keys(src)
for i = 0; i < len(ks); i = i + 1 { k = ks[i]; dst[k] = src[k] }
dst["x"] = 7
print(src["x"]) // 1
print(dst["x"]) // 7
```
Shallow copies duplicate only the top‑level mapping; nested arrays/maps inside are still shared unless you clone them manually.
## Equality
```
print({"a":1,"b":2} == {"b":2,"a":1}) // true
print({"a":1} == {"a":2}) // false
```
Map equality compares sets of keys and their corresponding values for equality (order does not matter).
## Common utilities
Depending on your build/stdlib configuration, these helpers are commonly available:
- has(m, key): 1 if present, 0 otherwise
- keys(m): array of keys
- values(m): array of values (parallel to keys(m) order)
- len(a) works on arrays; for maps, prefer keys(m) then len(keys(m)) if you need a count
