Volume 15: Collections and Iteration

1. Introduction

This volume defines collections, iteration, iterables, iterators, and for-in loops in the Rethon programming language. It describes the collection model, list types, dictionary types, set types, tuple types, range types, iterable protocol, iterator protocol, for-in statements, iteration semantics, collection literals, generic collections, pattern matching and collections, collection equality, collection hashing, collection visibility and mutability, future extensions, and summary.

This document is part of the official Rethon Language Specification. It is normative rather than descriptive. Implementations, tooling, documentation systems, and other source-processing tools shall treat the rules in this volume as authoritative.

This volume does not define backend iteration machinery, memory layout, hash-table internals, or runtime-specific collection implementation details. It defines the source-level and language-level behavior of collections and iteration as programmer-visible abstractions.

Rethon is Python-inspired in language philosophy and Python-first in surface syntax where practical.

Rethon uses static typing, generics, protocols, value-oriented design, pattern matching, explicit typing where practical, and readable source-level control flow.

Collections shall be generic, statically typed, and usable through explicit protocol contracts.

2. Collection Model

Rethon shall support a small set of first-class collection types at the source level.

The initial collection model shall include lists, dictionaries, sets, tuples, and ranges.

Collections shall be statically typed and shall integrate with the type system, generics, and protocol model.

Collections shall remain readable and Python-like in surface syntax.

Example:

names: list<str> = ["Ada", "Lin", "Sam"]
counts: dict<str, int> = {"apples": 3, "pears": 2}
unique_ids: set<int> = {1, 2, 3}
location: tuple<float, float> = (10.0, 20.0)
steps: range = range(0, 10)

Collection types shall preserve the language's static typing and value-oriented design goals.

A collection type shall be explicit in source code when the type cannot be safely inferred.

3. List Types

List types shall be supported.

A list type shall represent an ordered, indexable collection of values.

A list type shall be generic over the type of its elements.

Example:

let names: list<str> = ["Ada", "Lin", "Sam"]

List values shall preserve ordering.

List values shall be mutable collections unless a later language rule explicitly defines a more restricted list form.

List element types shall be statically typed.

A list shall permit repeated values.

A list shall be appropriate for ordered sequences whose size and contents may change over time.

4. Dictionary Types

Dictionary types shall be supported.

A dictionary type shall represent a mapping from keys to values.

A dictionary type shall be generic over the key type and the value type.

Example:

age_by_name: dict<str, int> = {"Ada": 36, "Lin": 29}

Dictionary keys shall be compared according to the language's equality and hashing rules.

Dictionary keys shall be statically typed.

Dictionary values shall be statically typed.

A dictionary shall be appropriate for keyed lookup, association tables, and other mapping-based data structures.

A dictionary shall preserve the language's readability and static typing goals.

5. Set Types

Set types shall be supported.

A set type shall represent an unordered collection of distinct values.

A set type shall be generic over the type of its elements.

Example:

unique_tags: set<str> = {"fast", "typed", "safe"}

Set values shall not contain duplicate elements according to the language's equality and hashing rules.

Set elements shall be statically typed.

A set shall be appropriate for membership testing, deduplication, and mathematical set-like use cases.

A set shall not imply ordering unless a later language rule explicitly defines an ordered set form.

6. Tuple Types

Tuple types shall be supported.

A tuple type shall represent a fixed-arity ordered collection of values.

A tuple type shall be generic over the types of its elements.

Example:

point: tuple<int, int> = (1, 2)

Tuple values shall preserve element order and arity.

Tuple values shall be suitable for small fixed groupings of values, multi-value returns, and structured data where a dedicated struct type is unnecessary.

Tuple element types shall be statically typed.

Tuple arity shall be part of the tuple type.

7. Range Types

Range types shall be supported.

A range type shall represent a finite or bounded integer progression suitable for iteration.

Example:

steps: range = range(0, 10)

A range shall be iterable.

A range shall be suitable for loop counters, index traversal, and other regular numeric iteration tasks.

A range shall remain a source-level collection form rather than a runtime implementation detail.

The exact numeric bounds and stepping semantics shall be defined by the language's source-level rules and supporting runtime behavior, but the language shall not expose backend implementation details in this volume.

8. Iterable Protocol

An iterable protocol shall be supported.

An iterable shall describe a value that can produce an iterator.

Example:

protocol Iterable<Item>:
    def iterator(self) -> Iterator<Item>

An iterable protocol shall be a behavior contract, not storage.

A type shall be iterable when it explicitly conforms to the iterable protocol or when a later language rule defines another explicit iterable path.

The iterable protocol shall support generic collection APIs and for-in loops.

9. Iterator Protocol

An iterator protocol shall be supported.

An iterator shall describe a stateful producer of successive values.

Example:

protocol Iterator<Item>:
    def next(self) -> Option<Item>

An iterator shall produce items one at a time in iteration order.

An iterator shall be statically typed through its item type.

An iterator shall be compatible with the iterable protocol and with for-in statements.

An iterator shall represent iteration state explicitly rather than relying on hidden source-level magic.

10. For-In Statements

for-in statements shall be supported.

Example:

for name in names:
    print(name)

A for-in statement shall iterate over the values produced by an iterable value.

A for-in statement shall bind each successive item to the loop target in order.

A for-in statement shall use Python-like surface syntax.

A for-in statement shall be allowed wherever a statement is permitted by the language's block and scope rules.

A loop target may be a single binding or a destructuring pattern where the language rules permit it.

Example:

for key, value in entries:
    print(key, value)

11. Iteration Semantics

Iteration shall proceed in source order as defined by the iterable or iterator.

A for-in loop shall obtain iteration values from the iterable source and bind each item in turn.

Iteration shall remain explicit at the source level.

A loop body shall execute once per produced item until the iterator is exhausted or control flow exits the loop.

An empty iterable shall produce zero loop iterations.

Iteration semantics shall remain compatible with break, continue, and return as defined elsewhere in the specification.

The specification does not require iteration to expose internal storage layout or allocation strategy.

12. Collection Literals

Collection literals shall be supported.

Example:

let names: list<str> = ["Ada", "Lin", "Sam"]
let age_by_name: dict<str, int> = {"Ada": 36, "Lin": 29}
let unique_ids: set<int> = {1, 2, 3}
let point: tuple<int, int> = (1, 2)

Collection literals shall be statically typed.

Collection literals shall be compatible with type inference when the target type is known unambiguously.

A list literal shall use square brackets.

A dictionary literal shall use brace syntax with key-value pairs.

A set literal shall use brace syntax when the type context makes the set form unambiguous.

A tuple literal shall use parenthesized comma-separated values.

13. Generic Collections

Collection types shall be generic.

Example:

let values: list<int> = [1, 2, 3]
let mapping: dict<str, int> = {"a": 1, "b": 2}
let flags: set<bool> = {True, False}
let pair: tuple<str, int> = ("count", 3)

Generic collection types shall remain statically typed.

Generic collection APIs shall preserve element type information where possible.

Protocol constraints may be used where a collection API requires behavior such as hashing, equality, or iteration.

Generic collection types shall integrate with the language's existing generic programming model.

14. Pattern Matching and Collections

Pattern matching shall remain compatible with tuple values and with collection-oriented control flow.

Example:

match point:
    case (0, 0):
        print("origin")
    case (x, y):
        print(x, y)

Tuple values shall be natural candidates for pattern matching because they are fixed-arity ordered values.

Pattern matching on tuples shall remain statically typed and shall respect the tuple's arity and element types.

List, dictionary, and set patterns may be introduced later if the language decides that their source-level forms are sufficiently clear and useful.

Until such later refinement, tuple values shall be the primary collection form targeted by direct destructuring patterns.

15. Collection Equality

Collection equality shall be defined in a value-oriented way.

Two list values shall compare equal when they have the same length and pairwise equal elements in order.

Two dictionary values shall compare equal when they have the same set of key-value associations, according to the language's equality rules for keys and values.

Two set values shall compare equal when they contain the same elements, regardless of order.

Two tuple values shall compare equal when they have the same arity and pairwise equal elements.

Two range values shall compare equal when they denote the same iteration sequence according to the language's range rules.

Collection equality shall be statically reasoned about where possible and shall remain compatible with the language's value semantics.

16. Collection Hashing

Collection hashing shall follow the language's hashability rules.

A collection type shall be hashable only when the language rules permit stable hashing for that collection form.

Tuple values may be hashable when all of their element types are hashable and the tuple is otherwise eligible for hashing.

Set and dictionary values shall not be hashable as ordinary mutable collection values.

List values shall not be hashable as ordinary mutable collection values.

Range values may be hashable if the language later defines a stable and useful hash form for them, but the specification does not require such a form in this volume.

Hashability shall remain aligned with equality and with the language's memory-safety and value-semantics goals.

17. Collection Visibility and Mutability

Collection types shall obey the language's visibility rules when declared in public or private APIs.

Collection mutability shall be explicit in source-level design.

A mutable collection value may change its contents when the language and its libraries permit such operations.

A collection binding may be immutable even when the collection type itself is mutable.

Example:

let names: list<str> = ["Ada", "Lin"]

The binding names is immutable, but the collection type may still expose mutable operations unless the collection API or declaration says otherwise.

The collection model shall distinguish between mutable bindings and mutable contents.

Public collection APIs shall make mutability visible enough to be understandable at the declaration site.

18. Future Extensions

This volume defines the current direction for collections and iteration in Rethon, but future specification work may refine the model in carefully controlled ways.

Possible future extensions include:

• sequence-specific collection views
• immutable collection variants
• ordered set forms
• more specialized dictionary and map forms
• richer iterator adapters
• generator-based iteration forms if justified later
• additional collection pattern forms
• more precise collection literal disambiguation rules

Any future extension shall preserve the current direction:

• collections remain generic and statically typed
• Python-first collection surface syntax remains preferred where practical
• for-in remains the core iteration form
• iteration remains protocol-based
• tuple values remain natural pattern-matching targets
• collection equality and hashability remain value-oriented and explicit
• mutability remains visible in source-level API design

19. Summary

Rethon shall support list, dictionary, set, tuple, and range types as the initial collection family.

Collections shall be generic and statically typed.

Iteration shall be protocol-based through iterable and iterator behavior contracts.

for-in statements shall be the core iteration construct.

Collection literals shall be supported.

Tuple values shall be the primary collection form for direct pattern matching.

Collection equality shall follow value-oriented rules, and hashability shall remain explicit and constrained by the language's type system.

Collection mutability shall remain visible at the API and binding level.

Rethon's collection and iteration model shall therefore remain Python-first, statically typed, and readable while preserving the language's protocol-oriented and value-oriented design.