Merge pull request swiftlang#71224 from glessard/rdar121395821

[stdlib] Improve documentation for the various "String from C-string" initializers

Author: glessard

stdlib/public/core/CString.swift

@@ -42,7 +42,8 @@ extension String {
   ///     }
   ///     // Prints "Caf�"
   ///
-  /// - Parameter nullTerminatedUTF8: A pointer to a null-terminated UTF-8 code sequence.
+  /// - Parameter nullTerminatedUTF8:
+  ///     A pointer to a null-terminated sequence of UTF-8 code units.
   public init(cString nullTerminatedUTF8: UnsafePointer<CChar>) {
     let len = UTF8._nullCodeUnitOffset(in: nullTerminatedUTF8)
     let buffer = UnsafeBufferPointer(start: nullTerminatedUTF8, count: len)
@@ -51,8 +52,24 @@ extension String {
     }
   }
 
+  /// Creates a new string by copying the null-terminated UTF-8 data referenced
+  /// by the given array.
+  ///
+  /// If `cString` contains ill-formed UTF-8 code unit sequences, this
+  /// initializer replaces them with the Unicode replacement character
+  /// (`"\u{FFFD}"`).
+  ///
+  /// - Note: This initializer is deprecated. Use the initializer
+  ///         `String.init(decoding: array, as: UTF8.self)` instead,
+  ///         remembering that "\0" is a valid character in Swift.
+  ///
+  /// - Parameter nullTerminatedUTF8:
+  ///     An array containing a null-terminated sequence of UTF-8 code units.
   @inlinable
   @_alwaysEmitIntoClient
+  @available(swift, deprecated: 6, message:
+    "Use String(decoding: array, as: UTF8.self) instead, after truncating the null termination."
+  )
   public init(cString nullTerminatedUTF8: [CChar]) {
     self = nullTerminatedUTF8.withUnsafeBufferPointer {
       $0.withMemoryRebound(to: UInt8.self, String.init(_checkingCString:))
@@ -91,14 +108,32 @@ extension String {
   ///
   /// This is identical to `init(cString: UnsafePointer<CChar>)` but operates on
   /// an unsigned sequence of bytes.
+  ///
+  /// - Parameter nullTerminatedUTF8:
+  ///     A pointer to a null-terminated sequence of UTF-8 code units.
   public init(cString nullTerminatedUTF8: UnsafePointer<UInt8>) {
     let len = UTF8._nullCodeUnitOffset(in: nullTerminatedUTF8)
     self = String._fromUTF8Repairing(
       UnsafeBufferPointer(start: nullTerminatedUTF8, count: len)).0
   }
 
+  /// Creates a new string by copying the null-terminated UTF-8 data referenced
+  /// by the given array.
+  ///
+  /// This is identical to `init(cString: [CChar])` but operates on
+  /// an unsigned sequence of bytes.
+  ///
+  /// - Note: This initializer is deprecated. Use the initializer
+  ///         `String.init(decoding: array, as: UTF8.self)` instead,
+  ///         remembering that "\0" is a valid character in Swift.
+  ///
+  /// - Parameter nullTerminatedUTF8:
+  ///     An array containing a null-terminated UTF-8 code unit sequence.
   @inlinable
   @_alwaysEmitIntoClient
+  @available(swift, deprecated: 6, message:
+    "Use String(decoding: array, as: UTF8.self) instead, after truncating the null termination."
+  )
   public init(cString nullTerminatedUTF8: [UInt8]) {
     self = nullTerminatedUTF8.withUnsafeBufferPointer {
       String(_checkingCString: $0)
@@ -150,7 +185,7 @@ extension String {
   ///     // Prints "nil"
   ///
   /// - Parameter nullTerminatedUTF8:
-  ///       A pointer to a null-terminated UTF-8 code sequence.
+  ///     A pointer to a null-terminated sequence of UTF-8 code units.
   @inlinable
   @_alwaysEmitIntoClient
   public init?(validatingCString nullTerminatedUTF8: UnsafePointer<CChar>) {
@@ -183,10 +218,11 @@ extension String {
   ///     }
   ///     // Prints "nil"
   ///
-  /// Note: This initializer is deprecated. Use
-  ///       `String.init?(validatingCString:)` instead.
+  /// - Note: This initializer has been renamed. Use
+  ///         `String.init?(validatingCString:)` instead.
   ///
-  /// - Parameter cString: A pointer to a null-terminated UTF-8 code sequence.
+  /// - Parameter cString:
+  ///     A pointer to a null-terminated sequence of UTF-8 code units.
   @available(swift, deprecated: 6, renamed: "String.init(validatingCString:)")
   public init?(validatingUTF8 cString: UnsafePointer<CChar>) {
     let len = UTF8._nullCodeUnitOffset(in: cString)
@@ -198,8 +234,23 @@ extension String {
     self = str
   }
 
+  /// Creates a new string by copying and validating the null-terminated UTF-8
+  /// data referenced by the given array.
+  ///
+  /// This initializer does not try to repair ill-formed UTF-8 code unit
+  /// sequences. If any are found, the result of the initializer is `nil`.
+  ///
+  /// - Note: This initializer is deprecated. Use the initializer
+  ///         `String.init?(validating: array, as: UTF8.self)` instead,
+  ///         remembering that "\0" is a valid character in Swift.
+  ///
+  /// - Parameter nullTerminatedUTF8:
+  ///     An array containing a null-terminated sequence of UTF-8 code units.
   @inlinable
   @_alwaysEmitIntoClient
+  @available(swift, deprecated: 6, message:
+    "Use String(validating: array, as: UTF8.self) instead, after truncating the null termination."
+  )
   public init?(validatingCString nullTerminatedUTF8: [CChar]) {
     guard let length = nullTerminatedUTF8.firstIndex(of: 0) else {
       _preconditionFailure(
@@ -213,9 +264,23 @@ extension String {
     self = string
   }
 
+  /// Creates a new string by copying and validating the null-terminated UTF-8
+  /// data referenced by the given array.
+  ///
+  /// This initializer does not try to repair ill-formed UTF-8 code unit
+  /// sequences. If any are found, the result of the initializer is `nil`.
+  ///
+  /// - Note: This initializer is deprecated. Use the initializer
+  ///         `String.init?(validating: array, as: UTF8.self)` instead,
+  ///         remembering that "\0" is a valid character in Swift.
+  ///
+  /// - Parameter cString:
+  ///     An array containing a null-terminated sequence of UTF-8 code units.
   @inlinable
   @_alwaysEmitIntoClient
-  @available(swift, deprecated: 6, renamed: "String.init(validatingCString:)")
+  @available(swift, deprecated: 6, message:
+    "Use String(validating: array, as: UTF8.self) instead, after truncating the null termination."
+  )
   public init?(validatingUTF8 cString: [CChar]) {
     self.init(validatingCString: cString)
   }
@@ -240,7 +305,7 @@ extension String {
   public init?(validatingCString nullTerminatedUTF8: inout CChar) {
     guard nullTerminatedUTF8 == 0 else {
       _preconditionFailure(
-        "input of String.init(validatingUTF8:) must be null-terminated"
+        "input of String.init(validatingCString:) must be null-terminated"
       )
     }
     self = ""
@@ -284,8 +349,8 @@ extension String {
   ///     // Prints "Optional((result: "Caf�", repairsMade: true))"
   ///
   /// - Parameters:
-  ///   - cString: A pointer to a null-terminated code sequence encoded in
-  ///     `encoding`.
+  ///   - cString: A pointer to a null-terminated sequence of
+  ///     code units encoded in `encoding`.
   ///   - encoding: The Unicode encoding of the data referenced by `cString`.
   ///   - isRepairing: Pass `true` to create a new string, even when the data
   ///     referenced by `cString` contains ill-formed sequences. Ill-formed
@@ -329,9 +394,7 @@ extension String {
       codeUnits, encoding: encoding, repair: isRepairing)
   }
 
-  @_specialize(where Encoding == Unicode.UTF8)
-  @_specialize(where Encoding == Unicode.UTF16)
-  @inlinable // Fold away specializations
+  @inlinable
   @_alwaysEmitIntoClient
   public static func decodeCString<Encoding: _UnicodeEncoding>(
     _ cString: [Encoding.CodeUnit],
@@ -365,8 +428,6 @@ extension String {
     }
   }
 
-  @_specialize(where Encoding == Unicode.UTF8)
-  @_specialize(where Encoding == Unicode.UTF16)
   @inlinable
   @_alwaysEmitIntoClient
   @available(*, deprecated, message: "Use a copy of the String argument")
@@ -382,8 +443,6 @@ extension String {
     }
   }
 
-  @_specialize(where Encoding == Unicode.UTF8)
-  @_specialize(where Encoding == Unicode.UTF16)
   @inlinable
   @_alwaysEmitIntoClient
   @available(*, deprecated, message: "Use String(_ scalar: Unicode.Scalar)")
@@ -400,58 +459,74 @@ extension String {
     return ("", false)
   }
 
-  /// Creates a string from the null-terminated sequence of bytes at the given
-  /// pointer.
+  /// Creates a new string by copying the null-terminated sequence of code units
+  /// referenced by the given pointer.
+  ///
+  /// If `nullTerminatedCodeUnits` contains ill-formed code unit sequences, this
+  /// initializer replaces them with the Unicode replacement character
+  /// (`"\u{FFFD}"`).
   ///
   /// - Parameters:
-  ///   - nullTerminatedCodeUnits: A pointer to a sequence of contiguous code
-  ///     units in the encoding specified in `sourceEncoding`, ending just
-  ///     before the first zero code unit.
-  ///   - sourceEncoding: The encoding in which the code units should be
+  ///   - nullTerminatedCodeUnits: A pointer to a null-terminated sequence of
+  ///     code units encoded in `encoding`.
+  ///   - encoding: The encoding in which the code units should be
   ///     interpreted.
   @_specialize(where Encoding == Unicode.UTF8)
   @_specialize(where Encoding == Unicode.UTF16)
   @inlinable // Fold away specializations
   public init<Encoding: Unicode.Encoding>(
     decodingCString nullTerminatedCodeUnits: UnsafePointer<Encoding.CodeUnit>,
-    as sourceEncoding: Encoding.Type
+    as encoding: Encoding.Type
   ) {
-    self = String.decodeCString(nullTerminatedCodeUnits, as: sourceEncoding)!.0
+    self = String.decodeCString(nullTerminatedCodeUnits, as: encoding)!.0
   }
 
-  @_specialize(where Encoding == Unicode.UTF8)
-  @_specialize(where Encoding == Unicode.UTF16)
-  @inlinable // Fold away specializations
+  /// Creates a new string by copying the null-terminated sequence of code units
+  /// referenced by the given array.
+  ///
+  /// If `nullTerminatedCodeUnits` contains ill-formed code unit sequences, this
+  /// initializer replaces them with the Unicode replacement character
+  /// (`"\u{FFFD}"`).
+  ///
+  /// - Note: This initializer is deprecated. Use the initializer
+  ///         `String.init(decoding: array, as: Encoding.self)` instead,
+  ///         remembering that "\0" is a valid character in Swift.
+  ///
+  /// - Parameters:
+  ///   - nullTerminatedCodeUnits: An array containing a null-terminated
+  ///     sequence of code units encoded in `encoding`.
+  ///   - encoding: The encoding in which the code units should be
+  ///     interpreted.
+  @inlinable
   @_alwaysEmitIntoClient
+  @available(swift, deprecated: 6, message:
+    "Use String(decoding: array, as: Encoding.self) instead, after truncating the null termination."
+  )
   public init<Encoding: Unicode.Encoding>(
     decodingCString nullTerminatedCodeUnits: [Encoding.CodeUnit],
-    as sourceEncoding: Encoding.Type
+    as encoding: Encoding.Type
   ) {
-    self = String.decodeCString(nullTerminatedCodeUnits, as: sourceEncoding)!.0
+    self = String.decodeCString(nullTerminatedCodeUnits, as: encoding)!.0
   }
 
-  @_specialize(where Encoding == Unicode.UTF8)
-  @_specialize(where Encoding == Unicode.UTF16)
   @inlinable
   @_alwaysEmitIntoClient
   @available(*, deprecated, message: "Use a copy of the String argument")
   public init<Encoding: _UnicodeEncoding>(
     decodingCString nullTerminatedCodeUnits: String,
-    as sourceEncoding: Encoding.Type
+    as encoding: Encoding.Type
   ) {
-    self = nullTerminatedCodeUnits.withCString(encodedAs: sourceEncoding) {
-      String(decodingCString: $0, as: sourceEncoding.self)
+    self = nullTerminatedCodeUnits.withCString(encodedAs: encoding) {
+      String(decodingCString: $0, as: encoding.self)
     }
   }
 
-  @_specialize(where Encoding == Unicode.UTF8)
-  @_specialize(where Encoding == Unicode.UTF16)
-  @inlinable // Fold away specializations
+  @inlinable
   @_alwaysEmitIntoClient
   @available(*, deprecated, message: "Use String(_ scalar: Unicode.Scalar)")
   public init<Encoding: Unicode.Encoding>(
     decodingCString nullTerminatedCodeUnits: inout Encoding.CodeUnit,
-    as sourceEncoding: Encoding.Type
+    as encoding: Encoding.Type
   ) {
     guard nullTerminatedCodeUnits == 0 else {
       _preconditionFailure(

test/stdlib/StringAPICStringDiagnostics.swift

@@ -6,7 +6,9 @@ func checkStringOverloadCompilationDiagnostics() {
 
   _ = String(cString: "string") // expected-warning {{'init(cString:)' is deprecated: Use a copy of the String argument}}
 
-  _ = String(validatingCString: "string") // expected-warning {{init(validatingCString:)' is deprecated: Use a copy of the String argument}}
+  _ = String(validatingUTF8: "string") // expected-warning {{init(validatingUTF8:)' is deprecated: Use a copy of the String argument}}
+
+  _ = String(validatingCString: "string") // expected-warning {{'init(validatingCString:)' is deprecated: Use a copy of the String argument}}
 
   _ = String.decodeCString("string", as: Unicode.UTF8.self) // expected-warning {{'decodeCString(_:as:repairingInvalidCodeUnits:)' is deprecated: Use a copy of the String argument}}
 
@@ -23,7 +25,9 @@ func checkInoutConversionOverloadCompilationDiagnostics() {
 
   _ = String(cString: &c) // expected-warning {{'init(cString:)' is deprecated: Use String(_ scalar: Unicode.Scalar)}}
 
-  _ = String(validatingCString: &c) // expected-warning {{init(validatingCString:)' is deprecated: Use String(_ scalar: Unicode.Scalar)}}
+  _ = String(validatingUTF8: &c) // expected-warning {{init(validatingUTF8:)' is deprecated: Use String(_ scalar: Unicode.Scalar)}}
+
+  _ = String(validatingCString: &c) // expected-warning {{'init(validatingCString:)' is deprecated: Use String(_ scalar: Unicode.Scalar)}}
 
   var u = Unicode.UTF8.CodeUnit.zero