From 8fc83e3ff58c218205596b9ea820253433aabd41 Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Wed, 10 Jan 2018 17:46:52 +0300 Subject: [PATCH] Add samples for coerceIn, coerceAtLeast, coerceAtMost for comparable types #KT-20357 --- .../src/core/generated/_RangesJs.kt | 13 ++++++++--- .../stdlib/common/src/generated/_Ranges.kt | 13 ++++++++--- .../test/samples/comparisons/comparableOps.kt | 23 +++++++++++++++++++ libraries/stdlib/src/generated/_Ranges.kt | 13 ++++++++--- .../src/templates/Comparables.kt | 7 +++--- 5 files changed, 57 insertions(+), 12 deletions(-) diff --git a/js/js.libraries/src/core/generated/_RangesJs.kt b/js/js.libraries/src/core/generated/_RangesJs.kt index 42a904ede04..6a004d30097 100644 --- a/js/js.libraries/src/core/generated/_RangesJs.kt +++ b/js/js.libraries/src/core/generated/_RangesJs.kt @@ -652,7 +652,7 @@ public infix fun Short.until(to: Short): IntRange { * Ensures that this value is not less than the specified [minimumValue]. * * @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise. - * @sample samples.comparisons.ComparableOps.coerceAtLeast + * @sample samples.comparisons.ComparableOps.coerceAtLeastComparable */ public fun > T.coerceAtLeast(minimumValue: T): T { return if (this < minimumValue) minimumValue else this @@ -722,7 +722,7 @@ public fun Double.coerceAtLeast(minimumValue: Double): Double { * Ensures that this value is not greater than the specified [maximumValue]. * * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise. - * @sample samples.comparisons.ComparableOps.coerceAtMost + * @sample samples.comparisons.ComparableOps.coerceAtMostComparable */ public fun > T.coerceAtMost(maximumValue: T): T { return if (this > maximumValue) maximumValue else this @@ -792,6 +792,7 @@ public fun Double.coerceAtMost(maximumValue: Double): Double { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceInComparable */ public fun > T.coerceIn(minimumValue: T?, maximumValue: T?): T { if (minimumValue !== null && maximumValue !== null) { @@ -810,6 +811,7 @@ public fun > T.coerceIn(minimumValue: T?, maximumValue: T?): T * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -822,6 +824,7 @@ public fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Short { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -834,6 +837,7 @@ public fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Short { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -846,6 +850,7 @@ public fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -858,6 +863,7 @@ public fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Float { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -870,6 +876,7 @@ public fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Float { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Double.coerceIn(minimumValue: Double, maximumValue: Double): Double { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -899,7 +906,7 @@ public fun > T.coerceIn(range: ClosedFloatingPointRange): T * Ensures that this value lies in the specified [range]. * * @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`. - * @sample samples.comparisons.ComparableOps.coerceIn + * @sample samples.comparisons.ComparableOps.coerceInComparable */ public fun > T.coerceIn(range: ClosedRange): T { if (range is ClosedFloatingPointRange) { diff --git a/libraries/stdlib/common/src/generated/_Ranges.kt b/libraries/stdlib/common/src/generated/_Ranges.kt index 0cf6e048b69..3a270b9b8ca 100644 --- a/libraries/stdlib/common/src/generated/_Ranges.kt +++ b/libraries/stdlib/common/src/generated/_Ranges.kt @@ -472,7 +472,7 @@ public expect infix fun Short.until(to: Short): IntRange * Ensures that this value is not less than the specified [minimumValue]. * * @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise. - * @sample samples.comparisons.ComparableOps.coerceAtLeast + * @sample samples.comparisons.ComparableOps.coerceAtLeastComparable */ public expect fun > T.coerceAtLeast(minimumValue: T): T @@ -528,7 +528,7 @@ public expect fun Double.coerceAtLeast(minimumValue: Double): Double * Ensures that this value is not greater than the specified [maximumValue]. * * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise. - * @sample samples.comparisons.ComparableOps.coerceAtMost + * @sample samples.comparisons.ComparableOps.coerceAtMostComparable */ public expect fun > T.coerceAtMost(maximumValue: T): T @@ -584,6 +584,7 @@ public expect fun Double.coerceAtMost(maximumValue: Double): Double * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceInComparable */ public expect fun > T.coerceIn(minimumValue: T?, maximumValue: T?): T @@ -591,6 +592,7 @@ public expect fun > T.coerceIn(minimumValue: T?, maximumValue: * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public expect fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte @@ -598,6 +600,7 @@ public expect fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public expect fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Short @@ -605,6 +608,7 @@ public expect fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Shor * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public expect fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int @@ -612,6 +616,7 @@ public expect fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public expect fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long @@ -619,6 +624,7 @@ public expect fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public expect fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Float @@ -626,6 +632,7 @@ public expect fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Floa * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public expect fun Double.coerceIn(minimumValue: Double, maximumValue: Double): Double @@ -641,7 +648,7 @@ public expect fun > T.coerceIn(range: ClosedFloatingPointRange< * Ensures that this value lies in the specified [range]. * * @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`. - * @sample samples.comparisons.ComparableOps.coerceIn + * @sample samples.comparisons.ComparableOps.coerceInComparable */ public expect fun > T.coerceIn(range: ClosedRange): T diff --git a/libraries/stdlib/samples/test/samples/comparisons/comparableOps.kt b/libraries/stdlib/samples/test/samples/comparisons/comparableOps.kt index e2694fe2d9e..c55fb5b5bb0 100644 --- a/libraries/stdlib/samples/test/samples/comparisons/comparableOps.kt +++ b/libraries/stdlib/samples/test/samples/comparisons/comparableOps.kt @@ -17,6 +17,7 @@ package samples.comparisons import samples.* +import java.time.DayOfWeek import kotlin.test.assertFailsWith class ComparableOps { @@ -27,12 +28,25 @@ class ComparableOps { assertPrints(10.coerceAtLeast(20), "20") } + @Sample + fun coerceAtLeastComparable() { + assertPrints(DayOfWeek.WEDNESDAY.coerceAtLeast(DayOfWeek.MONDAY), "WEDNESDAY") + assertPrints(DayOfWeek.WEDNESDAY.coerceAtLeast(DayOfWeek.FRIDAY), "FRIDAY") + } + @Sample fun coerceAtMost() { assertPrints(10.coerceAtMost(5), "5") assertPrints(10.coerceAtMost(20), "10") } + + @Sample + fun coerceAtMostComparable() { + assertPrints(DayOfWeek.FRIDAY.coerceAtMost(DayOfWeek.SATURDAY), "FRIDAY") + assertPrints(DayOfWeek.FRIDAY.coerceAtMost(DayOfWeek.WEDNESDAY), "WEDNESDAY") + } + @Sample fun coerceIn() { assertPrints(10.coerceIn(1, 100), "10") @@ -43,4 +57,13 @@ class ComparableOps { 10.coerceIn(100, 0) } } + + @Sample + fun coerceInComparable() { + val workingDays = DayOfWeek.MONDAY..DayOfWeek.FRIDAY + assertPrints(DayOfWeek.WEDNESDAY.coerceIn(workingDays), "WEDNESDAY") + assertPrints(DayOfWeek.SATURDAY.coerceIn(workingDays), "FRIDAY") + + assertPrints(DayOfWeek.FRIDAY.coerceIn(DayOfWeek.SATURDAY, DayOfWeek.SUNDAY), "SATURDAY") + } } \ No newline at end of file diff --git a/libraries/stdlib/src/generated/_Ranges.kt b/libraries/stdlib/src/generated/_Ranges.kt index 10ac47cde19..d079c37d81a 100644 --- a/libraries/stdlib/src/generated/_Ranges.kt +++ b/libraries/stdlib/src/generated/_Ranges.kt @@ -652,7 +652,7 @@ public infix fun Short.until(to: Short): IntRange { * Ensures that this value is not less than the specified [minimumValue]. * * @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise. - * @sample samples.comparisons.ComparableOps.coerceAtLeast + * @sample samples.comparisons.ComparableOps.coerceAtLeastComparable */ public fun > T.coerceAtLeast(minimumValue: T): T { return if (this < minimumValue) minimumValue else this @@ -722,7 +722,7 @@ public fun Double.coerceAtLeast(minimumValue: Double): Double { * Ensures that this value is not greater than the specified [maximumValue]. * * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise. - * @sample samples.comparisons.ComparableOps.coerceAtMost + * @sample samples.comparisons.ComparableOps.coerceAtMostComparable */ public fun > T.coerceAtMost(maximumValue: T): T { return if (this > maximumValue) maximumValue else this @@ -792,6 +792,7 @@ public fun Double.coerceAtMost(maximumValue: Double): Double { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceInComparable */ public fun > T.coerceIn(minimumValue: T?, maximumValue: T?): T { if (minimumValue !== null && maximumValue !== null) { @@ -810,6 +811,7 @@ public fun > T.coerceIn(minimumValue: T?, maximumValue: T?): T * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -822,6 +824,7 @@ public fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Short { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -834,6 +837,7 @@ public fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Short { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -846,6 +850,7 @@ public fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -858,6 +863,7 @@ public fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Float { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -870,6 +876,7 @@ public fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Float { * Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. * * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + * @sample samples.comparisons.ComparableOps.coerceIn */ public fun Double.coerceIn(minimumValue: Double, maximumValue: Double): Double { if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum $maximumValue is less than minimum $minimumValue.") @@ -899,7 +906,7 @@ public fun > T.coerceIn(range: ClosedFloatingPointRange): T * Ensures that this value lies in the specified [range]. * * @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`. - * @sample samples.comparisons.ComparableOps.coerceIn + * @sample samples.comparisons.ComparableOps.coerceInComparable */ public fun > T.coerceIn(range: ClosedRange): T { if (range is ClosedFloatingPointRange) { diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt index eae94b11474..b871c6a9929 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt @@ -36,7 +36,7 @@ object ComparableOps : TemplateGroupBase() { Ensures that this value is not less than the specified [minimumValue]. @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise. - @sample samples.comparisons.ComparableOps.coerceAtLeast + @sample samples.comparisons.ComparableOps.coerceAtLeast${if (f == Generic) "Comparable" else ""} """ } body { @@ -58,7 +58,7 @@ object ComparableOps : TemplateGroupBase() { Ensures that this value is not greater than the specified [maximumValue]. @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise. - @sample samples.comparisons.ComparableOps.coerceAtMost + @sample samples.comparisons.ComparableOps.coerceAtMost${if (f == Generic) "Comparable" else ""} """ } body { @@ -80,7 +80,7 @@ object ComparableOps : TemplateGroupBase() { Ensures that this value lies in the specified [range]. @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`. - @sample samples.comparisons.ComparableOps.coerceIn + @sample samples.comparisons.ComparableOps.coerceIn${if (f == Generic) "Comparable" else ""} """ } body(Generic) { @@ -344,6 +344,7 @@ object ComparableOps : TemplateGroupBase() { Ensures that this value lies in the specified range [minimumValue]..[maximumValue]. @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue]. + @sample samples.comparisons.ComparableOps.coerceIn${if (f == Generic) "Comparable" else ""} """ } body(Primitives) {