[6.2] Better docs for UTF8Span (#83184) (#83209)

Cherry pick of #83184

<!--
If this pull request is targeting a release branch, please fill out the
following form:

https://github.com/swiftlang/.github/blob/main/PULL_REQUEST_TEMPLATE/release.md?plain=1

Otherwise, replace this comment with a description of your changes and
rationale. Provide links to external references/discussions if
appropriate.
If this pull request resolves any GitHub issues, link them like so:

  Resolves <link to issue>, resolves <link to another issue>.

For more information about linking a pull request to an issue, see:

https://docs.github.com/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
-->

<!--
Before merging this pull request, you must run the Swift continuous
integration tests.
For information about triggering CI builds via @swift-ci, see:

https://github.com/apple/swift/blob/main/docs/ContinuousIntegration.md#swift-ci

Thank you for your contribution to Swift!
-->

Co-authored-by: Alex Martini <[email protected]>

Author: milseman

stdlib/public/core/UTF8EncodingError.swift

@@ -70,8 +70,6 @@ extension Unicode.UTF8 {
    errors (including overlong encodings, surrogates, and invalid code
    points), it will produce an error per byte.
 
-   // FIXME: without a checkAllErrors, we don't have these classification distinctions, should we drop it, ensure we will do it, or what?
-
    Since overlong encodings, surrogates, and invalid code points are erroneous
    by the second byte (at the latest), the above definition produces the same
    ranges as defining such a sequence as a truncated scalar error followed by

stdlib/public/core/UTF8Span.swift

@@ -1,7 +1,7 @@
 // TODO: comment header
 
 
-/// TODO: docs
+/// A borrowed view into contiguous memory that contains validly-encoded UTF-8 code units.
 @frozen
 @safe
 @available(SwiftStdlib 6.2, *)
@@ -71,6 +71,8 @@ extension UTF8Span {
   /// valid UTF-8, otherwise throws an error.
   ///
   /// The resulting UTF8Span has the same lifetime constraints as `codeUnits`.
+  ///
+  /// - Complexity: O(n)
   @lifetime(copy codeUnits)
   public init(
     validating codeUnits: consuming Span<UInt8>
@@ -174,10 +176,16 @@ extension UTF8Span {
 
 @available(SwiftStdlib 6.2, *)
 extension UTF8Span {
+  /// A Boolean value that indicates whether the UTF-8 span is empty.
+  ///
+  /// - Complexity: O(1)
   public var isEmpty: Bool {
     self.count == 0
   }
 
+  /// A span used to access the code units.
+  ///
+  /// - Complexity: O(1)
   public var span: Span<UInt8> {
     @lifetime(copy self)
     get {
@@ -190,7 +198,11 @@ extension UTF8Span {
 }
 
 extension String {
-
+  /// Creates a new string, copying the specified code units.
+  ///
+  /// This initializer skips UTF-8 validation because `codeUnits` must contain valid UTF-8.
+  ///
+  /// - Complexity: O(n)
   @available(SwiftStdlib 6.2, *)
   public init(copying codeUnits: UTF8Span) {
     let isASCII = codeUnits.isKnownASCII

stdlib/public/core/UTF8SpanBits.swift

@@ -12,6 +12,8 @@ extension UTF8Span {
   /// contained non-ASCII content would report false for `isKnownASCII`, even
   /// if that String had subsequent mutation operations that removed any
   /// non-ASCII content.
+  ///
+  /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   public var isKnownASCII: Bool {
     0 != _countAndFlags & Self._asciiBit
@@ -20,6 +22,8 @@ extension UTF8Span {
   /// Do a scan checking for whether the contents are all-ASCII.
   ///
   /// Updates the `isKnownASCII` bit if contents are all-ASCII.
+  ///
+  /// - Complexity: O(n)
   @lifetime(self: copy self)
   public mutating func checkForASCII() -> Bool {
     if isKnownASCII { return true }
@@ -35,7 +39,8 @@ extension UTF8Span {
 
   /// Returns whether the contents are known to be NFC. This is not
   /// always checked at initialization time and is set by `checkForNFC`.
-  // TODO: should this be @_unavailableInEmbedded
+  ///
+  /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   public var isKnownNFC: Bool {
     0 != _countAndFlags & Self._nfcBit
@@ -64,6 +69,8 @@ extension UTF8Span {
   /// algorithm. However, it cannot detect all NFC contents.
   ///
   /// Updates the `isKnownNFC` bit.
+  ///
+  /// - Complexity: O(n)
   @_unavailableInEmbedded
   @lifetime(self: copy self)
   public mutating func checkForNFC(
@@ -117,6 +124,9 @@ extension UTF8Span {
     0xFF00_0000_0000_0000
   }
 
+  /// The number of UTF-8 code units in the span.
+  ///
+  /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   public var count: Int {
     Int(truncatingIfNeeded: _countAndFlags & Self._countMask)

stdlib/public/core/UTF8SpanComparisons.swift

@@ -4,12 +4,16 @@
 @available(SwiftStdlib 6.2, *)
 extension UTF8Span {
   /// Whether this span has the same bytes as `other`.
+  ///
+  /// - Complexity: O(n)
   @_alwaysEmitIntoClient
   public func bytesEqual(to other: some Sequence<UInt8>) -> Bool {
     unsafe _withUnsafeBufferPointer { unsafe $0.elementsEqual(other) }
   }
 
   /// Whether this span has the same `Unicode.Scalar`s as `other`.
+  ///
+  /// - Complexity: O(n)
   @_alwaysEmitIntoClient
   public func unicodeScalarsEqual(
     to other: some Sequence<Unicode.Scalar>
@@ -31,6 +35,8 @@ extension UTF8Span {
   }
 
   /// Whether this span has the same `Character`s as `other`.
+  ///
+  /// - Complexity: O(n)
   @_unavailableInEmbedded
   @_alwaysEmitIntoClient
   public func charactersEqual(
@@ -54,6 +60,8 @@ extension UTF8Span {
 extension UTF8Span {
   /// Whether `self` is equivalent to `other` under Unicode Canonical
   /// Equivalence.
+  ///
+  /// - Complexity: O(n)
   public func isCanonicallyEquivalent(
     to other: UTF8Span
   ) -> Bool {
@@ -70,6 +78,8 @@ extension UTF8Span {
 
   /// Whether `self` orders less than `other` under Unicode Canonical
   /// Equivalence using normalized code-unit order (in NFC).
+  ///
+  /// - Complexity: O(n)
   public func isCanonicallyLessThan(
     _ other: UTF8Span
   ) -> Bool {

stdlib/public/core/UTF8SpanIterators.swift

@@ -9,9 +9,9 @@ extension UTF8Span {
     .init(self)
   }
 
+  // **TODO**: Examples in below doc
+
   /// Iterate the `Unicode.Scalar`s  contents of a `UTF8Span`.
-  ///
-  /// **TODO**: Examples
   @frozen
   public struct UnicodeScalarIterator: ~Escapable {
     public let codeUnits: UTF8Span
@@ -37,6 +37,8 @@ extension UTF8Span {
     /// of the next scalar.
     ///
     /// Returns `nil` if at the end of the `UTF8Span`.
+    ///
+    /// - Complexity: O(1)
     @lifetime(self: copy self)
     public mutating func next() -> Unicode.Scalar? {
       guard currentCodeUnitOffset < codeUnits.count else {
@@ -55,6 +57,8 @@ extension UTF8Span {
     /// previous scalar.
     ///
     /// Returns `nil` if at the start of the `UTF8Span`.
+    ///
+    /// - Complexity: O(1)
     @lifetime(self: copy self)
     public mutating func previous() -> Unicode.Scalar? {
       guard currentCodeUnitOffset > 0 else {
@@ -73,6 +77,8 @@ extension UTF8Span {
     ///
     /// Returns the number of `Unicode.Scalar`s skipped over, which can be 0
     /// if at the end of the UTF8Span.
+    ///
+    /// - Complexity: O(1)
     @lifetime(self: copy self)
     public mutating func skipForward() -> Int {
       guard currentCodeUnitOffset < codeUnits.count else {
@@ -90,6 +96,8 @@ extension UTF8Span {
     ///
     /// Returns the number of `Unicode.Scalar`s skipped over, which can be
     /// fewer than `n` if at the end of the UTF8Span.
+    ///
+    /// - Complexity: O(n)
     @lifetime(self: copy self)
     public mutating func skipForward(by n: Int) -> Int {
       var numSkipped = 0
@@ -105,6 +113,8 @@ extension UTF8Span {
     ///
     /// Returns the number of `Unicode.Scalar`s skipped over, which can be 0
     /// if at the start of the UTF8Span.
+    ///
+    /// - Complexity: O(1)
     @lifetime(self: copy self)
     public mutating func skipBack() -> Int {
       guard currentCodeUnitOffset > 0 else {
@@ -122,6 +132,8 @@ extension UTF8Span {
     ///
     /// Returns the number of `Unicode.Scalar`s skipped over, which can be
     /// fewer than `n` if at the start of the UTF8Span.
+    ///
+    /// - Complexity: O(n)
     @lifetime(self: copy self)
     public mutating func skipBack(by n: Int) -> Int {
       var numSkipped = 0
@@ -132,35 +144,39 @@ extension UTF8Span {
       return numSkipped
     }
 
+    // TODO: Example for reset docs
+
     /// Reset to the nearest scalar-aligned code unit offset `<= i`.
     ///
-    /// **TODO**: Example
+    /// - Complexity: O(1)
     @lifetime(self: copy self)
     public mutating func reset(roundingBackwardsFrom i: Int)  {
       self.currentCodeUnitOffset = codeUnits._scalarAlignBackwards(i)
     }
 
     /// Reset to the nearest scalar-aligned code unit offset `>= i`.
     ///
-    /// **TODO**: Example
+    /// - Complexity: O(1)
     @lifetime(self: copy self)
     public mutating func reset(roundingForwardsFrom i: Int)  {
       self.currentCodeUnitOffset = codeUnits._scalarAlignForwards(i)
     }
 
+    // TODO: for below, verify that there is no path to UB, just garabage-data or guaranteed
+    // trap!
+
     /// Reset this iterator to `codeUnitOffset`, skipping _all_ safety
     /// checks (including bounds checks).
     ///
     /// Note: This is only for very specific, low-level use cases. If
     /// `codeUnitOffset` is not properly scalar-aligned, this function can
     /// result in undefined behavior when, e.g., `next()` is called.
     ///
-    /// TODO: verify that we're not UB, just garabage-data or guaranteed
-    ///       trap!
-    ///
     /// For example, this could be used by a regex engine to backtrack to a
     /// known-valid previous position.
     ///
+    ///
+    /// - Complexity: O(1)
     @unsafe
     @lifetime(self: copy self)
     public mutating func reset(toUnchecked codeUnitOffset: Int) {
@@ -172,6 +188,8 @@ extension UTF8Span {
     /// current position.
     ///
     /// The resultant `UTF8Span` has the same lifetime constraints as `self`.
+    ///
+    /// - Complexity: O(1)
     @lifetime(copy self)
     public func prefix() -> UTF8Span {
       let slice = codeUnits.span.extracting(0..<currentCodeUnitOffset)
@@ -185,6 +203,8 @@ extension UTF8Span {
     /// current position.
     ///
     /// The resultant `UTF8Span` has the same lifetime constraints as `self`.
+    ///
+    /// - Complexity: O(1)
     @lifetime(copy self)
     public func suffix() -> UTF8Span {
       let slice = codeUnits.span.extracting(currentCodeUnitOffset..<codeUnits.count)
@@ -208,9 +228,9 @@ extension UTF8Span {
     .init(self)
   }
 
+  // **TODO**: Examples in below doc
+
   /// Iterate the `Character` contents of a `UTF8Span`.
-  ///
-  /// **TODO**: Examples
   public struct CharacterIterator: ~Escapable {
     public let codeUnits: UTF8Span