String's NSString API: Replace factory methods with failable initializers.

DougGregor · DougGregor · commit eaefb5e2b063 · 2014-09-04T17:21:33.000Z
Addresses rdar://problem/18225788.


Swift SVN r21710
diff --git a/apinotes/Foundation.apinotes b/apinotes/Foundation.apinotes
@@ -8377,7 +8377,7 @@ Classes:
     Nullability:
     - S
     - S
-    NullabilityOfRet: N
+    NullabilityOfRet: O
   - Selector: 'initWithData:encoding:'
     MethodKind: Instance
     Nullability:
@@ -8406,7 +8406,7 @@ Classes:
     MethodKind: Instance
     Nullability:
     - S
-    NullabilityOfRet: N
+    NullabilityOfRet: O
   - Selector: 'isEqualToString:'
     MethodKind: Instance
     Nullability:
diff --git a/stdlib/objc/Foundation/NSStringAPI.swift b/stdlib/objc/Foundation/NSStringAPI.swift
@@ -192,75 +192,96 @@ extension String {
   //     encoding:(NSStringEncoding)enc
   //     error:(NSError **)error
 
-  /// Returns a string created by reading data from the file at a
+  /// Produces a string created by reading data from the file at a
   /// given path interpreted using a given encoding.
-  public static func stringWithContentsOfFile(
-    path: String,
+  public init?(
+    contentsOfFile path: String,
     encoding enc: NSStringEncoding,
     error: NSErrorPointer = nil
-  ) -> String? {
-    return NSString(contentsOfFile: path, encoding: enc, error: error)
+  ) {
+    if let ns = NSString(contentsOfFile: path, encoding: enc, error: error) {
+      self = ns as String
+    } else {
+      return nil
+    }
   }
 
   // + (instancetype)
   //     stringWithContentsOfFile:(NSString *)path
   //     usedEncoding:(NSStringEncoding *)
   //     enc error:(NSError **)error
 
-  /// Returns a string created by reading data from the file at
+  /// Produces a string created by reading data from the file at
   /// a given path and returns by reference the encoding used to
   /// interpret the file.
-  public static func stringWithContentsOfFile(
-    path: String,
+  public init?(
+    contentsOfFile path: String,
     usedEncoding: UnsafeMutablePointer<NSStringEncoding> = nil,
     error: NSErrorPointer = nil
-  ) -> String? {
-    return NSString(contentsOfFile: path, usedEncoding: usedEncoding,
-                                             error: error)
+  ) {
+    if let ns = NSString(contentsOfFile: path, usedEncoding: usedEncoding,
+                          error: error) {
+      self = ns as String
+    } else {
+      return nil
+    }
   }
 
   // + (instancetype)
   //     stringWithContentsOfURL:(NSURL *)url
   //     encoding:(NSStringEncoding)enc
   //     error:(NSError **)error
 
-  /// Returns a string created by reading data from a given URL
+  /// Produces a string created by reading data from a given URL
   /// interpreted using a given encoding.  Errors are written into the
   /// inout `error` argument.
-  public static func stringWithContentsOfURL(
-    url: NSURL, encoding enc: NSStringEncoding, error: NSErrorPointer = nil
-  ) -> String? {
-    return NSString(contentsOfURL: url, encoding: enc, error: error)
+  public init?(
+    contentsOfURL url: NSURL, 
+    encoding enc: NSStringEncoding, 
+    error: NSErrorPointer = nil
+  ) {
+    if let ns = NSString(contentsOfURL: url, encoding: enc, error: error) {
+      self = ns as String
+    } else {
+      return nil
+    }
   }
 
   // + (instancetype)
   //     stringWithContentsOfURL:(NSURL *)url
   //     usedEncoding:(NSStringEncoding *)enc
   //     error:(NSError **)error
 
-  /// Returns a string created by reading data from a given URL
+  /// Produces a string created by reading data from a given URL
   /// and returns by reference the encoding used to interpret the
   /// data.  Errors are written into the inout `error` argument.
-  public static func stringWithContentsOfURL(
-    url: NSURL,
+  public init?(
+    contentsOfURL url: NSURL,
     usedEncoding enc: UnsafeMutablePointer<NSStringEncoding> = nil,
     error: NSErrorPointer = nil
-  ) -> String? {
-    return NSString(contentsOfURL: url, usedEncoding: enc,
-                                            error: error)
+  ) {
+    if let ns = NSString(contentsOfURL: url, usedEncoding: enc, error: error) {
+      self = ns as String
+    } else {
+      return nil
+    }
   }
 
   // + (instancetype)
   //     stringWithCString:(const char *)cString
   //     encoding:(NSStringEncoding)enc
 
-  /// Returns a string containing the bytes in a given C array,
+  /// Produces a string containing the bytes in a given C array,
   /// interpreted according to a given encoding.
-  public static func stringWithCString(
-    cString: UnsafePointer<CChar>,
+  public init?(
+    CString: UnsafePointer<CChar>,
     encoding enc: NSStringEncoding
-  ) -> String? {
-    return NSString(CString: cString, encoding: enc)
+  ) {
+    if let ns = NSString(CString: CString, encoding: enc) {
+      self = ns as String
+    } else {
+      return nil 
+    }
   }
 
 
@@ -270,12 +291,14 @@ extension String {
   
   // + (instancetype)stringWithUTF8String:(const char *)bytes
 
-  /// Returns a string created by copying the data from a given
+  /// Produces a string created by copying the data from a given
   /// C array of UTF8-encoded bytes.
-  public static func stringWithUTF8String(
-    bytes: UnsafePointer<CChar>
-  ) -> String? {
-    return NSString(UTF8String: bytes)
+  public init?(UTF8String bytes: UnsafePointer<CChar>) {
+    if let ns = NSString(UTF8String: bytes) {
+      self = ns as String
+    } else {
+      return nil
+    }
   }
 
   //===--- Instance Methods/Properties-------------------------------------===//
@@ -729,17 +752,21 @@ extension String {
   //     length:(NSUInteger)length
   //     encoding:(NSStringEncoding)encoding
 
-  /// Returns an initialized `NSString` object equivalent to the given
+  /// Produces an initialized `NSString` object equivalent to the given
   /// `bytes` interpreted in the given `encoding`.
-  public static func stringWithBytes<
+  public init? <
     S: SequenceType where S.Generator.Element == UInt8
   >(
     bytes: S, encoding: NSStringEncoding
-  ) -> String? {
+  ) {
     let byteArray = Array(bytes)
-    return NSString(
-      bytes: byteArray, length: byteArray.count, encoding: encoding
-    ) as NSString? // HACK: FIXME: coerce to optional NSString to handle nil
+    if let ns = NSString(
+                  bytes: byteArray, length: byteArray.count, encoding: encoding
+                ) {
+      self = ns as String
+    } else {
+      return nil
+    }
   }
 
   // - (instancetype)
@@ -748,18 +775,22 @@ extension String {
   //     encoding:(NSStringEncoding)encoding
   //     freeWhenDone:(BOOL)flag
 
-  /// Returns an initialized `String` object that contains a
+  /// Produces an initialized `String` object that contains a
   /// given number of bytes from a given buffer of bytes interpreted
   /// in a given encoding, and optionally frees the buffer.  WARNING:
-  /// this method is not memory-safe!
-  public static func stringWithBytesNoCopy(
-    bytes: UnsafeMutablePointer<Void>, length: Int,
+  /// this initializer is not memory-safe!
+  public init?(
+    bytesNoCopy bytes: UnsafeMutablePointer<Void>, length: Int,
     encoding: NSStringEncoding, freeWhenDone flag: Bool
-  ) -> String? {
-    return NSString(
-      bytesNoCopy: bytes, length: length,
-      encoding: encoding, freeWhenDone: flag
-    ) as NSString? // Important: coerce to optional NSString to handle nil
+  ) {
+    if let ns = NSString(
+                  bytesNoCopy: bytes, length: length,
+                  encoding: encoding, freeWhenDone: flag
+                ) {
+      self = ns as String
+    } else {
+      return nil
+    }
   }
 
 
diff --git a/test/stdlib/NSStringAPI.swift b/test/stdlib/NSStringAPI.swift
@@ -89,7 +89,7 @@ NSStringAPIs.test("stringWithContentsOfFile(_:encoding:error:)") {
   let (existingPath, nonExistentPath) = createNSStringTemporaryFile()
   if true {
     var err: NSError?
-    let content = String.stringWithContentsOfFile(existingPath,
+    let content = String(contentsOfFile: existingPath,
         encoding: NSASCIIStringEncoding, error: &err)
 
     expectEmpty(err)
@@ -99,7 +99,7 @@ NSStringAPIs.test("stringWithContentsOfFile(_:encoding:error:)") {
   }
   if true {
     var err: NSError?
-    let content = String.stringWithContentsOfFile(nonExistentPath,
+    let content = String(contentsOfFile: nonExistentPath,
         encoding: NSASCIIStringEncoding, error: &err)
 
     expectNotEmpty(err)
@@ -112,7 +112,7 @@ NSStringAPIs.test("stringWithContentsOfFile(_:usedEncoding:error:)") {
   if true {
     var usedEncoding: NSStringEncoding = 0
     var err: NSError?
-    var content = String.stringWithContentsOfFile(existingPath,
+    var content = String(contentsOfFile: existingPath,
         usedEncoding: &usedEncoding, error: &err)
 
     expectNotEqual(0, usedEncoding)
@@ -124,7 +124,7 @@ NSStringAPIs.test("stringWithContentsOfFile(_:usedEncoding:error:)") {
   if true {
     var usedEncoding: NSStringEncoding = 0
     var err: NSError?
-    var content = String.stringWithContentsOfFile(nonExistentPath, error: &err)
+    var content = String(contentsOfFile: nonExistentPath, error: &err)
 
     expectEqual(0, usedEncoding)
     expectNotEmpty(err)
@@ -139,7 +139,7 @@ NSStringAPIs.test("stringWithContentsOfURL(_:encoding:error:)") {
   let nonExistentURL = NSURL(string: "file://" + nonExistentPath)!
   if true {
     var err: NSError?
-    var content = String.stringWithContentsOfURL(existingURL,
+    var content = String(contentsOfURL: existingURL,
         encoding: NSASCIIStringEncoding, error: &err)
 
     expectEmpty(err)
@@ -149,7 +149,7 @@ NSStringAPIs.test("stringWithContentsOfURL(_:encoding:error:)") {
   }
   if true {
     var err: NSError?
-    var content = String.stringWithContentsOfURL(nonExistentURL,
+    var content = String(contentsOfURL: nonExistentURL,
         encoding: NSASCIIStringEncoding, error: &err)
 
     expectNotEmpty(err)
@@ -164,7 +164,7 @@ NSStringAPIs.test("stringWithContentsOfURL(_:usedEncoding:error:)") {
   if true {
     var usedEncoding: NSStringEncoding = 0
     var err: NSError?
-    var content = String.stringWithContentsOfURL(existingURL,
+    var content = String(contentsOfURL: existingURL,
         usedEncoding: &usedEncoding, error: &err)
 
     expectNotEqual(0, usedEncoding)
@@ -176,7 +176,7 @@ NSStringAPIs.test("stringWithContentsOfURL(_:usedEncoding:error:)") {
   if true {
     var usedEncoding: NSStringEncoding = 0
     var err: NSError?
-    var content = String.stringWithContentsOfURL(nonExistentURL,
+    var content = String(contentsOfURL: nonExistentURL,
         usedEncoding: &usedEncoding, error: &err)
 
     expectEqual(0, usedEncoding)
@@ -187,11 +187,11 @@ NSStringAPIs.test("stringWithContentsOfURL(_:usedEncoding:error:)") {
 
 NSStringAPIs.test("stringWithCString(_:encoding:)") {
   expectOptionalEqual("foo, a basmati bar!",
-      String.stringWithCString(
+      String(CString: 
           "foo, a basmati bar!", encoding: String.defaultCStringEncoding()))
 }
 
-NSStringAPIs.test("stringWithUTF8String(_:)") {
+NSStringAPIs.test("init(UTF8String:)") {
   var s = "foo あいう"
   var up = UnsafeMutablePointer<UInt8>.alloc(100)
   var i = 0
@@ -200,7 +200,7 @@ NSStringAPIs.test("stringWithUTF8String(_:)") {
     i++
   }
   up[i] = 0
-  expectOptionalEqual(s, String.stringWithUTF8String(UnsafePointer(up)))
+  expectOptionalEqual(s, String(UTF8String: UnsafePointer(up)))
   up.dealloc(100)
 }
 
@@ -708,10 +708,10 @@ NSStringAPIs.test("hash") {
   expectEqual(nsstr.hash, s.hash)
 }
 
-NSStringAPIs.test("stringWithBytes(_:encoding:)") {
+NSStringAPIs.test("init(bytes:encoding:)") {
   var s: String = "abc あかさた"
   expectOptionalEqual(
-    s, String.stringWithBytes(s.utf8, encoding: NSUTF8StringEncoding))
+    s, String(bytes: s.utf8, encoding: NSUTF8StringEncoding))
 
   /*
   FIXME: Test disabled because the NSString documentation is unclear about
@@ -724,10 +724,10 @@ NSStringAPIs.test("stringWithBytes(_:encoding:)") {
   // FIXME: add a test where this function actually returns nil.
 }
 
-NSStringAPIs.test("stringWithBytesNoCopy(_:length:encoding:freeWhenDone:)") {
+NSStringAPIs.test("init(bytesNoCopy:length:encoding:freeWhenDone:)") {
   var s: String = "abc あかさた"
   var bytes: [UInt8] = Array(s.utf8)
-  expectOptionalEqual(s, String.stringWithBytesNoCopy(&bytes,
+  expectOptionalEqual(s, String(bytesNoCopy: &bytes,
       length: bytes.count, encoding: NSUTF8StringEncoding,
       freeWhenDone: false))
 
@@ -1532,7 +1532,7 @@ NSStringAPIs.test("writeToFile(_:atomically:encoding:error:)") {
     expectTrue(result)
 
     expectOptionalEqual(
-      s, String.stringWithContentsOfFile(
+      s, String(contentsOfFile: 
         nonExistentPath, encoding: NSASCIIStringEncoding))
   }
 }
@@ -1550,7 +1550,7 @@ NSStringAPIs.test("writeToURL(_:atomically:encoding:error:)") {
     expectTrue(result)
 
     expectOptionalEqual(
-      s, String.stringWithContentsOfFile(
+      s, String(contentsOfFile: 
         nonExistentPath, encoding: NSASCIIStringEncoding))
   }
 }
diff --git a/test/stdlib/NewString.swift b/test/stdlib/NewString.swift
@@ -76,7 +76,7 @@ func nonASCII() {
   // Cocoa stores non-ASCII in a UTF-16 buffer
   // Code units in each character: 2 1 1 1 2 2 2
   // Offset of each character:     0 2 3 4 5 7 9 11
-  var nsUTF16 = NSString(UTF8String: "🏂☃❅❆❄︎⛄️❄️")
+  var nsUTF16 = NSString(UTF8String: "🏂☃❅❆❄︎⛄️❄️")!
   // CHECK-NEXT: has UTF-16: true
   println("has UTF-16: \(CFStringGetCharactersPtr(unsafeBitCast(nsUTF16, CFString.self)) != nil)")
 
@@ -122,7 +122,7 @@ func ascii() {
   // Cocoa stores ASCII in a buffer of bytes.  This is an important case
   // because it doesn't provide a contiguous array of UTF-16, so we'll be
   // treating it as an opaque NSString.
-  var nsASCII = NSString(UTF8String: "foobar")
+  var nsASCII = NSString(UTF8String: "foobar")!
   // CHECK-NEXT: has UTF-16: false
   println("has UTF-16: \(CFStringGetCharactersPtr(unsafeBitCast(nsASCII, CFString.self)) != nil)")
 
