v0.2.15

examples/021-strings-unicode-et-encodages-examples.md

@@ -1,31 +1,18 @@
 # Exemples / DO-DON'T — Chapitre 21 — Strings, Unicode et encodages
 
-> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
+> Document compagnon. Les exemples illustrent les règles du chapitre ; la formulation normative reste dans le chapitre lui-même.
 
-## Exemples actuellement présents dans le chapitre
+## Exemples extraits du chapitre
 
 ### Exemple 1
 
 ```text
-Utf8String
-Utf16String
-Utf32String
-AsciiString éventuel
-Bytes
+String text = "abc";
+text::append("def"); // OK
 ```
 
 ### Exemple 2
 
-```text
-byte
-code unit
-Unicode scalar
-code point
-grapheme cluster
-```
-
-### Exemple 3
-
 ```text
 'A'
 'é'
@@ -35,8 +22,184 @@ grapheme cluster
 '\u{1F600}'
 ```
 
+### Exemple 3
+
+```text
+Utf8Char
+Utf16Char
+Utf32Char
+
+Utf8String
+Utf16String
+Utf32String
+```
+
 ### Exemple 4
 
+```text
+Utf8Char
+    exactement un Unicode scalar encodé en UTF-8
+    1 à 4 uint8
+
+Utf16Char
+    exactement un Unicode scalar encodé en UTF-16
+    1 à 2 uint16
+
+Utf32Char
+    exactement un Unicode scalar encodé en UTF-32
+    1 uint32
+```
+
+### Exemple 5
+
+```text
+Utf8String
+    séquence UTF-8 valide
+
+Utf16String
+    séquence UTF-16 valide
+
+Utf32String
+    séquence UTF-32 valide
+```
+
+### Exemple 6
+
+```text
+UTF-8  -> uint8
+UTF-16 -> uint16
+UTF-32 -> uint32
+```
+
+### Exemple 7
+
+```text
+char::toUtf8Char()
+Utf8Char::toChar()
+Utf8Char::toUtf16Char()
+
+Utf8Char::tryFrom(uint8)
+Utf16Char::tryFrom(uint16)
+Utf32Char::tryFrom(uint32)
+
+Utf8Char::tryToUint8()
+Utf16Char::tryToUint16()
+Utf32Char::toUint32()
+```
+
+### Exemple 8
+
+```text
+Utf8String text = ...;
+Utf16Char value = ...;
+
+text::append(value);                // ERROR
+text::append(value::toUtf8Char());  // OK
+```
+
+### Exemple 9
+
+```text
+String text = ...;
+text[5]; // ERROR
+```
+
+### Exemple 10
+
+```text
+text::scalarAt(index) -> char
+text::scalarCount() -> uint64
+```
+
+### Exemple 11
+
+```text
+Utf8String[index]  -> uint8
+Utf16String[index] -> uint16
+Utf32String[index] -> uint32
+```
+
+### Exemple 12
+
+```text
+encodedCharAt(scalarIndex)
+    retourne le UtfXChar correspondant au scalar ordinal demandé
+
+scalarAt(scalarIndex)
+    retourne le char correspondant
+```
+
+### Exemple 13
+
+```text
+Utf8String::encodedCharAt(uint64)  -> Utf8Char
+Utf16String::encodedCharAt(uint64) -> Utf16Char
+Utf32String::encodedCharAt(uint64) -> Utf32Char
+
+Utf8String::scalarAt(uint64)  -> char
+Utf16String::scalarAt(uint64) -> char
+Utf32String::scalarAt(uint64) -> char
+```
+
+### Exemple 14
+
+```text
+scalarCount()
+```
+
+### Exemple 15
+
+```text
+codeUnitCount()
+scalarCount()
+```
+
+### Exemple 16
+
+```text
+String implements Iterable<char>
+```
+
+### Exemple 17
+
+```text
+code units
+encoded chars
+Unicode scalars
+```
+
+### Exemple 18
+
+```text
+codeUnits()
+encodedChars()
+scalars()
+```
+
+### Exemple 19
+
+```text
+String text = "abc";
+text::append("def");
+```
+
+### Exemple 20
+
+```text
+Utf8String text = ...;
+Utf8Char value = ...;
+
+text::append(value); // OK
+```
+
+### Exemple 21
+
+```text
+text[index] = 0xFF; // ERROR
+```
+
+### Exemple 22
+
 ```text
 "..."                 String normale, escapes actifs
 """..."""             String normale multiligne
@@ -55,56 +218,19 @@ cr"..."               chaîne C brute, réservé
 t"..."                template structuré, réservé
 ```
 
-### Exemple 5
+### Exemple 23
 
 ```text
-i"Hello {name}"
-i"Hello ${name}"
-```
-
-### Exemple 6
-
-```text
-"""
-    first
-    second
-    """
-```
-
-### Exemple 7
-
-```text
-r"simple"
-r#"He said "hello"."#
-r##"contains "# inside"##
-```
-
-### Exemple 8
-
-```text
-r"""..."""
-r#"""..."""#
-```
-
-### Exemple 9
-
-```text
-\\      backslash
-\"      double quote
-\'      single quote
-\n      newline
-\r      carriage return
-\t      horizontal tab
-\0      NUL
-\u{...} Unicode scalar
-```
-
-### Exemple 10
-
-```text
-b"\x00\x7f\x80\xff"
+\\
+\"
+\'
+\n
+\r
+\t
+\0
+\u{...}
 ```
 
 ## DO / DON'T / WHY / compiler error / edge cases
 
-La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.
+À consolider progressivement avant la baseline publique V3 et à transformer, lorsque pertinent, en tests de conformité de la toolchain.