[stdlib] String.Index: conform to CustomDebugStringConvertible

[lorentey]

This PR conforms String.Index to CustomStringConvertible, making it easier to understand what these indices actually are, and considerably simplifying the debugging experience when working with string indices.

String indices currently print by dumping their raw contents, which is extraordinarily unhelpful:

let string = "👋🏼 هلو"

print(string.startIndex) // ⟹ Index(_rawBits: 15)
print(string.endIndex) // ⟹ Index(_rawBits: 983047)

With this PR, indices print by displaying their storage offset and encoding in a succinct format:

print(string.startIndex) // ⟹ "0[any]"
print(string.endIndex) // ⟹ "15[utf8]"

The specific format of the returned string and the information in it remains subject to change between Swift releases.

Related previous PRs:

• [stdlib] String.Index: Add _description & _debugDescription #61548
• [DRAFT][stdlib] String.Index: Add custom printing #58479
• [lldb] Add type summary for String.Index llvm-project#5515

Swift Evolution proposal:

• https://github.com/swiftlang/swift-evolution/blob/main/proposals/0445-string-index-printing.md

rdar://22794467

[lorentey]

@swift-ci test

[lorentey]

The first test run is expected to fail. (The ABI verifier will need updates, but I'm hoping that's all.)

[benrimmington]

When the Sequence.count(where:) method was re-implemented, there was a comment that the standard library can't effectively use @backDeployed yet.

[Azoy]

I'm not sure what the issue was back then, but hopefully it's been resolved since then 🤞

[lorentey]

One seemingly minor issue that keeps causing trouble is that @backDeployed does not gracefully handle mid-release ABI transitions -- people whose SDK is out of phase with their running OS may end up building code that fails to link at runtime.

Another issue I recently discovered is that @backDeployed functions cannot be used to fulfill a member requirement in a retroactive protocol conformance. It is tempting to try backdeploying the CustomStringConvertible conformance by putting this in a public package somewhere:

extension String.Index: @retroactive CustomStringConvertible {
 // `description` comes straight from the stdlib
}

However, if description is marked @backDeployed, then this fails at runtime on versions predating its introduction. (This is clearly a bug, as @_alwaysEmitIntoClient functions do work in the same context.)

---

I think we'll want to keep String.Index.description as opaque as possible -- it cannot be defined fully @_aeic, or we would give up the flexibility to change its implementation later. At the same time, I also want the function to deploy back to earlier versions.

This is the alternative I'm considering -- it's kind of a homegrown @backDeploy, built from chewing gum and twine.

extension String.Index {
  @_alwaysEmitIntoClient
  public var description: String {
    if #available(SwiftStdlib 6.1, *) {
      return _descriptionImpl()
    }
    return _description
  }

  @_alwaysEmitIntoClient
  @inline(never)
  public var _description: String { // Preexisting member
    // 23[utf8]+1
    var d = "\(_encodedOffset)[\(_encodingDescription)]"
    if transcodedOffset != 0 {
      d += "+\(transcodedOffset)"
    }
    return d
  }

  @available(SwiftStdlib 6.1, *)
  @usableFromInline
  internal func _descriptionImpl() -> String {
    _description
  }
}

I don't love that the exported symbol name is different from String.description, but this may be a workable alternative. It makes it easy to tweak the description in future releases of the stdlib, without affecting its result when run on older versions.

Luckily, these are implementation details that do not matter for Swift Evolution. (We do promise that the property will be backdeployable, but the mechanism for that and the precise list of new symbols that the stdlib will expose are not normative.)

[benrimmington]

This is the alternative I'm considering -- it's kind of a homegrown @backDeploy, built from chewing gum and twine.

If that alternative works, perhaps it should be documented alongside CRISP. However, if the pre-existing _description can still be used, why does description need to be back-deployable, when the conformance to CustomStringConvertible cannot be back-deployed?

[lorentey]

Swift does not allow the stdlib to backdeploy the conformance, but it also doesn't forbid user code to ship a retroactive conformance with the same effect:

It is tempting to try backdeploying the CustomStringConvertible conformance by putting this in a public package somewhere:

extension String.Index: @retroactive CustomStringConvertible {
 // `description` comes straight from the stdlib
}

I am toying with the idea to suggest publishing an official stdlib companion package to ship such things. (This is not crucial for CustomStringConvertible, but back-deployment will be very desirable for all the upcoming Equatable/Hashable conformances on string views -- we cannot live without them.)

[lorentey]

@swift-ci test macOS platform

[lorentey]

@swift-ci test

[lorentey]

@swift-ci test

[lorentey]

@swift-ci test

[lorentey]

@swift-ci test

[lorentey]

@swift-ci test source compatibility