You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The sample description strings shown above are illustrative, not normative. This proposal does not specify the exact format and information content of the string returned by the `description` implementation on `String.Index`. As is the case with most conformances to `CustomStringConvertible`, the purpose of these descriptions is to expose internal implementation details for debugging purposes. As those implementation details evolve, the descriptions may need to be changed to match them. Such changes are not generally expected to be part of the Swift Evolution process; so we need to keep the content of these descriptions unspecified.
45
+
The sample output strings shown above are illustrative, not normative. This proposal does not specify the exact format and information content of the string returned by the `debugDescription` implementation on `String.Index`. As is the case with most conformances to `CustomDebugStringConvertible`, the purpose of these descriptions is to expose internal implementation details for debugging purposes. As those implementation details evolve, the descriptions may need to be changed to match them. Such changes are not generally expected to be part of the Swift Evolution process; so we need to keep the content of these descriptions unspecified.
45
46
46
-
(With that said, the example displays shown above are not newly invented -- they have already proved their usefulness in actual use. They were developed while working on subtle string processing problems in Swift 5.7, and [LLDB has been shipping them as built-in data formatters][lldb] since the Swift 5.8 release.
47
+
(With that said, the example displays shown above are not newly invented -- they have already proven their usefulness in actual use. They were developed while working on subtle string processing problems in Swift 5.7, and [LLDB has been shipping them as built-in data formatters][lldb] since the Swift 5.8 release.
47
48
48
49
In the displays shown, string indices succinctly display their storage offset, their expected encoding, and an (optional) transcoded offset value. For example, the output `15[utf8]` indicates that the index is addressing the code unit at offset 15 in a UTF-8 encoded `String` value. The `startIndex` is at offset zero, which works the same with _any_ encoding, so it is displayed as `0[any]`. As of Swift 6.0, on some platforms string instances may store their text in UTF-16, and so indices within such strings use `[utf16]` to specify that their offsets are measured in UTF-16 code units.
49
50
@@ -53,44 +54,42 @@ The `+1` in `0[utf8]+1` is an offset into a _transcoded_ Unicode scalar; this in
53
54
54
55
All of this is really useful information to see while developing or debugging string algorithms, but it is also deeply specific to the particular implementation of `String` that ships in Swift 6.0; therefore it is inherently unstable, and it may change in any Swift release.)
55
56
56
-
<!--
57
-
```
58
-
Characters: | 👋🏼 | " " | H | e | l | l | ó |
59
-
Scalars: | 👋 | "\u{1F3FC}" | " " | H | e | l | l | ó |
The new conformance changes the result of converting a `String.Index` value to a string. This changes observable behavior: code that attempts to parse the result of `String(describing:)` can be mislead by the change of format.
78
+
The new conformance changes the result of converting a `String.Index` value to a string. This changes observable behavior: code that attempts to parse the result of `String(describing:)`or `String(reflecting:)`can be mislead by the change of format.
80
79
81
-
However, `String(describing:)` and `String(reflecting:)` explicitly state that when the input type conforms to none of the standard string conversion protocols, then the result of these operations is unspecified.
80
+
However, the documentation of these interfaces explicitly state that when the input type conforms to none of the standard string conversion protocols, then the result of these operations is unspecified.
82
81
83
82
Changing the value of an unspecified result is not considered to be a source incompatible change.
84
83
85
84
## ABI compatibility
86
85
87
-
The proposal retroactively conforms a previously existing standard type to a previously existing standard protocol. This is technically an ABI breaking change -- on ABI stable platforms, we may have preexisting Swift binaries that assume that `String.Index is CustomStringConvertible` returns `false`, or ones that are implementing this conformance on their own.
86
+
The proposal retroactively conforms a previously existing standard type to a previously existing standard protocol. This is technically an ABI breaking change -- on ABI stable platforms, we may have preexisting Swift binaries that assume that `String.Index is CustomDebugStringConvertible` returns `false`, or ones that are implementing this conformance on their own.
88
87
89
88
We do not expect this to be an issue in practice.
90
89
91
90
## Implications on adoption
92
91
93
-
The `String.Index.description` property is defined to be backdeployable, but the conformance itself is not. (It cannot be.)
92
+
The `String.Index.debugDescription` property is defined to be backdeployable, but the conformance itself is not. (It cannot be.)
94
93
95
94
Code that runs on ABI stable platforms will not get the nicer displays when running on earlier versions of the Swift Standard Library.
Other preexisting types in the Standard Library may also usefully gain `CustomStringConvertible` conformances in the future:
114
+
Other preexisting types in the Standard Library may also usefully gain custom string conversions in the future:
116
115
117
116
-`Set.Index`, `Dictionary.Index`
118
117
-`Slice`, `DefaultIndices`
@@ -124,7 +123,7 @@ Other preexisting types in the Standard Library may also usefully gain `CustomSt
124
123
125
124
### New String API to expose the information in these descriptions
126
125
127
-
The information exposed in the index descriptions shown above is mostly retrievable through public APIs, but not entirely: perhaps most importantly, there is no way to get the expected encoding of a string index through the stdlib's public API surface. The lack of such an API may encourage interested Swift developers to try retrieving this information by parsing the unstable `description` string, or by bitcasting indices to peek at the underlying bit patterns -- neither of which would be healthy for the Swift ecosystem overall. It therefore is desirable to eventually expose this information as well, through API additons like the drafts below:
126
+
The information exposed in the index descriptions shown above is mostly retrievable through public APIs, but not entirely: perhaps most importantly, there is no way to get the expected encoding of a string index through the stdlib's public API surface. The lack of such an API may encourage interested Swift developers to try retrieving this information by parsing the unstable `debugDescription` string, or by bitcasting indices to peek at the underlying bit patterns -- neither of which would be healthy for the Swift ecosystem overall. It therefore is desirable to eventually expose this information as well, through API additons like the drafts below:
128
127
129
128
```swift
130
129
extensionString {
@@ -173,4 +172,9 @@ Given that these APIs are quite obscure/subtle, and they pose some interesting d
173
172
174
173
## Alternatives considered
175
174
176
-
None.
175
+
The original version of this proposal suggested conforming `String.Index` to `CustomStringConvertible`, not `CustomDebugStringConvertible`. The change to the debug-flavored protocol emphasizes that the new descriptions aren't intended to be used outside debugging contexts.
176
+
177
+
178
+
## Acknowledgements
179
+
180
+
We'd like to express our appreciation to Jordan Rose and Ben Rimmington for scratching at the `CustomStringConvertible` vs `CustomDebugStringConvertible` distinction during the review discussion.
0 commit comments