KT-16602: Provide samples for sorting API usage

libraries/stdlib/samples/test/samples/collections/arrays.kt

@@ -131,4 +131,53 @@ class Arrays {
         }
     }
 
+    class Sorting {
+
+        @Sample
+        fun sortArray() {
+            val intArray = intArrayOf(4, 3, 2, 1)
+
+            assertPrints(intArray.joinToString(), "4, 3, 2, 1")
+
+            intArray.sort()
+
+            assertPrints(intArray.joinToString(), "1, 2, 3, 4")
+        }
+
+        @Sample
+        fun sortArrayOfComparable() {
+            data class Person(val firstName: String, val lastName: String) : Comparable<Person> {
+                override fun compareTo(other: Person): Int {
+                    return lastName.compareTo(other.lastName)
+                }
+
+            }
+
+            val people = arrayOf(
+                Person("Ragnar", "Lodbrok"),
+                Person("Bjorn", "Ironside"),
+                Person("Sweyn", "Forkbeard")
+            )
+
+            assertPrints(people.joinToString(), "Person(firstName=Ragnar, lastName=Lodbrok), Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Sweyn, lastName=Forkbeard)")
+
+            people.sort()
+
+            assertPrints(people.joinToString(), "Person(firstName=Sweyn, lastName=Forkbeard), Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Ragnar, lastName=Lodbrok)")
+
+        }
+
+        @Sample
+        fun sortRangeOfArray() {
+            val intArray = intArrayOf(4, 3, 2, 1)
+
+            assertPrints(intArray.joinToString(), "4, 3, 2, 1")
+
+            intArray.sort(0, 3)
+
+            assertPrints(intArray.joinToString(), "2, 3, 4, 1")
+        }
+
+    }
+
 }

libraries/stdlib/samples/test/samples/collections/collections.kt

@@ -561,4 +561,41 @@ class Collections {
             assertPrints(emptyList.elementAtOrElse(0) { "no int" }, "no int")
         }
     }
+
+    class Sorting {
+
+        @Sample
+        fun sortMutableList() {
+            val mutableList = mutableListOf(4, 3, 2, 1)
+
+            assertPrints(mutableList.joinToString(), "4, 3, 2, 1")
+
+            mutableList.sort()
+
+            assertPrints(mutableList.joinToString(), "1, 2, 3, 4")
+        }
+
+        @Sample
+        fun sortRangeOfComparable() {
+            data class Person(val firstName: String, val lastName: String) : Comparable<Person> {
+                override fun compareTo(other: Person): Int {
+                    return lastName.compareTo(other.lastName)
+                }
+
+            }
+
+            val people = arrayOf(
+                Person("Ragnar", "Lodbrok"),
+                Person("Bjorn", "Ironside"),
+                Person("Sweyn", "Forkbeard")
+            )
+
+            assertPrints(people.joinToString(), "Person(firstName=Ragnar, lastName=Lodbrok), Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Sweyn, lastName=Forkbeard)")
+
+            people.sort(0, 2)
+
+            assertPrints(people.joinToString(), "Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Ragnar, lastName=Lodbrok), Person(firstName=Sweyn, lastName=Forkbeard)")
+        }
+
+    }
 }