[Docs] Note that partition(by:) is unstable (#39384)

Author: natecook1000

stdlib/public/core/CollectionAlgorithms.swift

@@ -221,7 +221,9 @@ extension MutableCollection {
   /// After partitioning a collection, there is a pivot index `p` where
   /// no element before `p` satisfies the `belongsInSecondPartition`
   /// predicate and every element at or after `p` satisfies
-  /// `belongsInSecondPartition`.
+  /// `belongsInSecondPartition`. This operation isn't guaranteed to be
+  /// stable, so the relative ordering of elements within the partitions might
+  /// change.
   ///
   /// In the following example, an array of numbers is partitioned by a
   /// predicate that matches elements greater than 30.
@@ -241,6 +243,10 @@ extension MutableCollection {
   ///     let second = numbers[p...]
   ///     // second == [60, 40]
   ///
+  /// Note that the order of elements in both partitions changed.
+  /// That is, `40` appears before `60` in the original collection,
+  /// but, after calling `partition(by:)`, `60` appears before `40`.
+  ///
   /// - Parameter belongsInSecondPartition: A predicate used to partition
   ///   the collection. All elements satisfying this predicate are ordered
   ///   after all elements not satisfying it.
@@ -285,7 +291,9 @@ extension MutableCollection where Self: BidirectionalCollection {
   /// After partitioning a collection, there is a pivot index `p` where
   /// no element before `p` satisfies the `belongsInSecondPartition`
   /// predicate and every element at or after `p` satisfies
-  /// `belongsInSecondPartition`.
+  /// `belongsInSecondPartition`. This operation isn't guaranteed to be
+  /// stable, so the relative ordering of elements within the partitions might
+  /// change.
   ///
   /// In the following example, an array of numbers is partitioned by a
   /// predicate that matches elements greater than 30.
@@ -305,6 +313,10 @@ extension MutableCollection where Self: BidirectionalCollection {
   ///     let second = numbers[p...]
   ///     // second == [60, 40]
   ///
+  /// Note that the order of elements in both partitions changed.
+  /// That is, `40` appears before `60` in the original collection,
+  /// but, after calling `partition(by:)`, `60` appears before `40`.
+  ///
   /// - Parameter belongsInSecondPartition: A predicate used to partition
   ///   the collection. All elements satisfying this predicate are ordered
   ///   after all elements not satisfying it.

stdlib/public/core/MutableCollection.swift

@@ -121,7 +121,9 @@ where SubSequence: MutableCollection
   /// After partitioning a collection, there is a pivot index `p` where
   /// no element before `p` satisfies the `belongsInSecondPartition`
   /// predicate and every element at or after `p` satisfies
-  /// `belongsInSecondPartition`.
+  /// `belongsInSecondPartition`. This operation isn't guaranteed to be
+  /// stable, so the relative ordering of elements within the partitions might
+  /// change.
   ///
   /// In the following example, an array of numbers is partitioned by a
   /// predicate that matches elements greater than 30.
@@ -141,6 +143,10 @@ where SubSequence: MutableCollection
   ///     let second = numbers[p...]
   ///     // second == [60, 40]
   ///
+  /// Note that the order of elements in both partitions changed.
+  /// That is, `40` appears before `60` in the original collection,
+  /// but, after calling `partition(by:)`, `60` appears before `40`.
+  ///
   /// - Parameter belongsInSecondPartition: A predicate used to partition
   ///   the collection. All elements satisfying this predicate are ordered
   ///   after all elements not satisfying it.