Deprecate all sort methods and provide sorted ones.

#KT-4903

libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt

@@ -38,6 +38,152 @@ fun ordering(): List<GenericFunction> {
         exclude(Sequences)
     }
 
+    templates add f("sorted()") {
+        exclude(Strings)
+        exclude(PrimitiveType.Boolean)
+
+        doc {
+            """
+            Returns a list of all elements sorted according to their natural sort order.
+            """
+        }
+        returns("List<T>")
+        typeParam("T : Comparable<T>")
+        body {
+            """
+            val sortedList = toArrayList()
+            java.util.Collections.sort(sortedList)
+            return sortedList
+            """
+        }
+
+        returns("SELF", Sequences)
+        doc(Sequences) {
+            "Returns a sequence that yields elements of this sequence sorted according to their natural sort order."
+        }
+        body(Sequences) {
+            """
+            return object : Sequence<T> {
+                override fun iterator(): Iterator<T> {
+                    val sortedList = this@sorted.toArrayList()
+                    java.util.Collections.sort(sortedList)
+                    return sortedList.iterator()
+                }
+            }
+            """
+        }
+    }
+
+    templates add f("sortedDescending()") {
+        exclude(Strings)
+        exclude(PrimitiveType.Boolean)
+
+        doc {
+            """
+            Returns a list of all elements sorted descending according to their natural sort order.
+            """
+        }
+        returns("List<T>")
+        typeParam("T : Comparable<T>")
+        body {
+            """
+            return sortedWith(comparator { x, y -> y.compareTo(x) })
+            """
+        }
+        body(ArraysOfPrimitives) {
+            """
+            return copyOf().apply { sort() }.reverse()
+            """
+        }
+
+        returns("SELF", Sequences)
+        doc(Sequences) {
+            "Returns a sequence that yields elements of this sequence sorted descending according to their natural sort order."
+        }
+        body(Sequences) {
+            """
+            return sortedWith(comparator { x, y -> y.compareTo(x) })
+            """
+        }
+    }
+
+    templates add f("sortedWith(comparator: Comparator<in T>)") {
+        exclude(Strings)
+        returns("List<T>")
+        doc {
+            """
+            Returns a list of all elements sorted according to the specified [comparator].
+            """
+        }
+        body {
+            """
+            val sortedList = toArrayList()
+            java.util.Collections.sort(sortedList, comparator)
+            return sortedList
+            """
+        }
+
+        returns("SELF", Sequences)
+        doc(Sequences) {
+            "Returns a sequence that yields elements of this sequence sorted according to the specified [comparator]."
+        }
+        body(Sequences) {
+            """
+            return object : Sequence<T> {
+                override fun iterator(): Iterator<T> {
+                    val sortedList = this@sortedWith.toArrayList()
+                    java.util.Collections.sort(sortedList, comparator)
+                    return sortedList.iterator()
+                }
+            }
+            """
+        }
+    }
+
+    templates add f("sortedBy(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) order: (T) -> R?)") {
+        exclude(Strings)
+        inline(true)
+        returns("List<T>")
+        typeParam("R : Comparable<R>")
+
+        doc {
+            """
+            Returns a list of all elements sorted according to natural sort order of the value returned by specified [order] function.
+            """
+        }
+
+        returns("SELF", Sequences)
+        doc(Sequences) {
+            "Returns a sequence that yields elements of this sequence sorted according to natural sort order of the value returned by specified [order] function."
+        }
+
+        body {
+            "return sortedWith(compareBy(order))"
+        }
+    }
+
+    templates add f("sortedDescendingBy(inlineOptions(InlineOption.ONLY_LOCAL_RETURN) order: (T) -> R?)") {
+        exclude(Strings)
+        inline(true)
+        returns("List<T>")
+        typeParam("R : Comparable<R>")
+
+        doc {
+            """
+            Returns a list of all elements sorted descending according to natural sort order of the value returned by specified [order] function.
+            """
+        }
+
+        returns("SELF", Sequences)
+        doc(Sequences) {
+            "Returns a sequence that yields elements of this sequence sorted descending according to natural sort order of the value returned by specified [order] function."
+        }
+
+        body {
+            "return sortedWith(compareByDescending(order))"
+        }
+    }
+
     templates add f("sort()") {
         doc {
             """
@@ -46,6 +192,8 @@ fun ordering(): List<GenericFunction> {
         }
         returns("List<T>")
         typeParam("T : Comparable<T>")
+        deprecate("This method may change its behavior soon. Use sorted() instead.")
+        deprecateReplacement("sorted()")
         body {
             """
             val sortedList = toArrayList()
@@ -68,6 +216,11 @@ fun ordering(): List<GenericFunction> {
         }
         returns("List<T>")
         typeParam("T : Comparable<T>")
+        deprecate("Use sorted() instead.")
+        deprecateReplacement("sorted()")
+
+        deprecate("Use asIterable().sorted() instead.", Sequences)
+        deprecateReplacement("asIterable().sorted()", Sequences)
         body {
             """
             val sortedList = toArrayList()
@@ -85,6 +238,8 @@ fun ordering(): List<GenericFunction> {
             Returns a sorted list of all elements, in descending order.
             """
         }
+        deprecate("This method may change its behavior soon. Use sortedDescending() instead.")
+        deprecateReplacement("sortedDescending()")
         returns("List<T>")
         typeParam("T : Comparable<T>")
         body {
@@ -109,6 +264,8 @@ fun ordering(): List<GenericFunction> {
             Returns a sorted list of all elements, ordered by results of specified [order] function.
             """
         }
+        deprecate("This method may change its behavior soon. Use sortedBy() instead.")
+        deprecateReplacement("sortedBy(order)")
         returns("List<T>")
         typeParam("R : Comparable<R>")
         body {
@@ -132,6 +289,11 @@ fun ordering(): List<GenericFunction> {
             """
         }
         returns("List<T>")
+        deprecate("Use sortedBy(order) instead.")
+        deprecateReplacement("sortedBy(order)")
+
+        deprecate("Use asIterable().sortedBy(order) instead.", Sequences)
+        deprecateReplacement("asIterable().sortedBy(order)", Sequences)
         typeParam("T")
         typeParam("V : Comparable<V>")
         body {
@@ -154,6 +316,8 @@ fun ordering(): List<GenericFunction> {
             Returns a sorted list of all elements, in descending order by results of specified [order] function.
             """
         }
+        deprecate("This method may change its behavior soon. Use sortedDescendingBy() instead.")
+        deprecateReplacement("sortedDescendingBy(order)")
         returns("List<T>")
         typeParam("R : Comparable<R>")
         body {
@@ -177,6 +341,8 @@ fun ordering(): List<GenericFunction> {
             """
         }
         returns("List<T>")
+        deprecate("This method may change its behavior soon. Use sortedWith() instead.")
+        deprecateReplacement("sortedWith(comparator)")
         body {
             """
             val sortedList = toArrayList()