[se-0405] rename String.init?(validatingUTF8:)

Author: glessard

stdlib/public/core/CString.swift

@@ -124,6 +124,39 @@ extension String {
     self = ""
   }
 
+  /// Creates a new string by copying and validating the null-terminated UTF-8
+  /// data referenced by the given pointer.
+  ///
+  /// 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`.
+  ///
+  /// The following example calls this initializer with pointers to the
+  /// contents of two different `CChar` arrays---the first with well-formed
+  /// UTF-8 code unit sequences and the second with an ill-formed sequence at
+  /// the end.
+  ///
+  ///     let validUTF8: [CChar] = [67, 97, 102, -61, -87, 0]
+  ///     validUTF8.withUnsafeBufferPointer { ptr in
+  ///         let s = String(validatingCString: ptr.baseAddress!)
+  ///         print(s)
+  ///     }
+  ///     // Prints "Optional("Café")"
+  ///
+  ///     let invalidUTF8: [CChar] = [67, 97, 102, -61, 0]
+  ///     invalidUTF8.withUnsafeBufferPointer { ptr in
+  ///         let s = String(validatingCString: ptr.baseAddress!)
+  ///         print(s)
+  ///     }
+  ///     // Prints "nil"
+  ///
+  /// - Parameter nullTerminatedUTF8:
+  ///       A pointer to a null-terminated UTF-8 code sequence.
+  @inlinable
+  @_alwaysEmitIntoClient
+  public init?(validatingCString nullTerminatedUTF8: UnsafePointer<CChar>) {
+    self.init(validatingUTF8: nullTerminatedUTF8)
+  }
+
   /// Creates a new string by copying and validating the null-terminated UTF-8
   /// data referenced by the given pointer.
   ///
@@ -149,7 +182,11 @@ extension String {
   ///     }
   ///     // Prints "nil"
   ///
+  /// Note: This initializer is deprecated. Use
+  ///       `String.init?(validatingCString:)` instead.
+  ///
   /// - Parameter cString: A pointer to a null-terminated UTF-8 code sequence.
+  @available(*, deprecated, renamed: "String.init(validatingCString:)")
   public init?(validatingUTF8 cString: UnsafePointer<CChar>) {
     let len = UTF8._nullCodeUnitOffset(in: cString)
     guard let str = cString.withMemoryRebound(to: UInt8.self, capacity: len, {
@@ -162,39 +199,59 @@ extension String {
 
   @inlinable
   @_alwaysEmitIntoClient
-  public init?(validatingUTF8 cString: [CChar]) {
-    guard let length = cString.firstIndex(of: 0) else {
+  public init?(validatingCString nullTerminatedUTF8: [CChar]) {
+    guard let length = nullTerminatedUTF8.firstIndex(of: 0) else {
       _preconditionFailure(
-        "input of String.init(validatingUTF8:) must be null-terminated"
+        "input of String.init(validatingCString:) must be null-terminated"
       )
     }
-    guard let string = cString.prefix(length).withUnsafeBufferPointer({
+    let string = nullTerminatedUTF8.prefix(length).withUnsafeBufferPointer {
       $0.withMemoryRebound(to: UInt8.self, String._tryFromUTF8(_:))
-    })
-    else { return nil }
-
+    }
+    guard let string else { return nil }
     self = string
   }
 
+  @inlinable
+  @_alwaysEmitIntoClient
+  @available(*, deprecated, renamed: "String.init(validatingCString:)")
+  public init?(validatingUTF8 cString: [CChar]) {
+    self.init(validatingCString: cString)
+  }
+
+  @inlinable
+  @_alwaysEmitIntoClient
+  @available(*, deprecated, message: "Use a copy of the String argument")
+  public init?(validatingCString nullTerminatedUTF8: String) {
+    self = nullTerminatedUTF8.withCString(String.init(cString:))
+  }
+
   @inlinable
   @_alwaysEmitIntoClient
   @available(*, deprecated, message: "Use a copy of the String argument")
   public init?(validatingUTF8 cString: String) {
-    self = cString.withCString(String.init(cString:))
+    self.init(validatingCString: cString)
   }
 
   @inlinable
   @_alwaysEmitIntoClient
   @available(*, deprecated, message: "Use String(_ scalar: Unicode.Scalar)")
-  public init?(validatingUTF8 cString: inout CChar) {
-    guard cString == 0 else {
+  public init?(validatingCString nullTerminatedUTF8: inout CChar) {
+    guard nullTerminatedUTF8 == 0 else {
       _preconditionFailure(
         "input of String.init(validatingUTF8:) must be null-terminated"
       )
     }
     self = ""
   }
 
+  @inlinable
+  @_alwaysEmitIntoClient
+  @available(*, deprecated, message: "Use String(_ scalar: Unicode.Scalar)")
+  public init?(validatingUTF8 cString: inout CChar) {
+    self.init(validatingCString: &cString)
+  }
+
   /// Creates a new string by copying the null-terminated data referenced by
   /// the given pointer using the specified encoding.
   ///