Add samples for coerceIn

#KT-20357

js/js.libraries/src/core/generated/_RangesJs.kt

@@ -899,6 +899,7 @@ public fun <T: Comparable<T>> T.coerceIn(range: ClosedFloatingPointRange<T>): 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
  */
 public fun <T: Comparable<T>> T.coerceIn(range: ClosedRange<T>): T {
     if (range is ClosedFloatingPointRange) {
@@ -916,6 +917,7 @@ public fun <T: Comparable<T>> T.coerceIn(range: ClosedRange<T>): 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
  */
 public fun Int.coerceIn(range: ClosedRange<Int>): Int {
     if (range is ClosedFloatingPointRange) {
@@ -933,6 +935,7 @@ public fun Int.coerceIn(range: ClosedRange<Int>): Int {
  * 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
  */
 public fun Long.coerceIn(range: ClosedRange<Long>): Long {
     if (range is ClosedFloatingPointRange) {

libraries/stdlib/common/src/generated/_Ranges.kt

@@ -641,6 +641,7 @@ public expect fun <T: Comparable<T>> 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
  */
 public expect fun <T: Comparable<T>> T.coerceIn(range: ClosedRange<T>): T
 
@@ -648,6 +649,7 @@ public expect fun <T: Comparable<T>> T.coerceIn(range: ClosedRange<T>): 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
  */
 public expect fun Int.coerceIn(range: ClosedRange<Int>): Int
 
@@ -655,6 +657,7 @@ public expect fun Int.coerceIn(range: ClosedRange<Int>): Int
  * 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
  */
 public expect fun Long.coerceIn(range: ClosedRange<Long>): Long
 

libraries/stdlib/samples/test/samples/comparisons/comparableOps.kt

@@ -17,6 +17,7 @@
 package samples.comparisons
 
 import samples.*
+import kotlin.test.assertFailsWith
 
 class ComparableOps {
 
@@ -31,4 +32,15 @@ class ComparableOps {
         assertPrints(10.coerceAtMost(5), "5")
         assertPrints(10.coerceAtMost(20), "10")
     }
+
+    @Sample
+    fun coerceIn() {
+        assertPrints(10.coerceIn(1, 100), "10")
+        assertPrints(10.coerceIn(1..100), "10")
+        assertPrints(0.coerceIn(1, 100), "1")
+        assertPrints(500.coerceIn(1, 100), "100")
+        assertFailsWith<IllegalArgumentException> {
+            10.coerceIn(100, 0)
+        }
+    }
 }

libraries/stdlib/src/generated/_Ranges.kt

@@ -899,6 +899,7 @@ public fun <T: Comparable<T>> T.coerceIn(range: ClosedFloatingPointRange<T>): 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
  */
 public fun <T: Comparable<T>> T.coerceIn(range: ClosedRange<T>): T {
     if (range is ClosedFloatingPointRange) {
@@ -916,6 +917,7 @@ public fun <T: Comparable<T>> T.coerceIn(range: ClosedRange<T>): 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
  */
 public fun Int.coerceIn(range: ClosedRange<Int>): Int {
     if (range is ClosedFloatingPointRange) {
@@ -933,6 +935,7 @@ public fun Int.coerceIn(range: ClosedRange<Int>): Int {
  * 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
  */
 public fun Long.coerceIn(range: ClosedRange<Long>): Long {
     if (range is ClosedFloatingPointRange) {

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

@@ -80,6 +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
             """
         }
         body(Generic) {