[stdlib] Deprecate MutableCollection._withUnsafeMutableBufferPointerIfSupported

In Swift 5.0, [SE-0237] introduced the public `MutableCollection.withContiguousMutableStorageIfAvailable` method. It’s time we migrated off the old, underscored variant and deprecated it.

The default `MutableCollection.sort` and `.partition(by:)` implementations are currently calling this hidden method rather than the documented interface, preventing custom Collection implementations from achieving good performance, even if they have contiguous storage.

[SE-0237]: https://github.com/apple/swift-evolution/blob/master/proposals/0237-contiguous-collection.md

Author: lorentey

stdlib/public/core/Array.swift

@@ -1356,6 +1356,7 @@ extension Array: RangeReplaceableCollection {
   //===--- algorithms -----------------------------------------------------===//
 
   @inlinable
+  @available(*, deprecated, renamed: "withContiguousMutableStorageIfAvailable")
   public mutating func _withUnsafeMutableBufferPointerIfSupported<R>(
     _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R? {

stdlib/public/core/ArraySlice.swift

@@ -1079,6 +1079,7 @@ extension ArraySlice: RangeReplaceableCollection {
   //===--- algorithms -----------------------------------------------------===//
 
   @inlinable
+  @available(*, deprecated, renamed: "withContiguousMutableStorageIfAvailable")
   public mutating func _withUnsafeMutableBufferPointerIfSupported<R>(
     _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R? {

stdlib/public/core/CollectionAlgorithms.swift

@@ -318,7 +318,7 @@ extension MutableCollection where Self: BidirectionalCollection {
   public mutating func partition(
     by belongsInSecondPartition: (Element) throws -> Bool
   ) rethrows -> Index {
-    let maybeOffset = try _withUnsafeMutableBufferPointerIfSupported {
+    let maybeOffset = try withContiguousMutableStorageIfAvailable {
       (bufferPointer) -> Int in
       let unsafeBufferPivot = try bufferPointer._partitionImpl(
         by: belongsInSecondPartition)

stdlib/public/core/ContiguousArray.swift

@@ -980,6 +980,7 @@ extension ContiguousArray: RangeReplaceableCollection {
   //===--- algorithms -----------------------------------------------------===//
 
   @inlinable
+  @available(*, deprecated, renamed: "withContiguousMutableStorageIfAvailable")
   public mutating func _withUnsafeMutableBufferPointerIfSupported<R>(
     _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R? {

stdlib/public/core/MutableCollection.swift

@@ -177,6 +177,7 @@ where SubSequence: MutableCollection
   /// within an algorithm, but when that fails, invoking the
   /// same algorithm on `body`\ 's argument lets you trade safety for
   /// speed.
+  @available(*, deprecated, renamed: "withContiguousMutableStorageIfAvailable")
   mutating func _withUnsafeMutableBufferPointerIfSupported<R>(
     _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R?
@@ -199,6 +200,7 @@ where SubSequence: MutableCollection
 // TODO: swift-3-indexing-model - review the following
 extension MutableCollection {
   @inlinable
+  @available(*, deprecated, renamed: "withContiguousMutableStorageIfAvailable")
   public mutating func _withUnsafeMutableBufferPointerIfSupported<R>(
     _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R? {

stdlib/public/core/Sort.swift

@@ -246,10 +246,10 @@ extension MutableCollection where Self: RandomAccessCollection {
   public mutating func sort(
     by areInIncreasingOrder: (Element, Element) throws -> Bool
   ) rethrows {
-    let didSortUnsafeBuffer: Void? = try _withUnsafeMutableBufferPointerIfSupported {
-      buffer -> Void in
+    let didSortUnsafeBuffer =
+      try withContiguousMutableStorageIfAvailable { buffer in
         try buffer._stableSortImpl(by: areInIncreasingOrder)
-    }
+      }
     if didSortUnsafeBuffer == nil {
       // Fallback since we can't use an unsafe buffer: sort into an outside
       // array, then copy elements back in.

stdlib/public/core/UnsafeBufferPointer.swift.gyb

@@ -446,6 +446,7 @@ extension Unsafe${Mutable}BufferPointer {
   }
 
   @inlinable
+  @available(*, deprecated, renamed: "withContiguousMutableStorageIfAvailable")
   public mutating func _withUnsafeMutableBufferPointerIfSupported<R>(
     _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R? {