[se-0370] add notes regarding overlapping memory regions

Author: glessard

stdlib/public/core/UnsafeBufferPointer.swift.gyb

@@ -702,6 +702,9 @@ extension Unsafe${Mutable}BufferPointer {
   ///
   /// - Precondition: `self.count` >= `source.count`
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer
+  ///     must not overlap.
+  ///
   /// - Parameter source: A collection of elements to be used to
   ///     initialize the buffer's storage.
   /// - Returns: The index one past the last element of the buffer initialized
@@ -801,6 +804,9 @@ extension Unsafe${Mutable}BufferPointer {
   /// buffer's `startIndex`. If `source` contains as many elements as the buffer
   /// can hold, the returned index is equal to the buffer's `endIndex`.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer
+  ///     may overlap.
+  ///
   /// - Precondition: `self.count` >= `source.count`
   ///
   /// - Parameter source: A collection of elements to be used to update
@@ -870,9 +876,11 @@ extension Unsafe${Mutable}BufferPointer {
   ///
   /// - Precondition: `self.count` >= `source.count`
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer
+  ///     may overlap.
+  ///
   /// - Parameter source: A buffer containing the values to copy. The memory
-  ///     region underlying `source` must be initialized. The memory regions
-  ///     referenced by `source` and this buffer may overlap.
+  ///     region underlying `source` must be initialized.
   /// - Returns: The index one past the last element of the buffer initialized
   ///     by this function.
   @inlinable
@@ -910,9 +918,11 @@ extension Unsafe${Mutable}BufferPointer {
   ///
   /// - Precondition: `self.count` >= `source.count`
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer
+  ///     may overlap.
+  ///
   /// - Parameter source: A buffer containing the values to copy. The memory
-  ///     region underlying `source` must be initialized. The memory regions
-  ///     referenced by `source` and this buffer may overlap.
+  ///     region underlying `source` must be initialized.
   /// - Returns: The index one past the last element of the buffer initialized
   ///     by this function.
   @inlinable
@@ -937,11 +947,13 @@ extension Unsafe${Mutable}BufferPointer {
   /// buffer's `startIndex`. If `source` contains as many elements as the buffer
   /// can hold, the returned index is equal to the buffer's `endIndex`.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer
+  ///     must not overlap.
+  ///
   /// - Precondition: `self.count` >= `source.count`
   ///
   /// - Parameter source: A buffer containing the values to move.
-  ///     The memory region underlying `source` must be initialized. The memory
-  ///     regions referenced by `source` and this buffer must not overlap.
+  ///     The memory region underlying `source` must be initialized.
   /// - Returns: An index one past the index of the last element updated.
   @inlinable
   @_alwaysEmitIntoClient
@@ -973,11 +985,13 @@ extension Unsafe${Mutable}BufferPointer {
   /// buffer's `startIndex`. If `source` contains as many elements as the buffer
   /// can hold, the returned index is equal to the buffer's `endIndex`.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer
+  ///     must not overlap.
+  ///
   /// - Precondition: `self.count` >= `source.count`
   ///
   /// - Parameter source: A buffer slice containing the values to move.
-  ///   The memory region underlying `source` must be initialized. The
-  ///   memory regions referenced by `source` and this pointer must not overlap.
+  ///     The memory region underlying `source` must be initialized.
   /// - Returns: An index one past the index of the last element updated.
   @inlinable
   @_alwaysEmitIntoClient

stdlib/public/core/UnsafeBufferPointerSlice.swift

@@ -752,6 +752,9 @@ extension Slice {
   ///
   /// - Precondition: `self.count` >= `source.count`
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer slice
+  ///     must not overlap.
+  ///
   /// - Parameter source: A collection of elements to be used to
   ///     initialize the buffer slice's storage.
   /// - Returns: The index one past the last element of the buffer slice
@@ -818,6 +821,9 @@ extension Slice {
   /// `startIndex`. If `source` contains as many elements as the buffer slice
   /// can hold, the returned index is the buffer slice's `endIndex`.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer slice
+  ///     may overlap.
+  ///
   /// - Precondition: `self.count` >= `source.count`
   ///
   /// - Parameter source: A collection of elements to be used to update
@@ -853,11 +859,13 @@ extension Slice {
   /// slice's `startIndex`. If `source` contains as many elements as the slice
   /// can hold, the returned index is equal to the slice's `endIndex`.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer slice
+  ///     may overlap.
+  ///
   /// - Precondition: `self.count` >= `source.count`
   ///
   /// - Parameter source: A buffer containing the values to copy.
-  ///     The memory region underlying `source` must be initialized. The memory
-  ///     regions referenced by `source` and this buffer may overlap.
+  ///     The memory region underlying `source` must be initialized.
   /// - Returns: The index one past the last element of the buffer slice
   ///    initialized by this function.
   @inlinable
@@ -890,11 +898,13 @@ extension Slice {
   /// slice's `startIndex`. If `source` contains as many elements as the slice
   /// can hold, the returned index is equal to the slice's `endIndex`.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer slice
+  ///     may overlap.
+  ///
   /// - Precondition: `self.count` >= `source.count`
   ///
   /// - Parameter source: A buffer slice containing the values to copy.
-  ///     The memory region underlying `source` must be initialized. The memory
-  ///     regions referenced by `source` and this buffer slice may overlap.
+  ///     The memory region underlying `source` must be initialized.
   /// - Returns: The index one past the last element of the buffer slice
   ///    initialized by this function.
   @inlinable
@@ -925,11 +935,13 @@ extension Slice {
   /// buffer's `startIndex`. If `source` contains as many elements as the buffer
   /// slice can hold, the returned index is equal to the slice's `endIndex`.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer slice
+  ///     must not overlap.
+  ///
   /// - Precondition: `self.count` >= `source.count`
   ///
   /// - Parameter source: A buffer containing the values to move.
-  ///     The memory region underlying `source` must be initialized. The memory
-  ///     regions referenced by `source` and this buffer slice must not overlap.
+  ///     The memory region underlying `source` must be initialized.
   /// - Returns: An index one past the index of the last element updated.
   @inlinable
   @_alwaysEmitIntoClient
@@ -959,11 +971,13 @@ extension Slice {
   /// buffer's `startIndex`. If `source` contains as many elements as the buffer
   /// slice can hold, the returned index is equal to the slice's `endIndex`.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer slice
+  ///     must not overlap.
+  ///
   /// - Precondition: `self.count` >= `source.count`
   ///
   /// - Parameter source: A buffer slice containing the values to move.
-  ///     The memory region underlying `source` must be initialized. The memory
-  ///     regions referenced by `source` and this buffer slice must not overlap.
+  ///     The memory region underlying `source` must be initialized.
   /// - Returns: An index one past the index of the last element updated.
   @inlinable
   @_alwaysEmitIntoClient

stdlib/public/core/UnsafeRawBufferPointer.swift.gyb

@@ -804,6 +804,9 @@ extension Unsafe${Mutable}RawBufferPointer {
   /// to the type `C.Element` and is initialized. This method does not change
   /// the binding state of the unused portion of the buffer, if any.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer
+  ///     must not overlap.
+  ///
   /// - Parameters:
   ///   - type: The type of element to which this buffer's memory will be bound.
   ///   - source: A collection of elements to be used to
@@ -889,11 +892,13 @@ extension Unsafe${Mutable}RawBufferPointer {
   /// to the type `T` and is initialized. This method does not change
   /// the binding state of the unused portion of the buffer, if any.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer
+  ///     may overlap.
+  ///
   /// - Parameters:
   ///   - type: The type of element to which this buffer's memory will be bound.
   ///   - source: A buffer referencing the values to copy.
   ///     The memory region underlying `source` must be initialized.
-  ///     The memory regions referenced by `source` and this buffer may overlap.
   /// - Returns: A typed buffer referencing the initialized elements.
   ///     The returned buffer references memory starting at the same
   ///     base address as this buffer, and its count is equal to `source.count`.
@@ -940,11 +945,13 @@ extension Unsafe${Mutable}RawBufferPointer {
   /// to the type `T` and is initialized. This method does not change
   /// the binding state of the unused portion of the buffer, if any.
   ///
+  /// - Note: The memory regions referenced by `source` and this buffer
+  ///     may overlap.
+  ///
   /// - Parameters:
   ///   - type: The type of element to which this buffer's memory will be bound.
   ///   - source: A buffer referencing the values to copy.
   ///     The memory region underlying `source` must be initialized.
-  ///     The memory regions referenced by `source` and this buffer may overlap.
   /// - Returns: A typed buffer referencing the initialized elements.
   ///     The returned buffer references memory starting at the same
   ///     base address as this buffer, and its count is equal to `source.count`.