Merge pull request #40027 from glessard/wCSIA-clarification

Author: swift-ci

stdlib/private/StdlibCollectionUnittest/LoggingWrappers.swift

@@ -387,6 +387,7 @@ extension LoggingMutableCollection: MutableCollection {
      return try base.partition(by: belongsInSecondPartition)
    }
 
+  @available(*, deprecated, renamed: "withContiguousMutableStorageIfAvailable")
   public mutating func _withUnsafeMutableBufferPointerIfSupported<R>(
     _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R? {
@@ -601,6 +602,7 @@ extension BufferAccessLoggingMutableCollection: MutableCollection {
     return base.distance(from: start, to: end)
   }
 
+  @available(*, deprecated, renamed: "withContiguousMutableStorageIfAvailable")
   public mutating func _withUnsafeMutableBufferPointerIfSupported<R>(
     _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R? {

stdlib/public/core/MutableCollection.swift

@@ -172,34 +172,53 @@ where SubSequence: MutableCollection
   ///
   /// - Complexity: O(1)
   mutating func swapAt(_ i: Index, _ j: Index)
-  
-  /// Call `body(p)`, where `p` is a pointer to the collection's
-  /// mutable contiguous storage.  If no such storage exists, it is
-  /// first created.  If the collection does not support an internal
-  /// representation in a form of mutable contiguous storage, `body` is not
+
+  /// Call `body(buffer)`, where `buffer` provides access to the contiguous
+  /// mutable storage of the entire collection. If no such storage exists, it is
+  /// first created. If the collection does not support an internal
+  /// representation in the form of contiguous mutable storage, `body` is not
   /// called and `nil` is returned.
   ///
-  /// Often, the optimizer can eliminate bounds- and uniqueness-checks
-  /// within an algorithm, but when that fails, invoking the
-  /// same algorithm on `body`\ 's argument lets you trade safety for
-  /// speed.
+  /// The optimizer can often eliminate bounds- and uniqueness-checking
+  /// within an algorithm. When that fails, however, invoking the same
+  /// algorithm on `body`\ 's argument may let you trade safety for speed.
+  ///
+  /// A `Collection` that provides its own implementation of this method
+  /// must provide contiguous storage to its elements in the same order
+  /// as they appear in the collection. This guarantees that contiguous
+  /// mutable storage to any of its subsequences can be generated by slicing
+  /// `buffer` with a range formed from the distances to the subsequence's
+  /// `startIndex` and `endIndex`, respectively.
   @available(*, deprecated, renamed: "withContiguousMutableStorageIfAvailable")
   mutating func _withUnsafeMutableBufferPointerIfSupported<R>(
     _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R?
 
-  /// Call `body(p)`, where `p` is a pointer to the collection's
-  /// mutable contiguous storage.  If no such storage exists, it is
-  /// first created.  If the collection does not support an internal
-  /// representation in a form of mutable contiguous storage, `body` is not
+  /// Call `body(buffer)`, where `buffer` provides access to the contiguous
+  /// mutable storage of the entire collection. If no such storage exists, it is
+  /// first created. If the collection does not support an internal
+  /// representation in the form of contiguous mutable storage, `body` is not
   /// called and `nil` is returned.
   ///
-  /// Often, the optimizer can eliminate bounds- and uniqueness-checks
-  /// within an algorithm, but when that fails, invoking the
-  /// same algorithm on `body`\ 's argument lets you trade safety for
-  /// speed.
+  /// The optimizer can often eliminate bounds- and uniqueness-checking
+  /// within an algorithm. When that fails, however, invoking the same
+  /// algorithm on `body`\ 's argument may let you trade safety for speed.
+  ///
+  /// A `Collection` that provides its own implementation of this method
+  /// must provide contiguous storage to its elements in the same order
+  /// as they appear in the collection. This guarantees that contiguous
+  /// mutable storage to any of its subsequences can be generated by slicing
+  /// `buffer` with a range formed from the distances to the subsequence's
+  /// `startIndex` and `endIndex`, respectively.
+  ///
+  /// - Note: `buffer` must not be replaced by `body`.
+  ///
+  /// - Parameters:
+  ///   - body: a closure to be executed using the elements of this collection.
+  ///   - buffer: a buffer to the mutable contiguous storage of this collection.
+  /// - Returns: the value returned by `body`, or `nil`.
   mutating func withContiguousMutableStorageIfAvailable<R>(
-    _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
+    _ body: (_ buffer: inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R?
 }
 

stdlib/public/core/Sequence.swift

@@ -383,20 +383,31 @@ public protocol Sequence {
   __consuming func _copyContents(
     initializing ptr: UnsafeMutableBufferPointer<Element>
   ) -> (Iterator,UnsafeMutableBufferPointer<Element>.Index)
-  
-  /// Call `body(p)`, where `p` is a pointer to the collection's
-  /// contiguous storage.  If no such storage exists, it is
-  /// first created.  If the collection does not support an internal
-  /// representation in a form of contiguous storage, `body` is not
+
+  /// Call `body(buffer)`, where `buffer` provides access to the contiguous
+  /// storage of the entire collection. If no such storage exists, it is
+  /// first created. If the collection does not support an internal
+  /// representation in the form of contiguous storage, `body` is not
   /// called and `nil` is returned.
   ///
+  /// The optimizer can often eliminate bounds- and uniqueness-checking
+  /// within an algorithm. When that fails, however, invoking the same
+  /// algorithm on `body`\ 's argument may let you trade safety for speed.
+  ///
   /// A `Collection` that provides its own implementation of this method
-  /// must also guarantee that an equivalent buffer of its `SubSequence` 
-  /// can be generated by advancing the pointer by the distance to the
-  /// slice's `startIndex`.
+  /// must provide contiguous storage to its elements in the same order
+  /// as they appear in the collection. This guarantees that contiguous
+  /// storage to any of its subsequences can be generated by slicing
+  /// `buffer` with a range formed from the distances to the subsequence's
+  /// `startIndex` and `endIndex`, respectively.
+  ///
+  /// - Parameters:
+  ///   - body: a closure to be executed using the elements of this collection.
+  ///   - buffer: a buffer to the contiguous storage of this collection.
+  /// - Returns: the value returned by `body`, or `nil`.
   func withContiguousStorageIfAvailable<R>(
-    _ body: (UnsafeBufferPointer<Element>) throws -> R
-  ) rethrows -> R?  
+    _ body: (_ buffer: UnsafeBufferPointer<Element>) throws -> R
+  ) rethrows -> R?
 }
 
 // Provides a default associated type witness for Iterator when the

stdlib/public/core/Slice.swift

@@ -309,7 +309,7 @@ extension Slice: MutableCollection where Base: MutableCollection {
         _precondition(
           slice.baseAddress == copy.baseAddress &&
           slice.count == copy.count,
-          "Slice.withUnsafeMutableBufferPointer: replacing the buffer is not allowed")
+          "Slice.withContiguousMutableStorageIfAvailable: replacing the buffer is not allowed")
       }
       return try body(&slice)
     }

stdlib/public/core/UnsafeBufferPointer.swift.gyb

@@ -472,7 +472,7 @@ extension Unsafe${Mutable}BufferPointer {
     let (oldBase, oldCount) = (self.baseAddress, self.count)
     defer { 
       _debugPrecondition((oldBase, oldCount) == (self.baseAddress, self.count),
-      "UnsafeMutableBufferPointer.withUnsafeMutableBufferPointer: replacing the buffer is not allowed")
+      "UnsafeMutableBufferPointer.withContiguousMutableStorageIfAvailable: replacing the buffer is not allowed")
     } 
     return try body(&self)
   }