Merge pull request swiftlang#84623 from valeriyvan/UTF8SpanIterators1

Address 3 TODOs adding examples to UTF8SpanIterators

Author: Azoy

stdlib/public/core/UTF8SpanIterators.swift

@@ -21,9 +21,19 @@ extension UTF8Span {
     .init(self)
   }
 
-  // **TODO**: Examples in below doc
-
-  /// Iterate the `Unicode.Scalar`s  contents of a `UTF8Span`.
+  /// Iterate the `Unicode.Scalar`s contents of a `UTF8Span`.
+  ///
+  ///     func printScalarValues(_ string: borrowing String) {
+  ///         var iterator = string.utf8Span.makeUnicodeScalarIterator()
+  ///         while let scalar = iterator.next() {
+  ///             print(scalar.escaped(asASCII: true))
+  ///         }
+  ///     }
+  ///
+  ///     let string = "A🎉"
+  ///     printScalarValues(string)
+  ///     // Prints "A"
+  ///     // Prints "\u{0001F389}"
   @frozen
   public struct UnicodeScalarIterator: ~Escapable {
     public let codeUnits: UTF8Span
@@ -156,10 +166,18 @@ extension UTF8Span {
       return numSkipped
     }
 
-    // TODO: Example for reset docs
-
     /// Reset to the nearest scalar-aligned code unit offset `<= i`.
     ///
+    ///     func printScalarAfterReset(_ string: borrowing String) {
+    ///         var iterator = string.utf8Span.makeUnicodeScalarIterator()
+    ///         iterator.reset(roundingBackwardsFrom: 8)  // Position 8 is mid-emoji, rounds back to 6
+    ///         if let scalar = iterator.next() {
+    ///             print(scalar)  // Prints "🌍" (emoji starts at byte 6)
+    ///         }
+    ///     }
+    ///     let string = "Hello 🌍"
+    ///     printScalarAfterReset(string)
+    ///
     /// - Complexity: O(1)
     @lifetime(self: copy self)
     public mutating func reset(roundingBackwardsFrom i: Int)  {
@@ -240,9 +258,26 @@ extension UTF8Span {
     .init(self)
   }
 
-  // **TODO**: Examples in below doc
-
   /// Iterate the `Character` contents of a `UTF8Span`.
+  ///
+  ///     func countCharacters(_ string: borrowing String) {
+  ///         var iterator = string.utf8Span.makeCharacterIterator()
+  ///         var count = 0
+  ///         while let character = iterator.next() {
+  ///             count += 1
+  ///             print("Character \(count): \(character)")
+  ///         }
+  ///         print("Total: \(count) characters")
+  ///     }
+  ///
+  ///     let string = "لاهور"
+  ///     countCharacters(string)
+  ///     // Prints "Character 1: ل"
+  ///     // Prints "Character 2: ا"
+  ///     // Prints "Character 3: ه"
+  ///     // Prints "Character 4: و"
+  ///     // Prints "Character 5: ر"
+  ///     // Prints "Total: 5 characters"
   public struct CharacterIterator: ~Escapable {
     public let codeUnits: UTF8Span