From 8e97c94005bd24eef4b7a7330631245fb3f57792 Mon Sep 17 00:00:00 2001
From: ilya-g <ilya.a.gorbunov@yandex.ru>
Date: Thu, 17 Jan 2019 20:37:58 +0300
Subject: [PATCH] Document that sorting is stable (#2552)

---
 runtime/src/main/kotlin/generated/_ArraysNative.kt         | 4 ++++
 runtime/src/main/kotlin/kotlin/collections/Arrays.kt       | 7 ++++++-
 .../main/kotlin/kotlin/collections/MutableCollections.kt   | 4 ++++
 3 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/runtime/src/main/kotlin/generated/_ArraysNative.kt b/runtime/src/main/kotlin/generated/_ArraysNative.kt
index 76a58b914a7..5b32efd1c57 100644
--- a/runtime/src/main/kotlin/generated/_ArraysNative.kt
+++ b/runtime/src/main/kotlin/generated/_ArraysNative.kt
@@ -1388,6 +1388,8 @@ public actual fun CharArray.sort(): Unit {
 
 /**
  * Sorts the array in-place according to the natural order of its elements.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T : Comparable<T>> Array<out T>.sort(): Unit {
     if (size > 1) kotlin.util.sortArrayComparable(this)
@@ -1395,6 +1397,8 @@ public actual fun <T : Comparable<T>> Array<out T>.sort(): Unit {
 
 /**
  * Sorts the array in-place according to the order specified by the given [comparator].
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T> Array<out T>.sortWith(comparator: Comparator<in T>): Unit {
     if (size > 1) kotlin.util.sortArrayWith(this, 0, size, comparator)
diff --git a/runtime/src/main/kotlin/kotlin/collections/Arrays.kt b/runtime/src/main/kotlin/kotlin/collections/Arrays.kt
index 8fef2f9b868..219986c07a0 100644
--- a/runtime/src/main/kotlin/kotlin/collections/Arrays.kt
+++ b/runtime/src/main/kotlin/kotlin/collections/Arrays.kt
@@ -23,7 +23,12 @@ public actual inline fun <reified T> Array<out T>?.orEmpty(): Array<out T> = thi
         throw IllegalArgumentException("fromIndex ($fromIndex) is greater than toIndex ($toIndex).")
 }
 
-
+// TODO: Move to generated code
+/**
+ * Sorts a range in the array in-place with the given [comparator].
+ *
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
+ */
 public fun <T> Array<out T>.sortWith(comparator: Comparator<in T>, fromIndex: Int = 0, toIndex: Int = size): Unit {
     sortArrayWith(this, fromIndex, toIndex, comparator)
 }
diff --git a/runtime/src/main/kotlin/kotlin/collections/MutableCollections.kt b/runtime/src/main/kotlin/kotlin/collections/MutableCollections.kt
index ee0e8f75ab2..8c123a75946 100644
--- a/runtime/src/main/kotlin/kotlin/collections/MutableCollections.kt
+++ b/runtime/src/main/kotlin/kotlin/collections/MutableCollections.kt
@@ -9,11 +9,15 @@ import kotlin.comparisons.*
 
 /**
  * Sorts elements in the list in-place according to their natural sort order.
+ *
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T : Comparable<T>> MutableList<T>.sort(): Unit = sortWith(Comparator<T> { a: T, b: T -> a.compareTo(b) })
 
 /**
  * Sorts elements in the list in-place according to the order specified with [comparator].
+ *
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T> MutableList<T>.sortWith(comparator: Comparator<in T>): Unit {
     if (size > 1) {