Collections and comprehensions

An array literal accepts expressions and ...expression entries. A set literal contains expressions, and a map literal contains key: value entries.

A comprehension starts with for pattern in (source). Additional clauses use for pattern in (source) or if (condition). The => token introduces the body. A map body has the form key: value.

An array literal forms Array<T> from its element types.

A set literal forms Set<T> from its element types.

A map literal forms Map<K, V> from its key and value types.

Empty collection context

Empty collection context

Spreading a concrete Array<T> contributes elements of type T to the containing array literal.

An array spread whose concrete, non-union operand type is not Array<T> produces TPZ5001.

Array construction appends ordinary values and inserts each spread operand’s elements at the spread position.

Key-capability checking applies to set elements and map keys in literals and comprehensions, independently of map values.

A function, Map, Set, Range, or ByteBuffer used as a set element or map key produces TPZ5007. A compound key containing one of these types also produces TPZ5007.

Map keys and Set elements follow value semantics at insertion. Scalars include integer and floating values, strings, booleans, unit/null, Bytes, Path, URL, Date, BigInt, and Decimal. Option/Result payloads, arrays, records, enum payloads, and newtype contents must recursively be keyable. Map, Set, Range, ByteBuffer, functions, templates, File, JSONValue, Regex, Match, TOMLValue, and RoundingMode are rejected as keys. Imported namespaces and host-provided opaque values are also not keys. Structural guards bound recursive key checks. A generic type parameter passing the static gate is not evidence that every substitution is keyable; the concrete runtime value must still pass this domain check.

Binding annotations, expected call parameters, declared returns, block tails, parentheses, and expected function result types can supply a collection expectation. Empty literals follow empty collection context. A collection expectation does not select one arm from a union. Contextual literal typing does not change collection variance or general assignability.

A matching Array<E>, Set<E>, or Map<K, V> expectation supplies the component types for each emitted element, key, and value. Nonempty literals and comprehension bodies receive those component expectations, including through declared or expected callable results. After successful component checking, a comprehension retains the expected type arguments in its result without further widening. Comprehension iterator sources keep their own inferred types, and filters require bool. A rigid type parameter remains rigid. An incompatible concrete component must still be rejected. Callable result inference retains the actual body constraints for its enclosing comparison. Array spread checks its contributed element type. Collection variance, assignability, and key eligibility are unchanged.

Completing an empty collection from context must preserve the constraints of its concrete siblings. A nested string array cannot satisfy an int-array expectation merely because another map value is empty. SELF currently has a whole-type refinement path that can erase this mismatch; retain the intended rejection while that implementation limitation is reviewed.

Callback methods such as values.map(f) and values.filter(p) apply existing function values and chain their transformations. A comprehension states source bindings, filters, and emitted values together. It constructs an array, set, or map and can combine several sources.

Array map and filter evaluate their receiver and callback expression once in ordinary call order. Each method then makes a complete eager pass in element order. It calls its function once per element. A filter retains successful elements in that order. Each method finishes before the next method in a chain begins. Thus values.filter(p).map(f) finishes every call to p before its first call to f.

A comprehension eagerly builds its result. Its first source evaluates once. Each later source evaluates again for each earlier binding combination that reaches it. Clauses run in written order. Each filter decides whether later clauses and the body run for the current bindings. The body runs before traversal advances to the next reached combination.

For the same array and fixed pure functions that complete, values.map(f) and [for value in (values) => f(value)] produce the same ordered values. A pure function has the same result for the same arguments and has no observable effects. values.filter(p).map(f) and [for value in (values) if (p(value)) => f(value)] also produce the same ordered values. The second comprehension calls f immediately after a successful p for each element. Effects and failures retain these evaluation boundaries.

Each later comprehension clause executes inside the preceding clauses.

A comprehension if filter runs the remaining clauses and body when its condition is true and skips them when it is false.

Each successful comprehension body evaluation contributes one element or one map key/value pair.

For a concrete Array<T>, Set<T>, or Range<T> source, a comprehension checks its pattern against the source element type T.

A concrete non-iterable source in a comprehension produces TPZ5001.

A comprehension if condition must have type bool. A non-boolean condition produces TPZ5001.

Without a matching array expectation, an array comprehension independently infers and widens its body type T, producing Array<T>. With a matching expectation, component checking and the result type follow collection context propagation.

Without a matching set expectation, a set comprehension independently infers and widens its body type T, producing Set<T>. With a matching expectation, component checking and the result type follow collection context propagation.

Without a matching map expectation, a map comprehension independently infers and widens its key type K and value type V, producing Map<K, V>. With a matching expectation, component checking and the result type follow collection context propagation.

Literal elements and spread sources evaluate in source order. Each map key evaluates before its value. A comprehension reevaluates each later iterator source for every earlier binding combination that reaches it; an if filter controls only the following clauses and body. Map literals and comprehensions evaluate all pairs before the constructor checks for duplicate keys. A duplicate does not erase effects already performed by later pairs.

If an element, iterator source, filter, key, or value faults or propagates an early result, later expressions are not evaluated and no collection result is produced on that path. Effects already performed remain observable. This production failure is distinct from duplicate-map validation, which starts only after all pairs have been accumulated; ordinary faults follow the fault cleanup rule.

Each for source is resolved before that clause introduces its fresh immutable pattern bindings. Later clauses and the body see earlier bindings, and a later for clause may shadow an earlier name. Each source and filter uses the required outer parentheses and ordinary expression grammar inside them. The comprehension body arrow follows the complete parenthesized operand.

A comprehension may use a refutable pattern. Each reached element must match. The first mismatch raises runtime TPZ5001 and stops construction. Use an explicit filter or match expression to skip elements.

One pattern introduces one scope and must not bind the same name twice. This differs from valid shadowing across separate for clauses. SELF currently misses the same-scope duplicate guard on plain list patterns; the intended TPZ5008 rejection is retained as an implementation limitation.

Set literals and comprehensions preserve the order of first occurrence and collapse duplicate elements.

Map keys, values, and entries are observed in insertion order. Traversing those views with for preserves that order. Map display uses the same order. Inserting a new key appends it. Inserting an existing key replaces its value without moving the key. Removing a key preserves the relative order of surviving entries.

Set traversal and display follow insertion order. Adding an existing element keeps its position. Removing an element preserves the relative order of surviving elements. Set construction follows first occurrence order. Map and Set equality remains independent of this observation order.

Repeating a string or integer literal key in a map literal produces TPZ5602.

When computed keys collide during map literal or comprehension construction, execution fails with TPZ4601 without replacing the earlier value.

A computed duplicate key faults at the span of the complete map literal, whose start is the map keyword. The fault location is not the second key expression. The source-backed expectation for this fixture is example.tpz:2:14; the public CLI emission is tracked as an implementation limitation.

Key insertion follows value semantics. Canonical key equality compares the stored value family and then its contents recursively. Arrays compare elementwise; records compare field names and values; nominal records, enums, and newtypes retain declaration identity. Floating signed zeros compare equal, while NaN does not equal any key, including itself. Integer and floating keys have distinct tags. Equivalent constant spellings do not define different language values merely because static duplicate detection recognizes only some forms.

A repeated constant boolean key is a duplicate just as a repeated constant string or integer key is. SELF currently parses booleans as expression/boolean but its constant-key checker tests expression/bool. The intended TPZ5602 rejection is retained as a product test, and the mismatched syntax kind is an implementation limitation.