azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document that sorting is stable in each platform

Browse Source 
#KT-12473 Fixed
This commit is contained in:
Ilya Gorbunov
2019-01-16 02:50:34 +03:00
parent 56672c2564
commit 0ac85ad715
10 changed files with 134 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt
+11
View File
@@ -6,6 +6,8 @@
package templates
import templates.Family.*
import templates.Ordering.stableSortNote
import templates.Ordering.appendStableSortNote
object ArrayOps : TemplateGroupBase() {
@@ -884,6 +886,7 @@ object ArrayOps : TemplateGroupBase() {
} builder {
typeParam("T : Comparable<T>")
doc { "Sorts the array in-place according to the natural order of its elements." }
appendStableSortNote()
specialFor(ArraysOfPrimitives) {
doc { "Sorts the array in-place." }
}
@@ -939,6 +942,7 @@ object ArrayOps : TemplateGroupBase() {
include(ArraysOfObjects)
} builder {
doc { "Sorts the array in-place according to the order specified by the given [comparator]." }
appendStableSortNote()
returns("Unit")
on(Platform.JVM) {
body {
@@ -968,6 +972,7 @@ object ArrayOps : TemplateGroupBase() {
body { "asDynamic().sort(comparison)" }
}
specialFor(ArraysOfObjects) {
appendStableSortNote()
body { """if (size > 1) sortArrayWith(this, comparison)""" }
}
}
@@ -981,6 +986,8 @@ object ArrayOps : TemplateGroupBase() {
"""
Sorts the array in-place according to the natural order of its elements.
$stableSortNote
@throws ClassCastException if any element of the array is not [Comparable].
"""
}
@@ -996,6 +1003,9 @@ object ArrayOps : TemplateGroupBase() {
exclude(PrimitiveType.Boolean)
} builder {
doc { "Sorts a range in the array in-place." }
specialFor(ArraysOfObjects) {
appendStableSortNote()
}
returns("Unit")
body {
"java.util.Arrays.sort(this, fromIndex, toIndex)"
@@ -1007,6 +1017,7 @@ object ArrayOps : TemplateGroupBase() {
include(ArraysOfObjects)
} builder {
doc { "Sorts a range in the array in-place with the given [comparator]." }
appendStableSortNote()
returns("Unit")
body {
"java.util.Arrays.sort(this, fromIndex, toIndex, comparator)"
libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
+41
View File
@@ -96,6 +96,15 @@ object Ordering : TemplateGroupBase() {
}
}
val stableSortNote =
"The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting."
fun MemberBuilder.appendStableSortNote() {
doc {
doc.orEmpty().trimIndent() + "\n\n" + stableSortNote
}
}
val f_sorted = fn("sorted()") {
includeDefault()
exclude(PrimitiveType.Boolean)
@@ -106,6 +115,9 @@ object Ordering : TemplateGroupBase() {
Returns a list of all elements sorted according to their natural sort order.
"""
}
if (f != ArraysOfPrimitives) {
appendStableSortNote()
}
returns("List<T>")
typeParam("T : Comparable<T>")
body {
@@ -134,6 +146,7 @@ object Ordering : TemplateGroupBase() {
doc {
"Returns a sequence that yields elements of this sequence sorted according to their natural sort order."
}
appendStableSortNote()
sequenceClassification(intermediate, stateful)
}
body(Sequences) {
@@ -156,6 +169,9 @@ object Ordering : TemplateGroupBase() {
doc {
"Returns an array with all elements of this array sorted according to their natural sort order."
}
specialFor(InvariantArraysOfObjects) {
appendStableSortNote()
}
typeParam("T : Comparable<T>")
returns("SELF")
body {
@@ -171,6 +187,9 @@ object Ordering : TemplateGroupBase() {
exclude(PrimitiveType.Boolean)
} builder {
doc { """Sorts elements in the ${f.collection} in-place descending according to their natural sort order.""" }
if (f != ArraysOfPrimitives) {
appendStableSortNote()
}
returns("Unit")
typeParam("T : Comparable<T>")
specialFor(Lists) {
@@ -198,6 +217,9 @@ object Ordering : TemplateGroupBase() {
Returns a list of all elements sorted descending according to their natural sort order.
"""
}
if (f != ArraysOfPrimitives) {
appendStableSortNote()
}
returns("List<T>")
typeParam("T : Comparable<T>")
body {
@@ -216,6 +238,7 @@ object Ordering : TemplateGroupBase() {
doc {
"Returns a sequence that yields elements of this sequence sorted descending according to their natural sort order."
}
appendStableSortNote()
sequenceClassification(intermediate, stateful)
}
}
@@ -227,6 +250,9 @@ object Ordering : TemplateGroupBase() {
doc {
"Returns an array with all elements of this array sorted descending according to their natural sort order."
}
specialFor(InvariantArraysOfObjects) {
appendStableSortNote()
}
typeParam("T : Comparable<T>")
returns("SELF")
body(InvariantArraysOfObjects) {
@@ -252,6 +278,9 @@ object Ordering : TemplateGroupBase() {
Returns a list of all elements sorted according to the specified [comparator].
"""
}
if (f != ArraysOfPrimitives) {
appendStableSortNote()
}
body {
"""
if (this is Collection) {
@@ -278,6 +307,7 @@ object Ordering : TemplateGroupBase() {
doc {
"Returns a sequence that yields elements of this sequence sorted according to the specified [comparator]."
}
appendStableSortNote()
sequenceClassification(intermediate, stateful)
}
body(Sequences) {
@@ -299,6 +329,7 @@ object Ordering : TemplateGroupBase() {
doc {
"Returns an array with all elements of this array sorted according the specified [comparator]."
}
appendStableSortNote()
returns("SELF")
body {
"""
@@ -313,6 +344,7 @@ object Ordering : TemplateGroupBase() {
} builder {
inline()
doc { """Sorts elements in the ${f.collection} in-place according to natural sort order of the value returned by specified [selector] function.""" }
appendStableSortNote()
returns("Unit")
typeParam("R : Comparable<R>")
specialFor(Lists) { receiver("MutableList<T>") }
@@ -332,12 +364,16 @@ object Ordering : TemplateGroupBase() {
Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
"""
}
if (f != ArraysOfPrimitives) {
appendStableSortNote()
}
specialFor(Sequences) {
returns("SELF")
doc {
"Returns a sequence that yields elements of this sequence sorted according to natural sort order of the value returned by specified [selector] function."
}
appendStableSortNote()
sequenceClassification(intermediate, stateful)
}
body {
@@ -350,6 +386,7 @@ object Ordering : TemplateGroupBase() {
} builder {
inline()
doc { """Sorts elements in the ${f.collection} in-place descending according to natural sort order of the value returned by specified [selector] function.""" }
appendStableSortNote()
returns("Unit")
typeParam("R : Comparable<R>")
specialFor(Lists) { receiver("MutableList<T>") }
@@ -370,12 +407,16 @@ object Ordering : TemplateGroupBase() {
Returns a list of all elements sorted descending according to natural sort order of the value returned by specified [selector] function.
"""
}
if (f != ArraysOfPrimitives) {
appendStableSortNote()
}
specialFor(Sequences) {
returns("SELF")
doc {
"Returns a sequence that yields elements of this sequence sorted descending according to natural sort order of the value returned by specified [selector] function."
}
appendStableSortNote()
sequenceClassification(intermediate, stateful)
}