Add a new set of initializers to Data to aid efficiency and clarity when wrapping NSData.

addresses:
rdar://problem/26385078 Data() really needs a init(length:) and replaceBytes(in:withBytes:)
rdar://problem/26508250 Add more specific init method to Data to indicate keeping a ref type

Author: parkera

stdlib/public/SDK/Foundation/Data.swift

@@ -128,14 +128,29 @@ public struct Data : ReferenceConvertible, CustomStringConvertible, Equatable, H
     public init(bytes: UnsafePointer<UInt8>, count: Int) {
         _wrapped = _SwiftNSData(immutableObject: NSData(bytes: bytes, length: count))
     }
-    
+
+    /// Initialize a `Data` with copied memory content.
+    ///
+    /// - parameter bytes: A pointer to the memory. It will be copied.
+    /// - parameter count: The number of bytes to copy.
+    public init(bytes: UnsafeMutablePointer<UInt8>, count: Int) {
+        _wrapped = _SwiftNSData(immutableObject: NSData(bytes: UnsafePointer(bytes), length: count))
+    }
+
     /// Initialize a `Data` with copied memory content.
     /// 
     /// - parameter buffer: A buffer pointer to copy. The size is calculated from `SourceType` and `buffer.count`.
     public init<SourceType>(buffer: UnsafeBufferPointer<SourceType>) {
         _wrapped = _SwiftNSData(immutableObject: NSData(bytes: buffer.baseAddress, length: strideof(SourceType) * buffer.count))
     }
-    
+
+    /// Initialize a `Data` with copied memory content.
+    ///
+    /// - parameter buffer: A buffer pointer to copy. The size is calculated from `SourceType` and `buffer.count`.
+    public init<SourceType>(buffer: UnsafeMutableBufferPointer<SourceType>) {
+        _wrapped = _SwiftNSData(immutableObject: NSData(bytes: UnsafePointer(buffer.baseAddress), length: strideof(SourceType) * buffer.count))
+    }
+
     /// Initialize a `Data` with the contents of an Array.
     ///
     /// - parameter bytes: An array of bytes to copy.
@@ -156,15 +171,33 @@ public struct Data : ReferenceConvertible, CustomStringConvertible, Equatable, H
 
     /// Initialize a `Data` with the specified size.
     ///
+    /// This initializer doesn not necessarily allocate the requested memory right away. Mutable data allocates additional memory as needed, so `capacity` simply establishes the initial capacity. When it does allocate the initial memory, though, it allocates the specified amount.
+    ///
+    /// This method sets the `count` of the data to 0.
+    /// 
+    /// If the capacity specified in `capacity` is greater than four memory pages in size, this may round the amount of requested memory up to the nearest full page.
+    ///
     /// - parameter capacity: The size of the data.
     public init?(capacity: Int) {
         if let d = NSMutableData(capacity: capacity) {
-            _wrapped = _SwiftNSData(immutableObject: d)
+            _wrapped = _SwiftNSData(mutableObject: d)
         } else {
             return nil
         }
     }
 
+    /// Initialize a `Data` with the specified count of zeroed bytes.
+    ///
+    /// - parameter count: The number of bytes the data initially contains.
+    public init?(count: Int) {
+        if let d = NSMutableData(length: count) {
+            _wrapped = _SwiftNSData(mutableObject: d)
+        } else {
+            return nil
+        }
+    }
+
+
     /// Initialize an empty `Data`.
     public init() {
         _wrapped = _SwiftNSData(immutableObject: NSData(bytes: nil, length: 0))
@@ -217,9 +250,27 @@ public struct Data : ReferenceConvertible, CustomStringConvertible, Equatable, H
         }
     }
 
-    private init(_bridged data: NSData) {
-        // We must copy the input because it might be mutable; just like storing a value type in ObjC
-        _wrapped = _SwiftNSData(immutableObject: data.copy())
+    /// Initialize a `Data` by adopting a reference type.
+    ///
+    /// You can use this initializer to create a `struct Data` that wraps a `class NSData`. `struct Data` will use the `class NSData` for all operations. Other initializers (including casting using `as Data`) may choose to hold a reference or not, based on a what is the most efficient representation.
+    ///
+    /// If the resulting value is mutated, then `Data` will invoke the `mutableCopy()` function on the reference to copy the contents. You may customize the behavior of that function if you wish to return a specialized mutable subclass.
+    ///
+    /// - parameter reference: The instance of `NSData` that you wish to wrap. This instance will be copied by `struct Data`.
+    public init(reference: NSData) {
+        _wrapped = _SwiftNSData(immutableObject: reference.copy())
+    }
+    
+    /// Initialize a `Data` by adopting a mutable reference type.
+    ///
+    /// You can use this initializer to create a `struct Data` that wraps a `class NSMutableData`. `struct Data` will use the `class NSMutableData` for all operations. Other initializers (including casting using `as Data`) may choose to hold a reference or not, based on a what is the most efficient representation.
+    ///
+    /// If the resulting value is mutated, then `Data` will invoke the `mutableCopy()` function on the reference to copy the contents. You may customize the behavior of that function if you wish to return a specialized mutable subclass.
+    ///
+    /// - warning: For performance reasons, this method does not copy the reference on initialization. It assumes that the reference is uniquely held by the struct. If you continue to mutate the reference after invoking this initializer, you may invalidate the copy-on-write and value semantics of `struct Data`. It is recommended that you do not keep the reference after initializing a `Data` with it.
+    /// - parameter mutableReference: The instance of `NSMutableData` that you wish to wrap.
+    public init(mutableReference: NSMutableData) {
+        _wrapped = _SwiftNSData(mutableObject: mutableReference)
     }
 
     // -----------------------------------
@@ -428,6 +479,9 @@ public struct Data : ReferenceConvertible, CustomStringConvertible, Equatable, H
 
     /// Replace a region of bytes in the data with new data.
     ///
+    /// This will resize the data if required, to fit the entire contents of `data`.
+    ///
+    /// - precondition: `range` must be within the range of the data.
     /// - parameter range: The range in the data to replace.
     /// - parameter data: The replacement data.
     public mutating func replaceBytes(in range: Range<Index>, with data: Data) {
@@ -439,7 +493,23 @@ public struct Data : ReferenceConvertible, CustomStringConvertible, Equatable, H
             $0.replaceBytes(in: nsRange, withBytes: bytes, length: cnt)
         }
     }
+    
+    /// Replace a region of bytes in the data with new bytes from a buffer.
+    ///
+    /// This will resize the data if required, to fit the entire contents of `buffer`.
+    ///
+    /// - precondition: `range` must be within the range of the data.
+    /// - parameter buffer: The replacement bytes.
+    public mutating func replaceBytes<SourceType>(in range: Range<Index>, with buffer: UnsafeBufferPointer<SourceType>) {
+        let nsRange = NSMakeRange(range.lowerBound, range.upperBound - range.lowerBound)
+        let bufferCount = buffer.count * strideof(SourceType)
+        
+        _applyUnmanagedMutation {
+            $0.replaceBytes(in: nsRange, withBytes: buffer.baseAddress, length: bufferCount)
+        }
 
+    }
+    
     /// Return a new copy of the data in a specified range.
     ///
     /// - parameter range: The range to copy.
@@ -506,7 +576,7 @@ public struct Data : ReferenceConvertible, CustomStringConvertible, Equatable, H
         }
     }
 
-    public subscript(bounds: Range<Int>) -> MutableRandomAccessSlice<Data> {
+    public subscript(bounds: Range<Index>) -> MutableRandomAccessSlice<Data> {
         get {
             return MutableRandomAccessSlice(base: self, bounds: bounds)
         }
@@ -568,11 +638,13 @@ extension Data : _ObjectiveCBridgeable {
     }
 
     public static func _forceBridgeFromObjectiveC(_ input: NSData, result: inout Data?) {
-        result = Data(_bridged: input)
+        // We must copy the input because it might be mutable; just like storing a value type in ObjC
+        result = Data(reference: input)
     }
 
     public static func _conditionallyBridgeFromObjectiveC(_ input: NSData, result: inout Data?) -> Bool {
-        result = Data(_bridged: input)
+        // We must copy the input because it might be mutable; just like storing a value type in ObjC
+        result = Data(reference: input)
         return true
     }
 

test/1_stdlib/TestData.swift

@@ -190,7 +190,7 @@ class TestData : TestDataSuper {
 
     func testCustomData() {
         let length = 5
-        let allOnesData = AllOnesData(length: length) as Data
+        let allOnesData = Data(reference: AllOnesData(length: length))
         expectEqual(1, allOnesData[0], "First byte of all 1s data should be 1")
 
         // Double the length
@@ -246,7 +246,7 @@ class TestData : TestDataSuper {
         let allOnes = AllOnesData(length: 64)
 
         // Type-erased
-        let data = allOnes as Data
+        let data = Data(reference: allOnes)
 
         // Create a home for our test data
         let dirPath = (NSTemporaryDirectory() as NSString).appendingPathComponent(NSUUID().uuidString)
@@ -291,7 +291,7 @@ class TestData : TestDataSuper {
         expectEqual(s.count, 2, "Expected only two entries in the Set")
     }
 
-    func testSubsequences() {
+    func testReplaceBytes() {
         var hello = dataFrom("Hello")
         let world = dataFrom("World")
 
@@ -306,7 +306,7 @@ class TestData : TestDataSuper {
         expectEqual(goodbyeWorld, expected)
     }
 
-    func testSubsequences2() {
+    func testReplaceBytes2() {
         let hello = dataFrom("Hello")
         let world = dataFrom(" World")
         let goodbye = dataFrom("Goodbye")
@@ -320,8 +320,29 @@ class TestData : TestDataSuper {
         }
         expectEqual(mutateMe, expected)
     }
+    
+    func testReplaceBytes3() {
+        // The expected result
+        let expectedBytes : [UInt8] = [1, 2, 9, 10, 11, 12, 13]
+        let expected = expectedBytes.withUnsafeBufferPointer {
+            return Data(buffer: $0)
+        }
+        
+        // The data we'll mutate
+        let someBytes : [UInt8] = [1, 2, 3, 4, 5]
+        var a = someBytes.withUnsafeBufferPointer {
+            return Data(buffer: $0)
+        }
+        
+        // The bytes we'll insert
+        let b : [UInt8] = [9, 10, 11, 12, 13]
+        b.withUnsafeBufferPointer {
+            a.replaceBytes(in: 2..<5, with: $0)
+        }
+        expectEqual(expected, a)
+    }
 
-    func testSubsequences3() {
+    func testRange() {
         let helloWorld = dataFrom("Hello World")
         let goodbye = dataFrom("Goodbye")
         let hello = dataFrom("Hello")
@@ -774,9 +795,10 @@ DataTests.test("testBridgingMutable") { TestData().testBridgingMutable() }
 DataTests.test("testBridgingCustom") { TestData().testBridgingCustom() }
 DataTests.test("testEquality") { TestData().testEquality() }
 DataTests.test("testDataInSet") { TestData().testDataInSet() }
-DataTests.test("testSubsequences") { TestData().testSubsequences() }
-DataTests.test("testSubsequences2") { TestData().testSubsequences2() }
-DataTests.test("testSubsequences3") { TestData().testSubsequences3() }
+DataTests.test("testReplaceBytes") { TestData().testReplaceBytes() }
+DataTests.test("testReplaceBytes2") { TestData().testReplaceBytes2() }
+DataTests.test("testReplaceBytes3") { TestData().testReplaceBytes3() }
+DataTests.test("testRange") { TestData().testRange() }
 DataTests.test("testInsertData") { TestData().testInsertData() }
 DataTests.test("testLoops") { TestData().testLoops() }
 DataTests.test("testGenericAlgorithms") { TestData().testGenericAlgorithms() }
@@ -811,6 +833,26 @@ DataTests.test("bounding failure replace") {
     data.replaceBytes(in: 5..<200, with: Data())
 }
 
+DataTests.test("bounding failure replace2") {
+    var data = "a".data(using: .utf8)!
+    var bytes : [UInt8] = [1, 2, 3]
+    expectCrashLater()
+    bytes.withUnsafeBufferPointer {
+        // lowerBound ok, upperBound after end of data
+        data.replaceBytes(in: 0..<2, with: $0)
+    }
+}
+
+DataTests.test("bounding failure replace3") {
+    var data = "a".data(using: .utf8)!
+    var bytes : [UInt8] = [1, 2, 3]
+    expectCrashLater()
+    bytes.withUnsafeBufferPointer {
+        // lowerBound is > length
+        data.replaceBytes(in: 2..<4, with: $0)
+    }
+}
+
 DataTests.test("bounding failure reset range") {
     var data = "Hello World".data(using: .utf8)!
     expectCrashLater()