# 22. Collections et itération ## 22.1 `Array` — V1 REQUIS — FIGÉ EN PRINCIPE `Array` est une séquence contiguë dont la longueur est déterminée au runtime lors de la construction et reste fixe ensuite. Il n'expose pas d'opération structurelle de redimensionnement. Les éléments suivent exactement la sémantique normale de `T` : ```text T primitif -> valeur by-value T struct -> valeur by-value T class -> référence de classe ``` Copier un `Array` crée une collection indépendante. Les éléments eux-mêmes sont copiés selon la sémantique normale de `T`. Pour `Array`, deux arrays copiés peuvent donc contenir des références vers les mêmes objets `User`, tout en restant indépendants quant au remplacement de leurs cases. ### 22.1.1 Initialisation complète Un `Array` safe doit être entièrement initialisé avant de devenir observable. Il n'existe aucune initialisation implicite en zéro, `null`, `None` ou valeur indéfinie. ```text Array values = [1, 2, 3]; Array empty = []; ``` Le littéral `[...]` est contextualisé par le type attendu ; il ne reçoit pas automatiquement un type autonome hors contexte suffisant. Les expressions d'un littéral d'array sont évaluées exactement une fois, de gauche à droite. En cas d'échec pendant la construction, aucun array partiellement initialisé ne devient observable. ### 22.1.2 `filled` ```text Array::filled(uint64 length, T value) ``` `value` est évaluée une seule fois, puis répétée selon la sémantique normale de copie de `T`. ```text User firstUser = ...; User otherUser = ...; Array users = Array::filled(3, firstUser); users[1] = otherUser; // OK si l'accès n'est pas const ``` Initialement, les trois cases contiennent la même référence `firstUser`. Chaque case reste cependant un emplacement indépendant et peut recevoir ultérieurement une autre référence. `filled()` ne clone jamais implicitement un objet référencé. ### 22.1.3 `empty` et `generate` ```text Array::empty() ``` construit un array de longueur zéro. Une opération `generate` est retenue conceptuellement pour construire une valeur distincte par index. Sa syntaxe exacte sera figée avec les callables/lambdas. La factory devra être appelée exactement une fois par index, dans l'ordre croissant, sans parallélisation implicite. Le safe code ne peut pas obtenir un `Array` observable partiellement/non initialisé. Le compilateur/runtime reste libre d'utiliser de la mémoire non initialisée en interne tant qu'elle n'est jamais observable. ## 22.2 `StaticArray` — V1 REQUIS — FIGÉ `StaticArray` est une séquence contiguë dont la longueur `N` est connue à la compilation et reste fixe. ```text StaticArray values = [10, 20, 30]; StaticArray empty = []; ``` Le nombre d'éléments du littéral doit correspondre exactement à `N`. Une initialisation répétée utilise : ```text StaticArray::filled(T value) ``` avec la même sémantique de copie que `Array::filled`. `StaticArray` n'autorise pas davantage qu'`Array` l'observation d'éléments non initialisés. ## 22.3 `Slice` — V1 REQUIS — FIGÉ EN PRINCIPE `Slice` est une vue contiguë, de longueur fixe, sur une portion d'un stockage existant. Une slice ne réalise aucune copie sémantique des éléments. ```text Array values = ...; Slice part = values::slice(10..<20); part[0] = 42; // modifie values[10] ``` Une slice : ```text reste attachée à la portion qu'elle désigne conserve une longueur fixe n'est pas redimensionnable n'est pas déplaçable vers une autre portion peut modifier les éléments uniquement si l'accès source l'autorise ne peut jamais augmenter les droits de mutabilité de la source ``` La constness se propage : ```text const Array users = ...; const Slice part = users::slice(0..<4); part[0] = otherUser; // ERROR part[0]::setName("Alice"); // ERROR part[0]::getName(); // OK ``` Le backing storage nécessaire à une slice reste vivant aussi longtemps que nécessaire. Cette garantie ne requiert aucune syntaxe de lifetime utilisateur. Une slice vide est une valeur valide. Les indices d'une sous-slice sont relatifs à la slice source. `Slice` garantit la contiguïté. Une éventuelle vue non contiguë constituerait un autre concept et n'est pas réservée sans besoin réel. ## 22.4 Interfaces de collections — V1 REQUIS — FIGÉ EN PRINCIPE Les interfaces décrivent des capacités réellement garanties. Les classes/structs génériques fournissent le stockage et l'implémentation. Saselang ne retient pas le modèle d'opérations optionnelles présentes dans une interface mais susceptibles d'échouer ensuite comme « unsupported ». Hiérarchie principale : ```text Iterable ↓ Collection ↓ List ↓ SettableList ↓ ResizableList ``` `Set` et `Map` forment des branches sémantiques distinctes. ### 22.4.1 `Iterable` et `Iterator` `foreach` dépend uniquement de `Iterable`. ```text interface Iterable { const method iterator() -> Iterator; } ``` Créer un iterator ne constitue pas une mutation sémantique de la source. `Iterator` représente une itération particulière et possède un état de progression mutable : ```text interface Iterator { method next() -> Option; } ``` `Some(value)` fournit l'élément suivant ; `None` marque la fin normale de l'itération. Saselang n'impose pas le couple `hasNext()` / `next()`. `Option` rend l'état de fin explicite dans une seule opération. `Iterator` n'étend pas `Iterable` par défaut. Une source capable de créer des itérations et une itération déjà en cours sont deux capacités différentes, même si certains types concrets peuvent éventuellement fournir les deux. Pour les collections ordinaires non concurrentes, une mutation structurelle invalide par défaut les iterators actifs lorsque le type concret ne garantit pas explicitement une autre politique. ```text insert / remove / clear / append / changement structurel -> peut invalider l'iterator utilisation ultérieure d'un iterator invalidé -> IteratorInvalidatedFault ``` Le simple remplacement d'une valeur existante n'est pas automatiquement une mutation structurelle. Le type concret documente sa politique exacte. Les collections concurrentes ou spécialisées peuvent fournir une autre politique (`snapshot`, stabilité, weak consistency, etc.) ; elle doit être explicite. ### 22.4.2 `View` `View` représente une vue légère sur une source existante : ```text interface View extends Iterable { const method count() -> uint64; const method isEmpty() -> bool; } ``` `View` n'étend pas `Collection`. Le contrat général ne contient pas `contains()`. Une classe ou une interface plus spécialisée peut l'ajouter si elle en a réellement besoin. Une `View` : ```text n'impose aucune copie des éléments n'impose aucun stockage indépendant n'impose aucune contiguïté ne possède pas nécessairement les données qu'elle expose ne peut jamais augmenter les permissions const de sa source ``` Par défaut, une vue est **vivante**, pas un snapshot : une nouvelle itération peut observer les modifications ultérieures de la source selon le contrat du type concret. Le runtime/compilateur garantit que le stockage ou l'état source nécessaire reste valide aussi longtemps que la vue l'exige, sans syntaxe de lifetime utilisateur. Le comportement d'un iterator déjà créé avant une modification reste régi par la politique d'invalidation/stabilité du type concret. ### 22.4.3 `Collection` `Collection` étend `Iterable` et représente une collection finie d'éléments. Contrat minimal : ```text count() -> uint64 isEmpty() -> bool contains(const T value) -> bool ``` `count()` exprime le nombre d'éléments au sens général de collection. ### 22.4.4 `List` `List` étend `Collection` et `OpIndex`. Elle garantit : ```text ordre stable indexation positionnelle en lecture length() -> uint64 ``` Pour une `List` : ```text count() == length() ``` Les deux noms restent distincts parce qu'ils expriment la cardinalité générale d'une collection et la longueur d'une séquence indexable. `List` ne garantit ni remplacement, ni redimensionnement, ni complexité algorithmique particulière de l'accès indexé. ### 22.4.5 `SettableList` `SettableList` étend `List` et `OpIndexMut`. Elle garantit le remplacement d'un élément existant sans modification de longueur : ```text list[index] = value; ``` `index` doit désigner une case existante ; l'affectation ne signifie jamais `append`. ### 22.4.6 `ResizableList` `ResizableList` étend `SettableList` et garantit des opérations structurelles capables de modifier la longueur. Les signatures exactes seront figées avec `Vector`. Un `resize(newLength)` sans information d'initialisation n'est pas retenu implicitement : agrandir une collection doit définir comment les nouveaux éléments sont construits. Lorsqu'il existe, `clear()` suit la convention : ```text clear() -> uint64 ``` et retourne le nombre d'éléments effectivement supprimés. ### 22.4.7 Capacité du type et permission `const` La capacité intrinsèque du type et la permission d'un accès sont deux dimensions distinctes. ```text SettableList users = ...; const SettableList readonly = users; ``` Le type sait remplacer des éléments, mais l'accès `readonly` ne peut pas utiliser cette capacité. La même règle s'applique à `Map`, `Set`, `View` et aux éléments obtenus à travers ces accès : une projection ne peut jamais augmenter les droits reçus de sa source. ### 22.4.8 Classification initiale des séquences ```text StaticArray List SettableList pas ResizableList Array List SettableList pas ResizableList Slice List SettableList pas ResizableList Vector List SettableList ResizableList ``` `Vector` reste à définir précisément. Un type persistant/immutable par nature n'a aucune obligation d'implémenter `List` s'il ne garantit pas sa sémantique. ### 22.4.9 `Set` et `ResizableSet` `Set` étend `Collection`. Il garantit : ```text unicité des éléments aucun index ordinal aucun ordre d'itération général garanti ``` La capacité structurelle est séparée : ```text interface ResizableSet extends Set { method add(T value) -> bool; method remove(const T value) -> bool; method clear() -> uint64; } ``` Sémantique : ```text add(value) true -> élément ajouté false -> élément déjà présent, set inchangé remove(value) true -> élément supprimé false -> élément absent clear() -> nombre d'éléments effectivement supprimés ``` Il n'existe pas de niveau `SettableSet` : remplacer un élément d'un set équivaut conceptuellement à une modification structurelle de son ensemble de valeurs. ### 22.4.10 `Map`, `SettableMap` et `ResizableMap` `Map` n'étend pas `Collection` et n'implémente pas directement `Iterable<...>`. Une map possède trois projections naturelles différentes : clés, valeurs et entrées ; aucune ne doit être choisie implicitement comme itération « par défaut ». Contrat de lecture : ```text interface Map extends OpIndex { const method count() -> uint64; const method isEmpty() -> bool; const method containsKey(const K key) -> bool; const method get(const K key) -> Option; const method keys() -> View; const method values() -> View; const method entries() -> View>; } ``` Deux intentions sont séparées : ```text map[key] -> V accès strict la clé doit exister absence dynamique -> KeyNotFoundFault map::get(key) -> Option accès conditionnel absence normale -> None ``` `SettableMap` étend `Map` et `OpIndexMut`. ```text map[key] = value; ``` remplace uniquement la valeur d'une clé existante. Cette syntaxe n'insère jamais implicitement une nouvelle clé. Une clé absente produit `KeyNotFoundFault`. `ResizableMap` étend `SettableMap` et ajoute les changements structurels : ```text insert(K key, V value) -> Void faults DuplicateKeyFault remove(const K key) -> Void faults KeyNotFoundFault clear() -> uint64 ``` `insert` affirme que la clé est nouvelle ; `remove` affirme qu'elle existe. Leurs violations dynamiques sont des `Fault` unchecked et capturables. Le Core ne fournit pas mécaniquement `tryInsert` / `tryRemove` ayant pour seule fonction de dupliquer ces opérations dans `Result` ou `bool`. Une variante conditionnelle ne sera ajoutée que si elle porte une sémantique réellement utile distincte. Il n'existe pas de `put()` implicite « insert ou replace » tant qu'un besoin concret ne justifie pas cette troisième intention. ### 22.4.11 `MapEntry` `MapEntry` représente une paire clé/valeur observée lors d'une projection `entries()`. Conceptuellement : ```text struct MapEntry { const method key() -> K; const method value() -> V; } ``` `MapEntry` n'est pas un proxy mutable vers un bucket interne de la map et n'expose pas de `setValue()` implicite. La mutation d'une map reste explicite via : ```text map[key] = value; ``` La sémantique de copie/référence de `K` et `V` suit les règles normales de leurs types. ### 22.4.12 Ordre : `Ordering`, `Comparable` et `Comparator` L'ordre total applicatif utilise : ```text enum Ordering { Less, Equal, Greater } ``` `Comparable` exprime l'ordre naturel ou principal du type dans son domaine : ```text interface Comparable { const method compareTo(const T other) -> Ordering; } ``` Un type peut tout à fait implémenter `Comparable` tout en supportant plusieurs ordres alternatifs via des comparators. Par exemple, un `User` d'un jeu peut avoir un classement principal naturel et rester comparable autrement par nom, niveau ou date. `Comparator` exprime un ordre externe/alternatif : ```text interface Comparator { const method compare(const T left, const T right) -> Ordering; } ``` Règle de sélection : ```text Comparator explicitement fourni -> utilisé exclusivement aucun Comparator fourni -> Comparable requis ``` Aucun mélange/fallback entre les deux n'est effectué pendant une même opération ou dans une même collection ordonnée. `Ordering::Equal` signifie équivalence selon cette relation d'ordre. Il n'implique pas nécessairement `left == right`. Les implémentations de `Comparable` et `Comparator` doivent respecter cohérence, symétrie d'ordre et transitivité. Le compilateur n'est pas tenu de prouver ces propriétés générales. ### 22.4.13 `SortedSet` et `SortedMap` `SortedSet` étend `Set` et garantit un ordre total stable selon le comparator actif : ```text interface SortedSet extends Set { const method comparator() -> Option>; const method first() -> Option; const method last() -> Option; } ``` `None` pour `comparator()` signifie que l'ordre naturel `Comparable` est utilisé. `Some(comparator)` expose l'ordre externe choisi pour cette instance. `SortedMap` étend `Map` et ordonne les entrées par clé : ```text interface SortedMap extends Map { const method comparator() -> Option>; const method firstKey() -> Option; const method lastKey() -> Option; } ``` Pour une `SortedMap`, les vues `keys()`, `values()` et `entries()` parcourent les données dans l'ordre des clés. Les opérations de bornes/ranges (`floor`, `ceiling`, `lower`, `higher` ou noms définitifs) seront fermées séparément afin de ne pas introduire de noms ambigus par simple imitation d'une autre plateforme. ### 22.4.14 `TreeSet` et `TreeMap` Les types standard ordonnés généraux sont nommés : ```text TreeSet TreeMap ``` Le nom n'impose pas une structure arborescente précise au niveau ABI/implémentation tant que le contrat observable reste respecté. Un futur `BTreeMap` peut exister comme implémentation explicitement fondée sur un B-tree ; il ne remplace pas le nom général `TreeMap`. Comme Saselang n'autorise qu'un `construct` par classe, les deux modes de création passent par des factories de classe distinctes : ```text TreeSet::natural() requiert T implements Comparable TreeSet::withComparator(Comparator comparator) n'exige pas Comparable TreeMap::natural() requiert K implements Comparable TreeMap::withComparator(Comparator comparator) n'exige pas Comparable ``` Les contraintes appartiennent aux factories concernées et non nécessairement au type générique entier. ### 22.4.15 Contraintes des implémentations concrètes Les interfaces abstraites `Set` et `Map` n'imposent pas une stratégie de stockage particulière. Ainsi : ```text HashSet / HashMap peuvent exiger des capacités de hash/égalité TreeSet / TreeMap utilisent Comparable ou Comparator ``` `Hashable`, l'égalité et leurs contrats exacts seront fermés dans le bloc dédié. Ils ne sont pas imposés à `Set` ou `Map` eux-mêmes. ### 22.4.16 Collections concurrentes Les garanties concurrentes sont orthogonales aux capacités structurelles et relèvent du SDK. Une future : ```text ConcurrentMap ``` exprime des garanties de concurrence/atomicité et ne remplace pas `ResizableMap`. Un type concret peut par exemple implémenter les deux : ```text ConcurrentHashMap implements ResizableMap, ConcurrentMap ``` Le SDK n'introduit pas une variante `ConcurrentX` pour chaque type uniquement par symétrie. Les interfaces concurrentes ne sont ajoutées que lorsqu'un contrat atomique/concurrent concret existe. Une opération composée n'est pas atomique simplement parce que chaque appel individuel est thread-safe. Les futures opérations atomiques (`putIfAbsent`, comparaison/remplacement, etc.) seront spécifiées avec le modèle de concurrence. ## 22.5 `Range` — V1 REQUIS — FIGÉ EN PRINCIPE `Range` est une vraie valeur Saselang immuable représentant un intervalle ordonné. Il ne représente ni un pas ni une progression d'itération. Les quatre syntaxes de bornes sont : ```text a..b [a, b] bornes basse et haute incluses a>..b (a, b] borne basse exclue, borne haute incluse a....` et ne recherche aucun type commun implicite entre deux bornes déjà typées différemment. Un littéral non encore typé peut toutefois être contextualisé normalement : ```text Range ids = 1..100; ``` ### 22.5.1 Domaine ordonné `Range` est disponible lorsque les valeurs admissibles utilisées comme bornes appartiennent à un domaine totalement ordonné selon le contrat de comparaison retenu par Saselang. La règle est fondée sur la capacité du type, pas sur une whitelist fermée. Elle peut donc s'appliquer à des entiers, `char`, des enums ou structs explicitement ordonnés, et à des types Core/utilisateur satisfaisant le contrat requis. Les enums n'obtiennent pas automatiquement un ordre à partir de leur ordre de déclaration : ils doivent fournir explicitement la capacité d'ordre total requise. Les floats sont autorisés comme bornes de `Range` uniquement pour leur sous-domaine fini : ```text NaN interdit comme borne +Infinity interdit comme borne -Infinity interdit comme borne valeur finie autorisée ``` `-0.0` et `+0.0` occupent la même position dans l'ordre numérique d'un range, même si leur représentation binaire reste distincte et observable par les mécanismes bas niveau appropriés. `NaN` et les infinities n'appartiennent à aucun `Range` défini avec ces règles ; `contains()` retourne donc `false` pour ces valeurs. ### 22.5.2 Construction et ranges vides Les bornes sont évaluées de gauche à droite, exactement une fois chacune, avant la construction du range. Une borne statiquement prouvée invalide provoque une erreur de compilation. Une borne calculée dynamiquement mais invalide selon le contrat de `Range` provoque un `Fault` runtime lors de la construction directe. Le nom concret du fault sera fixé avec l'API Core ; aucune variante `try... -> Result` parallèle n'est créée automatiquement pour la même validation. `lower > upper` ne constitue pas une erreur : le résultat est un range vide. Lorsque les bornes sont égales : ```text a..a contient exactement a a>..a vide a....` doit exposer au minimum les capacités conceptuelles suivantes, dont les noms sont retenus sauf raison ultérieure forte de les changer : ```text range::lower() range::upper() range::includesLower() range::includesUpper() range::isEmpty() range::contains(value) ``` Le range est immuable : modifier une borne signifie construire un autre `Range`. Le `match` utilisant un range-pattern emploie la même sémantique d'appartenance sans invoquer un prédicat utilisateur arbitraire. ## 22.6 Progression et itération des ranges — V1 REQUIS — FIGÉ EN PRINCIPE L'existence d'un `Range`, son itérabilité et sa progression sont trois concepts distincts : ```text Range intervalle ordonné RangeIterable parcours canonique vers l'avant RangeStep parcours avant avec pas explicite RangeReverse parcours canonique vers l'arrière RangeReverseStep parcours arrière avec pas explicite RangeProgression valeur de progression produite ``` Ces noms sont retenus comme noms Core significatifs ; leur namespace exact sera décidé lors de l'organisation générale de Core, probablement dans une famille dédiée aux ranges. Un type n'est pas obligé de fournir toutes ces capacités. Un range peut être valide sans être itérable ; il peut être itérable vers l'avant sans supporter `reverse()` ou `step()`. `foreach` continue à consommer `Iterable` : un `Range` ou une `RangeProgression` n'est utilisable par `foreach` que lorsque les capacités Core concernées fournissent cette itérabilité. ### 22.6.1 Progression canonique Lorsqu'un type fournit `RangeIterable`, le parcours direct d'un range utilise sa progression canonique. Celle-ci n'est pas définie génériquement comme un appel caché à `step(1)`. Pour les entiers Core, la progression canonique avance naturellement d'une unité. Pour `char`, elle avance parmi les Unicode scalar values valides et saute les valeurs surrogate `U+D800..U+DFFF`, qui ne sont pas des `char` Saselang valides. Un `Range` est un intervalle valide lorsque ses bornes sont finies, mais il n'est pas automatiquement itérable et ne reçoit pas automatiquement une capacité de `step` flottant. ### 22.6.2 `step(...)` Le pas ne fait jamais partie du `Range`. La syntaxe de parcours explicite est : ```text (range)::step(step) ``` Elle produit une progression itérable et ne modifie pas le `Range` d'origine. La compatibilité entre le type des bornes `T` et le type du pas `Step` est définie explicitement par `RangeStep` ou `RangeReverseStep`. Elle n'est pas déduite automatiquement d'une conversion numérique générale. Cela permet notamment de définir des couples adaptés au domaine : ```text RangeStep RangeStep RangeStep RangeStep ``` et de refuser des couples qui introduiraient une perte ou n'auraient pas de sens. Par exemple, un range `float16` peut recevoir seulement les types de pas explicitement supportés sans imposer qu'un `float32` plus large soit accepté. Le pas exprime une magnitude de progression, pas une direction. Pour les types numériques Core, il doit être strictement supérieur à zéro. Un pas statiquement nul ou négatif est une erreur de compilation ; une valeur dynamique invalide provoque un `Fault` runtime lors de la construction directe de la progression. Aucune variante `try... -> Result` n'est ajoutée uniquement pour dupliquer ce contrôle. Pour les types utilisateur, la validité du pas est définie par le contrat Range correspondant et n'est pas réduite artificiellement à une comparaison numérique avec zéro. ### 22.6.3 `reverse()` La direction inverse est explicite : ```text (range)::reverse() (range)::reverse()::step(step) ``` `reverse()` ne construit pas un range aux bornes inversées. Le `Range` reste identique ; seule la direction de parcours change. La forme canonique compose la direction avant le pas : ```text range [::reverse()] [::step(step)] ``` Une progression déjà matérialisée par `step()` n'est pas requise de fournir à son tour `reverse()`. Cela évite plusieurs chaînes d'appels synonymes pour le même parcours. L'inclusion ou l'exclusion des bornes reste une propriété du range et ne change jamais avec la direction. ### 22.6.4 Arrêt, overflow et pas non aligné Une progression s'arrête avant de produire une valeur hors du range. Elle ne doit jamais provoquer un overflow uniquement pour constater qu'elle a atteint la fin. Par exemple : ```text (250u8..255u8)::step(2u8) ``` produit conceptuellement : ```text 250 252 254 ``` sans tenter de former `256`. De même : ```text (1..10)::step(4) ``` produit : ```text 1 5 9 ``` La borne finale n'est pas ajoutée artificiellement si elle ne tombe pas naturellement sur la progression. Un range vide produit simplement une progression vide.