[stdlib] String API revisions

- Clarify StringProtocol conformance
- Deprecate ExpressibleByStringInterpolation
- String index conversions docs
- Describe shared string indices

Author: natecook1000

stdlib/public/core/CompilerProtocols.swift

@@ -673,30 +673,8 @@ public protocol ExpressibleByDictionaryLiteral {
 /// Conforming to the ExpressibleByStringInterpolation Protocol
 /// ===========================================================
 ///
-/// To use string interpolation to initialize instances of your custom type,
-/// implement the required initializers for `ExpressibleByStringInterpolation`
-/// conformance. String interpolation is a multiple-step initialization
-/// process. When you use string interpolation, the following steps occur:
-///
-/// 1. The string literal is broken into pieces. Each segment of the string
-///    literal before, between, and after any included expressions, along with
-///    the individual expressions themselves, are passed to the
-///    `init(stringInterpolationSegment:)` initializer.
-/// 2. The results of those calls are passed to the
-///    `init(stringInterpolation:)` initializer in the order in which they
-///    appear in the string literal.
-///
-/// In other words, initializing the `message` constant in the example above
-/// using string interpolation is equivalent to the following code:
-///
-///     let message = String(stringInterpolation:
-///           String(stringInterpolationSegment: "One cookie: $"),
-///           String(stringInterpolationSegment: price),
-///           String(stringInterpolationSegment: ", "),
-///           String(stringInterpolationSegment: number),
-///           String(stringInterpolationSegment: " cookies: $"),
-///           String(stringInterpolationSegment: price * number),
-///           String(stringInterpolationSegment: "."))
+/// The `ExpressibleByStringInterpolation` protocol is deprecated. Do not add
+/// new conformances to the protocol.
 @available(*, deprecated, message: "it will be replaced or redesigned in Swift 4.0.  Instead of conforming to 'ExpressibleByStringInterpolation', consider adding an 'init(_:String)'")
 public typealias ExpressibleByStringInterpolation = _ExpressibleByStringInterpolation
 public protocol _ExpressibleByStringInterpolation {

stdlib/public/core/String.swift

@@ -13,6 +13,9 @@
 import SwiftShims
 
 /// A type that can represent a string as a collection of characters.
+///
+/// Do not declare new conformances to `StringProtocol`. Only the `String` and
+/// `Substring` types in the standard library are valid conforming types.
 public protocol StringProtocol
   : BidirectionalCollection,
   TextOutputStream, TextOutputStreamable,
@@ -536,10 +539,10 @@ extension String {
 ///     // Prints "1"
 ///
 /// On the other hand, an emoji flag character is constructed from a pair of
-/// Unicode scalar values, like `"\u{1F1F5}"` and `"\u{1F1F7}"`. Each of
-/// these scalar values, in turn, is too large to fit into a single UTF-16 or
-/// UTF-8 code unit. As a result, each view of the string `"🇵🇷"` reports a
-/// different length.
+/// Unicode scalar values, like `"\u{1F1F5}"` and `"\u{1F1F7}"`. Each of these
+/// scalar values, in turn, is too large to fit into a single UTF-16 or UTF-8
+/// code unit. As a result, each view of the string `"🇵🇷"` reports a different
+/// length.
 ///
 ///     let flag = "🇵🇷"
 ///     print(flag.count)
@@ -561,22 +564,54 @@ extension String {
 ///
 /// To find individual elements of a string, use the appropriate view for your
 /// task. For example, to retrieve the first word of a longer string, you can
-/// search the `characters` view for a space and then create a new string from
-/// a prefix of the `characters` view up to that point.
+/// search the string for a space and then create a new string from a prefix
+/// of the string up to that point.
 ///
 ///     let name = "Marie Curie"
 ///     let firstSpace = name.index(of: " ") ?? name.endIndex
 ///     let firstName = name[..<firstSpace]
 ///     print(firstName)
 ///     // Prints "Marie"
 ///
-/// You can convert an index into one of a string's views to an index into
-/// another view.
+/// Strings and their views share indices, so you can access the UTF-8 view of
+/// the `name` string using the same `firstSpace` index.
 ///
-///     let firstSpaceUTF8 = firstSpace.samePosition(in: name.utf8)
-///     print(Array(name.utf8[..<firstSpaceUTF8]))
+///     print(Array(name.utf8[..<firstSpace]))
 ///     // Prints "[77, 97, 114, 105, 101]"
 ///
+/// Note that an index into one view may not have an exact corresponding
+/// position in another view. For example, the `flag` string declared above
+/// comprises a single character, but is composed of eight code units when
+/// encoded as UTF-8. The following code creates constants for the first and
+/// second positions in the `flag.utf8` view. Accessing the `utf8` view with
+/// these indices yields the first and second code UTF-8 units.
+///
+///     let firstCodeUnit = flag.startIndex
+///     let secondCodeUnit = flag.utf8.index(after: firstCodeUnit)
+///     // flag.utf8[firstCodeUnit] == 240
+///     // flag.utf8[secondCodeUnit] == 159
+///
+/// When used to access the elements of the `flag` string itself, however, the
+/// `secondCodeUnit` index does not correspond to the position of a specific
+/// character. Instead of only accessing the specific UTF-8 code unit, that
+/// index is treated as the position of the character at the index's encoded
+/// offset. In the case of `secondCodeUnit`, that character is still the flag
+/// itself.
+///
+///     // flag[firstCodeUnit] == "🇵🇷"
+///     // flag[secondCodeUnit] == "🇵🇷"
+///
+/// If you need to validate that an index from one string's view corresponds
+/// with an exact position in another view, use the index's
+/// `samePosition(in:)` method or the `init(_:within:)` initializer.
+///
+///     if let exactIndex = secondCodeUnit.samePosition(in: flag) {
+///         print(flag[exactIndex])
+///     } else {
+///         print("No exact match for this position.")
+///     }
+///     // Prints "No exact match for this position."
+///
 /// Performance Optimizations
 /// =========================
 ///

stdlib/public/core/StringIndexConversions.swift

@@ -12,7 +12,13 @@
 
 extension String.Index {
   /// Creates an index in the given string that corresponds exactly to the
-  /// specified `UnicodeScalarView` position.
+  /// specified position.
+  ///
+  /// If the index passed as `sourcePosition` represents the start of an
+  /// extended grapheme cluster---the element type of a string---then the
+  /// initializer succeeds. If the index instead represents the position of a
+  /// Unicode scalar within an extended grapheme cluster or the position of an
+  /// encoded Unicode scalar value, the result is `nil`.
   ///
   /// The following example converts the position of the Unicode scalar `"e"`
   /// into its corresponding position in the string. The character at that
@@ -28,21 +34,23 @@ extension String.Index {
   ///     print(cafe[...stringIndex])
   ///     // Prints "Café"
   ///
-  /// If the position passed in `unicodeScalarIndex` doesn't have an exact
-  /// corresponding position in `other`, the result of the initializer is
+  /// If the index passed as `sourcePosition` doesn't have an exact
+  /// corresponding position in `target`, the result of the initializer is
   /// `nil`. For example, an attempt to convert the position of the combining
   /// acute accent (`"\u{0301}"`) fails. Combining Unicode scalars do not have
   /// their own position in a string.
   ///
-  ///     let nextIndex = String.Index(cafe.unicodeScalars.index(after: scalarsIndex),
-  ///                                  within: cafe)
+  ///     let nextScalarsIndex = cafe.unicodeScalars.index(after: scalarsIndex)
+  ///     let nextStringIndex = String.Index(nextScalarsIndex, within: cafe)
+  ///
   ///     print(nextIndex)
   ///     // Prints "nil"
   ///
   /// - Parameters:
-  ///   - sourcePosition: A position in (a view of) the `other` parameter.
-  ///   - target: The string referenced by both `unicodeScalarIndex` and the
-  ///     resulting index.
+  ///   - sourcePosition: A position in a view of the `target` parameter.
+  ///     `sourcePosition` must be a valid index of at least one of the views
+  ///     of `target`.
+  ///   - target: The string referenced by the resulting index.
   public init?(
     _ sourcePosition: String.Index,
     within target: String
@@ -57,20 +65,23 @@ extension String.Index {
   /// Returns the position in the given UTF-8 view that corresponds exactly to
   /// this index.
   ///
-  /// The index must be a valid index of `String(utf8)`.
-  ///
-  /// This example first finds the position of the character `"é"` and then uses
-  /// this method find the same position in the string's `utf8` view.
+  /// This example first finds the position of the character `"é"`, and then
+  /// uses this method find the same position in the string's `utf8` view.
   ///
   ///     let cafe = "Café"
   ///     if let i = cafe.index(of: "é") {
-  ///         let j = i.samePosition(in: cafe.utf8)
+  ///         let j = i.samePosition(in: cafe.utf8)!
   ///         print(Array(cafe.utf8[j...]))
   ///     }
   ///     // Prints "[195, 169]"
   ///
-  /// - Parameter utf8: The view to use for the index conversion.
+  /// - Parameter utf8: The view to use for the index conversion. This index
+  ///   must be a valid index of at least one view of the string shared by
+  ///   `utf8`.
   /// - Returns: The position in `utf8` that corresponds exactly to this index.
+  ///   If this index does not have an exact corresponding position in `utf8`,
+  ///   this method returns `nil`. For example, an attempt to convert the
+  ///   position of a UTF-16 trailing surrogate returns `nil`.
   public func samePosition(
     in utf8: String.UTF8View
   ) -> String.UTF8View.Index? {
@@ -82,18 +93,23 @@ extension String.Index {
   ///
   /// The index must be a valid index of `String(utf16)`.
   ///
-  /// This example first finds the position of the character `"é"` and then uses
-  /// this method find the same position in the string's `utf16` view.
+  /// This example first finds the position of the character `"é"` and then
+  /// uses this method find the same position in the string's `utf16` view.
   ///
   ///     let cafe = "Café"
   ///     if let i = cafe.index(of: "é") {
-  ///         let j = i.samePosition(in: cafe.utf16)
+  ///         let j = i.samePosition(in: cafe.utf16)!
   ///         print(cafe.utf16[j])
   ///     }
   ///     // Prints "233"
   ///
-  /// - Parameter utf16: The view to use for the index conversion.
-  /// - Returns: The position in `utf16` that corresponds exactly to this index.
+  /// - Parameter utf16: The view to use for the index conversion. This index
+  ///   must be a valid index of at least one view of the string shared by
+  ///   `utf16`.
+  /// - Returns: The position in `utf16` that corresponds exactly to this
+  ///   index. If this index does not have an exact corresponding position in
+  ///   `utf16`, this method returns `nil`. For example, an attempt to convert
+  ///   the position of a UTF-8 continuation byte returns `nil`.
   public func samePosition(
     in utf16: String.UTF16View
   ) -> String.UTF16View.Index? {

stdlib/public/core/StringUTF16.swift

@@ -340,19 +340,27 @@ extension String.UTF16View.Index {
   /// Creates an index in the given UTF-16 view that corresponds exactly to the
   /// specified string position.
   ///
+  /// If the index passed as `sourcePosition` represents either the start of a
+  /// Unicode scalar value or the position of a UTF-16 trailing surrogate,
+  /// then the initializer succeeds. If `sourcePosition` does not have an
+  /// exact corresponding position in `target`, then the result is `nil`. For
+  /// example, an attempt to convert the position of a UTF-8 continuation byte
+  /// results in `nil`.
+  ///
   /// The following example finds the position of a space in a string and then
   /// converts that position to an index in the string's `utf16` view.
   ///
   ///     let cafe = "Café 🍵"
   ///
   ///     let stringIndex = cafe.index(of: "é")!
-  ///     let utf16Index = String.UTF16View.Index(stringIndex, within: cafe.utf16)
+  ///     let utf16Index = String.Index(stringIndex, within: cafe.utf16)!
   ///
   ///     print(cafe.utf16[...utf16Index])
   ///     // Prints "Café"
   ///
   /// - Parameters:
-  ///   - sourcePosition: A position in a string or one of its views
+  ///   - sourcePosition: A position in at least one of the views of the string
+  ///     shared by `target`.
   ///   - target: The `UTF16View` in which to find the new position.
   public init?(
     _ sourcePosition: String.Index, within target: String.UTF16View
@@ -377,6 +385,8 @@ extension String.UTF16View.Index {
   ///     // Prints "Café"
   ///
   /// - Parameter unicodeScalars: The view to use for the index conversion.
+  ///   This index must be a valid index of at least one view of the string
+  ///   shared by `unicodeScalars`.
   /// - Returns: The position in `unicodeScalars` that corresponds exactly to
   ///   this index. If this index does not have an exact corresponding
   ///   position in `unicodeScalars`, this method returns `nil`. For example,

stdlib/public/core/StringUnicodeScalarView.swift

@@ -378,34 +378,32 @@ extension String.UnicodeScalarIndex {
   ///     let cafe = "Café 🍵"
   ///
   ///     let utf16Index = cafe.utf16.index(of: 32)!
-  ///     let scalarIndex = String.UnicodeScalarView.Index(utf16Index, within: cafe.unicodeScalars)!
+  ///     let scalarIndex = String.Index(utf16Index, within: cafe.unicodeScalars)!
   ///
   ///     print(String(cafe.unicodeScalars[..<scalarIndex]))
   ///     // Prints "Café"
   ///
-  /// If the position passed in `utf16Index` doesn't have an exact
+  /// If the index passed as `sourcePosition` doesn't have an exact
   /// corresponding position in `unicodeScalars`, the result of the
   /// initializer is `nil`. For example, an attempt to convert the position of
-  /// the trailing surrogate of a UTF-16 surrogate pair fails.
+  /// the trailing surrogate of a UTF-16 surrogate pair results in `nil`.
   ///
   /// - Parameters:
-  ///   - utf16Index: A position in the `utf16` view of a string. `utf16Index`
+  ///   - sourcePosition: A position in the `utf16` view of a string. `utf16Index`
   ///     must be an element of `String(unicodeScalars).utf16.indices`.
   ///   - unicodeScalars: The `UnicodeScalarView` in which to find the new
   ///     position.
   public init?(
-    _ utf16Index: String.UTF16Index,
+    _ sourcePosition: String.UTF16Index,
     within unicodeScalars: String.UnicodeScalarView
   ) {
-    if !unicodeScalars._isOnUnicodeScalarBoundary(utf16Index) { return nil }
-    self = utf16Index
+    if !unicodeScalars._isOnUnicodeScalarBoundary(sourcePosition) { return nil }
+    self = sourcePosition
   }
 
   /// Returns the position in the given string that corresponds exactly to this
   /// index.
   ///
-  /// This index must be a valid index of `characters.unicodeScalars`.
-  ///
   /// This example first finds the position of a space (UTF-8 code point `32`)
   /// in a string's `utf8` view and then uses this method find the same position
   /// in the string.
@@ -417,6 +415,7 @@ extension String.UnicodeScalarIndex {
   ///     // Prints "🍵"
   ///
   /// - Parameter characters: The string to use for the index conversion.
+  ///   This index must be a valid index of at least one view of `characters`.
   /// - Returns: The position in `characters` that corresponds exactly to
   ///   this index. If this index does not have an exact corresponding
   ///   position in `characters`, this method returns `nil`. For example,