Add MutableCollection.withContiguousMutableStorageIfAvailable

stdlib/public/core/MutableCollection.swift

@@ -180,6 +180,20 @@ where SubSequence: MutableCollection
   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
+  /// 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.
+  mutating func withContiguousMutableStorageIfAvailable<R>(
+    _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
+  ) rethrows -> R?
 }
 
 // TODO: swift-3-indexing-model - review the following
@@ -191,6 +205,13 @@ extension MutableCollection {
     return nil
   }
 
+  @inlinable
+  public mutating func withContiguousMutableStorageIfAvailable<R>(
+    _ body: (inout UnsafeMutableBufferPointer<Element>) throws -> R
+  ) rethrows -> R? {
+    return nil
+  }
+
   /// Accesses a contiguous subrange of the collection's elements.
   ///
   /// The accessed slice uses the same indices for the same elements as the

test/api-digester/Outputs/stability-stdlib-abi.swift.expected

@@ -600,3 +600,5 @@ Var Dictionary.values has been removed
 Var FixedWidthInteger.allZeros has been removed (deprecated)
 Var String.Index._offset has been removed (deprecated)
 Var String.Index._utf16Index has been removed (deprecated)
+
+Func MutableCollection.withContiguousMutableStorageIfAvailable(_:) has been added as a protocol requirement

test/api-digester/Outputs/stability-stdlib-source.swift.expected

@@ -212,3 +212,5 @@ Func LazyCollectionProtocol.reversed() has been removed
 Var LazyCollectionProtocol.lazy has declared type change from LazyCollection<Self.Elements> to LazySequence<Self.Elements>
 
 Func Sequence.reduce(into:_:) has parameter 0 changing from Default to Owned
+
+Func MutableCollection.withContiguousMutableStorageIfAvailable(_:) has been added as a protocol requirement