Choose a collection by the question you ask of the data. Array<T> preserves
positions, Map<K, V> associates unique keys with values, and Set<T> keeps
unique elements. Their methods preserve these jobs instead of inheriting
whatever a host container happens to do.
Choose the operation by task
| Task | Prefer | Result and risk |
|---|---|---|
| Read an array position that may be absent | items.get(index) | Option<T>; never faults for the missing position |
| Require an array position as a program invariant | items[index] | T; faults when the index is invalid |
| Find a map key that may be absent | values.get(key) | Option<V> |
| Supply a default for a missing map key | values.getOr(key, default) | V |
| Ask whether a set contains a value | values.contains(value) | bool |
| Inspect map order without sharing later mutation | keys, values, or entries | A copied insertion-order snapshot |
| Produce a transformed collection | map, filter, sorted, set algebra | A new collection |
| Change the existing collection | A documented mutator on let mut | In-place mutation |
Use Array, Map, and Set together
let tasks = ["draft", "check", "ship"]
let selected = tasks.get(1)
let mut scores: Map<string, int> = Map.new()
scores.insert("ada", 10)
scores.insert("lin", 12)
let mut labels = Set.of("docs")
labels.add("tests")
print("{selected}:{scores.get("lin")}:{scores.keys}:{labels.toArray()}")Some(check):Some(12):[ada, lin]:[docs, tests]The two lookups return Some because absence is an ordinary possibility.
scores.keys and labels.toArray() preserve insertion order. Mutating
scores or labels later cannot change an already produced snapshot.
Safe reads, mutations, and faults
Array get, indexOf, pop, and removeAt return Option. pop and
removeAt also mutate, so their receiver root must be let mut. slice
clamps its half-open range and returns a new array. By contrast, direct
indexing and an invalid insert position are contract violations and fault.
Map get and remove return Option; containsKey returns bool.
insert, clear, and update mutate. mapValues and filter return new
maps while preserving the surviving key order.
Set contains and remove return bool. add, remove, and clear mutate.
union, intersection, and difference return new sets in their documented
order.
No core Array, Map, or Set operation returns Result. Recoverable external
failure belongs to the parser, decoder, file, or other effect that produced
the value. Handle or propagate that Result before applying the collection
operation.
Common correction: x in map is not key membership. Use
map.containsKey(x) or x in map.keys. Strings are not arrays and have no
.length; use text.scalars().length when scalar count is the task.
Exact boundaries
- Map keys and Set elements must be recursively keyable; invalid types are rejected statically.
- Mutating through an immutable binding is a static diagnostic.
- Updating an existing map value keeps its position; removing and reinserting moves it to the end.
- Map and Set do not gain general equality from their methods.
- Callback order follows the collection's specified iteration order.
Continue with Collections & Comprehensions, Null, Option, Result & Faults, or Standard Library Overview.