[stdlib] Document that removeAll(where:) doesn't reorder the remaining elements. (swiftlang#18803)

* Document that removeAll(where:) doesn't reorder the remaining elements.

Per Swift Forums discussion on the topic:
"Does removeAll(where:) on arrays guarantee preserved order of elements?"

* Copy docs from the first default impl up to the protocol requirement.

Per Nate's feedback on PR#18803.

The protocol requirement was missing a few extra sentences and a
code example.

* Fix a code example that would fail to remove negative odd integers.

Per feedback on the forums from Jens,
swap `== 1` with `!= 0` so that negative odd numbers would be
removed, too, if the example were modified to include some negative
numbers in the input array.

Author: krilnon

stdlib/public/core/RangeReplaceableCollection.swift

@@ -343,7 +343,16 @@ public protocol RangeReplaceableCollection : Collection
   /// - Complexity: O(*n*), where *n* is the length of the collection.
   mutating func removeAll(keepingCapacity keepCapacity: Bool /*= false*/)
 
-  /// Removes from the collection all elements that satisfy the given predicate.
+  /// Removes all the elements that satisfy the given predicate.
+  ///
+  /// Use this method to remove every element in a collection that meets
+  /// particular criteria. The order of the remaining elements is preserved.
+  /// This example removes all the odd values from an
+  /// array of numbers:
+  ///
+  ///     var numbers = [5, 6, 7, 8, 9, 10, 11]
+  ///     numbers.removeAll(where: { $0 % 2 != 0 })
+  ///     // numbers == [6, 8, 10]
   ///
   /// - Parameter shouldBeRemoved: A closure that takes an element of the
   ///   sequence as its argument and returns a Boolean value indicating
@@ -1083,11 +1092,12 @@ extension RangeReplaceableCollection where Self: MutableCollection {
   /// Removes all the elements that satisfy the given predicate.
   ///
   /// Use this method to remove every element in a collection that meets
-  /// particular criteria. This example removes all the odd values from an
+  /// particular criteria. The order of the remaining elements is preserved.
+  /// This example removes all the odd values from an
   /// array of numbers:
   ///
   ///     var numbers = [5, 6, 7, 8, 9, 10, 11]
-  ///     numbers.removeAll(where: { $0 % 2 == 1 })
+  ///     numbers.removeAll(where: { $0 % 2 != 0 })
   ///     // numbers == [6, 8, 10]
   ///
   /// - Parameter shouldBeRemoved: A closure that takes an element of the
@@ -1108,7 +1118,8 @@ extension RangeReplaceableCollection {
   /// Removes all the elements that satisfy the given predicate.
   ///
   /// Use this method to remove every element in a collection that meets
-  /// particular criteria. This example removes all the vowels from a string:
+  /// particular criteria. The order of the remaining elements is preserved.
+  /// This example removes all the vowels from a string:
   ///
   ///     var phrase = "The rain in Spain stays mainly in the plain."
   ///