v0.2.17

examples/024-casts-et-conversions-examples.md

@@ -2,100 +2,102 @@
 
 > Document compagnon. Les exemples illustrent les règles du chapitre ; la formulation normative reste dans le chapitre lui-même.
 
-## Exemples extraits du chapitre
-
-### Exemple 1
-
-```text
-conversion de valeur
-cast de hiérarchie nominale
-bitcast de représentation binaire
-```
-
-### Exemple 2
+## Conversion explicite
 
 ```text
 int8 small = ...;
-int32 large = small;                 // ERROR
+int32 large = small;                     // ERROR
 int32 explicitLarge = small::toInt32(); // OK
 ```
 
-### Exemple 3
+## Widening total
 
 ```text
-Dog dog = ...;
-Animal animal = dog;
-Serializable serializable = dog;
+int8 value = ...;
+int32 larger = value::toInt32();
 ```
 
-### Exemple 4
+Aucun `tryToInt32()` parallèle n'est nécessaire si toutes les valeurs source sont exactement représentables.
+
+## Narrowing exact avec `Fault`
 
 ```text
-Animal animal = ...;
-
-if (animal is Dog) {
-    // animal est raffiné en Dog ici.
-}
+int32 value = ...;
+int8 smaller = value::toInt8();
 ```
 
-### Exemple 5
+La signature Core peut déclarer :
 
 ```text
-toTarget()
-    conversion exacte et totale
-
-tryToTarget()
-    conversion exacte pour la valeur courante, récupérable si impossible
-
-roundToTarget()
-    perte de précision explicitement acceptée, conversion totale
-
-tryRoundToTarget()
-    perte de précision explicitement acceptée, mais conversion pouvant échouer
-
-saturateToTarget()
-    saturation explicite lorsqu'aucun arrondi supplémentaire n'est nécessaire
-
-saturatingRoundToTarget()
-    arrondi + saturation explicitement annoncés
-
-wrapToTarget()
-    wrapping entier explicite
+toInt8() -> int8
+    faults NumericConversionFault
 ```
 
-### Exemple 6
+`OutOfRange` est produit lorsque la valeur ne tient pas dans `int8`.
+
+## Politiques distinctes
 
 ```text
-tryToIntXX()
-tryToUintXX()
+value::toInt8()       // exact, peut fault
+value::saturateToInt8()
+value::wrapToInt8()
 ```
 
-### Exemple 7
+Ces opérations coexistent seulement lorsque leur résultat peut réellement différer.
+
+## Flottant vers entier
 
 ```text
-floor()
-ceil()
-round()
-truncate()
+float64 value = ...;
+
+int32 exact = value::toInt32();
 ```
 
-### Exemple 8
+La conversion exige une valeur finie, intégrale et dans la plage.
+
+Pour choisir explicitement une politique mathématique :
 
 ```text
-value::floor()::tryToInt32()
-value::ceil()::tryToInt32()
-value::round()::tryToInt32()
-value::truncate()::tryToInt32()
+value::floor()::toInt32()
+value::ceil()::toInt32()
+value::round()::toInt32()
+value::truncate()::toInt32()
 ```
 
-### Exemple 9
+Pour choisir la politique de plage :
 
 ```text
-value::floor()::trySaturateToInt32()
-value::round()::tryWrapToInt32()
+value::floor()::saturateToInt32()
+value::round()::wrapToInt32()
 ```
 
-### Exemple 10
+## Entier vers flottant
+
+```text
+int64 value = ...;
+
+float64 exact = value::toFloat64();
+float64 approximated = value::roundToFloat64();
+```
+
+`toFloat64()` exige l'exactitude ; `roundToFloat64()` accepte explicitement la perte de précision.
+
+## Flottant vers flottant
+
+```text
+toFloatXX()
+    exige l'exactitude
+
+roundToFloatXX()
+    accepte l'arrondi canonique
+    peut fault OutOfRange sur une valeur finie
+
+saturatingRoundToFloatXX()
+    accepte l'arrondi canonique
+    sature une valeur finie hors domaine
+```
+
+Les catégories suivantes sont préservées :
 
 ```text
 NaN       -> NaN
@@ -105,31 +107,13 @@ NaN       -> NaN
 -0        -> -0
 ```
 
-### Exemple 11
+## `NumericConversionFault`
 
 ```text
-payload NaN
-quiet/signaling bit
-signe du NaN
-représentation binaire exacte
+NumericConversionFault extends Fault
 ```
 
-### Exemple 12
-
-```text
-tryToFloatXX()
-    exige une représentation exacte
-
-tryRoundToFloatXX()
-    accepte l'arrondi canonique
-    refuse une valeur finie hors domaine fini destination
-
-saturatingRoundToFloatXX()
-    accepte l'arrondi canonique
-    sature une valeur finie hors domaine vers +/-Target::Max
-```
-
-### Exemple 13
+Codes :
 
 ```text
 NotFinite
@@ -138,40 +122,10 @@ OutOfRange
 Inexact
 ```
 
-### Exemple 14
+DON'T : introduire mécaniquement :
 
 ```text
-NotFinite
-    NaN ou +/-Infinity lorsqu'une valeur finie est requise
-
-NotIntegral
-    float -> integer alors que la valeur n'est pas mathématiquement entière
-
-OutOfRange
-    valeur mathématique hors du domaine de la destination
-
-Inexact
-    valeur dans le domaine destination mais non représentable exactement
-    alors que l'opération exige l'exactitude
+tryToTarget() -> Result<Target,NumericConversionError>
 ```
 
-### Exemple 15
-
-```text
-sourceType
-targetType
-sourceValue
-timestamp
-backend
-roundingMode
-```
-
-### Exemple 16
-
-```text
-annexes/A-numeric-conversions.md
-```
-
-## DO / DON'T / WHY / compiler error / edge cases
-
-À consolider progressivement avant la baseline publique V3 et à transformer, lorsque pertinent, en tests de conformité de la toolchain.
+si cette méthode ne ferait que dupliquer `toTarget() faults NumericConversionFault`.