[stdlib] [WIP] Add UnsafeRawBufferPointer.initialize(as:from:)

stdlib/public/core/UnsafeRawBufferPointer.swift.gyb

@@ -348,6 +348,60 @@ public struct Unsafe${Mutable}RawBufferPointer
     return 0
   }
 
+  %  if mutable:
+  /// Initializes memory in the buffer with the elements of
+  /// `source` and binds the initialized memory to type `T`.
+  ///
+  /// Returns an iterator to any elements of `source` that didn't fit in the 
+  /// buffer, and an index into the buffer one past the last byte written.
+  ///
+  /// - Precondition: The memory in `startIndex..<(source.count *
+  ///   MemoryLayout<T>.stride)` is uninitialized or initialized to a
+  ///   trivial type.
+  ///
+  /// - Precondition: The buffer must contain sufficient memory to
+  ///   accommodate at least `source.underestimateCount` elements.
+  ///
+  /// - Postcondition: The memory at `self[startIndex..<returned index]                 
+  ///   is bound to type `T`.
+  ///
+  /// - Postcondition: The `T` values at `self[startIndex..<returned index]`
+  ///   are initialized.
+  ///
+  // TODO: Optimize where `C` is a `ContiguousArrayBuffer`.
+  public func initializeMemory<S: Sequence>(
+    as: S.Iterator.Element.Type, from source: S
+  ) -> (unwritten: S.Iterator, initializedUpTo: Index) {
+
+    var it = source.makeIterator()
+    var idx = startIndex
+    let elementStride = MemoryLayout<S.Iterator.Element>.stride
+
+    // This has to be a debug precondition due to the cost of walking over some collections.
+    _debugPrecondition(source.underestimatedCount <= (count / elementStride),
+      "insufficient space to accommodate source.underestimatedCount elements")
+    guard let base = baseAddress else {
+      // this can be a precondition since only an invalid argument should be costly
+      _precondition(source.underestimatedCount == 0, "no memory available to initialize from source")
+      return (it, startIndex)
+    }  
+
+    for p in stride(from: base, 
+      // only advance to as far as the last element that will fit
+      to: base + count - elementStride + 1, 
+      by: elementStride
+    ) {
+      // underflow is permitted – e.g. a sequence into
+      // the spare capacity of an Array buffer
+      guard let x = it.next() else { break }
+      p.initializeMemory(as: S.Iterator.Element.self, to: x)
+      formIndex(&idx, offsetBy: elementStride)
+    }
+
+    return (it, idx)
+  }
+  %  end # mutable
+
   let _position, _end: Unsafe${Mutable}RawPointer?
 }
 

stdlib/public/core/UnsafeRawPointer.swift.gyb

@@ -294,7 +294,8 @@ public struct Unsafe${Mutable}RawPointer : Strideable, Hashable, _Pointer {
   /// - Postcondition: The `T` values at `self..<self + source.count *
   ///   MemoryLayout<T>.stride` are initialized.
   ///
-  /// TODO: Optimize where `C` is a `ContiguousArrayBuffer`.
+  // This is fundamentally unsafe since collections can underreport their count.
+  @available(*, deprecated, message: "it will be removed in Swift 4.0.  Please use 'UnsafeMutableRawBufferPointer.initialize(from:)' instead")
   @discardableResult
   public func initializeMemory<C : Collection>(
     as: C.Iterator.Element.Type, from source: C

test/stdlib/UnsafeRawBufferPointer.swift

@@ -75,6 +75,59 @@ UnsafeRawBufferPointerTestSuite.test("initFromArray") {
   expectEqual(array2, array1)
 }
 
+UnsafeRawBufferPointerTestSuite.test("initializeMemory(as:from:).underflow") {
+  let buffer = UnsafeMutableRawBufferPointer.allocate(count: 30)
+  defer { buffer.deallocate() }
+  let source = stride(from: 5 as Int64, to: 0, by: -1)
+  var (it,idx) = buffer.initializeMemory(as: Int64.self, from: source)
+  expectEqual(it.next()!, 2)
+  expectEqual(idx, 24)
+  ([5, 4, 3] as [Int64]).withUnsafeBytes {
+    expectEqualSequence($0,buffer[0..<idx])
+  }
+}
+
+UnsafeRawBufferPointerTestSuite.test("initializeMemory(as:from:).overflow") {
+  let buffer = UnsafeMutableRawBufferPointer.allocate(count: 30)
+  defer { buffer.deallocate() }
+  let source: [Int64] = [5, 4, 3, 2, 1]
+  if _isDebugAssertConfiguration() {
+    expectCrashLater()
+  }
+  var (it, idx) = buffer.initializeMemory(as: Int64.self, from: source)
+  expectEqual(it.next()!, 2)
+  expectEqual(idx, 24)
+  ([5, 4, 3] as [Int64]).withUnsafeBytes {
+    expectEqualSequence($0,buffer[0..<idx])
+  }
+}
+
+UnsafeRawBufferPointerTestSuite.test("initializeMemory(as:from:).exact") {
+  let buffer = UnsafeMutableRawBufferPointer.allocate(count: 24)
+  defer { buffer.deallocate() }
+  let source: [Int64] = [5, 4, 3]
+  var (it, idx) = buffer.initializeMemory(as: Int64.self, from: source)
+  expectNil(it.next())
+  expectEqual(idx, buffer.endIndex)
+  source.withUnsafeBytes { expectEqualSequence($0,buffer) }
+}
+
+UnsafeRawBufferPointerTestSuite.test("initializeMemory(as:from:).invalidNilPtr") {
+  let buffer = UnsafeMutableRawBufferPointer(start: nil, count: 0)
+  let source: [Int64] = [5, 4, 3, 2, 1]
+  expectCrashLater()
+  var (it, idx) = buffer.initializeMemory(as: Int64.self, from: source)
+}
+
+UnsafeRawBufferPointerTestSuite.test("initializeMemory(as:from:).validNilPtr") {
+  let buffer = UnsafeMutableRawBufferPointer(start: nil, count: 0)
+  let source: [Int64] = []
+  var (it, idx) = buffer.initializeMemory(as: Int64.self, from: source)
+  expectNil(it.next())
+  expectEqual(idx, source.endIndex)
+}
+
+
 // Directly test the byte Sequence produced by withUnsafeBytes.
 UnsafeRawBufferPointerTestSuite.test("withUnsafeBytes.Sequence") {
   let array1: [Int32] = [0, 1, 2, 3]