KT-20357 Add samples for elementAtOrElse

Move samples to Elements nested class.

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

@@ -444,7 +444,7 @@ public operator fun CharArray.contains(element: Char): Boolean {
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> Array<out T>.elementAt(index: Int): T {
@@ -454,7 +454,7 @@ public inline fun <T> Array<out T>.elementAt(index: Int): T {
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun ByteArray.elementAt(index: Int): Byte {
@@ -464,7 +464,7 @@ public inline fun ByteArray.elementAt(index: Int): Byte {
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun ShortArray.elementAt(index: Int): Short {
@@ -474,7 +474,7 @@ public inline fun ShortArray.elementAt(index: Int): Short {
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun IntArray.elementAt(index: Int): Int {
@@ -484,7 +484,7 @@ public inline fun IntArray.elementAt(index: Int): Int {
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun LongArray.elementAt(index: Int): Long {
@@ -494,7 +494,7 @@ public inline fun LongArray.elementAt(index: Int): Long {
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun FloatArray.elementAt(index: Int): Float {
@@ -504,7 +504,7 @@ public inline fun FloatArray.elementAt(index: Int): Float {
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun DoubleArray.elementAt(index: Int): Double {
@@ -514,7 +514,7 @@ public inline fun DoubleArray.elementAt(index: Int): Double {
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun BooleanArray.elementAt(index: Int): Boolean {
@@ -524,7 +524,7 @@ public inline fun BooleanArray.elementAt(index: Int): Boolean {
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun CharArray.elementAt(index: Int): Char {
@@ -533,6 +533,8 @@ public inline fun CharArray.elementAt(index: Int): Char {
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> Array<out T>.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T {
@@ -541,6 +543,8 @@ public inline fun <T> Array<out T>.elementAtOrElse(index: Int, defaultValue: (In
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun ByteArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Byte): Byte {
@@ -549,6 +553,8 @@ public inline fun ByteArray.elementAtOrElse(index: Int, defaultValue: (Int) -> B
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun ShortArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Short): Short {
@@ -557,6 +563,8 @@ public inline fun ShortArray.elementAtOrElse(index: Int, defaultValue: (Int) ->
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun IntArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Int): Int {
@@ -565,6 +573,8 @@ public inline fun IntArray.elementAtOrElse(index: Int, defaultValue: (Int) -> In
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun LongArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Long): Long {
@@ -573,6 +583,8 @@ public inline fun LongArray.elementAtOrElse(index: Int, defaultValue: (Int) -> L
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun FloatArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Float): Float {
@@ -581,6 +593,8 @@ public inline fun FloatArray.elementAtOrElse(index: Int, defaultValue: (Int) ->
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun DoubleArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Double): Double {
@@ -589,6 +603,8 @@ public inline fun DoubleArray.elementAtOrElse(index: Int, defaultValue: (Int) ->
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun BooleanArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Boolean): Boolean {
@@ -597,6 +613,8 @@ public inline fun BooleanArray.elementAtOrElse(index: Int, defaultValue: (Int) -
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun CharArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Char): Char {
@@ -606,7 +624,7 @@ public inline fun CharArray.elementAtOrElse(index: Int, defaultValue: (Int) -> C
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> Array<out T>.elementAtOrNull(index: Int): T? {
@@ -616,7 +634,7 @@ public inline fun <T> Array<out T>.elementAtOrNull(index: Int): T? {
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun ByteArray.elementAtOrNull(index: Int): Byte? {
@@ -626,7 +644,7 @@ public inline fun ByteArray.elementAtOrNull(index: Int): Byte? {
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun ShortArray.elementAtOrNull(index: Int): Short? {
@@ -636,7 +654,7 @@ public inline fun ShortArray.elementAtOrNull(index: Int): Short? {
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun IntArray.elementAtOrNull(index: Int): Int? {
@@ -646,7 +664,7 @@ public inline fun IntArray.elementAtOrNull(index: Int): Int? {
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun LongArray.elementAtOrNull(index: Int): Long? {
@@ -656,7 +674,7 @@ public inline fun LongArray.elementAtOrNull(index: Int): Long? {
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun FloatArray.elementAtOrNull(index: Int): Float? {
@@ -666,7 +684,7 @@ public inline fun FloatArray.elementAtOrNull(index: Int): Float? {
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun DoubleArray.elementAtOrNull(index: Int): Double? {
@@ -676,7 +694,7 @@ public inline fun DoubleArray.elementAtOrNull(index: Int): Double? {
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun BooleanArray.elementAtOrNull(index: Int): Boolean? {
@@ -686,7 +704,7 @@ public inline fun BooleanArray.elementAtOrNull(index: Int): Boolean? {
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun CharArray.elementAtOrNull(index: Int): Char? {

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

@@ -70,7 +70,7 @@ public operator fun <@kotlin.internal.OnlyInputTypes T> Iterable<T>.contains(ele
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this collection.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 public fun <T> Iterable<T>.elementAt(index: Int): T {
     if (this is List)
@@ -81,7 +81,7 @@ public fun <T> Iterable<T>.elementAt(index: Int): T {
 /**
  * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this list.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> List<T>.elementAt(index: Int): T {
@@ -90,6 +90,8 @@ public inline fun <T> List<T>.elementAt(index: Int): T {
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this collection.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 public fun <T> Iterable<T>.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T {
     if (this is List)
@@ -108,6 +110,8 @@ public fun <T> Iterable<T>.elementAtOrElse(index: Int, defaultValue: (Int) -> T)
 
 /**
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this list.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> List<T>.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T {
@@ -117,7 +121,7 @@ public inline fun <T> List<T>.elementAtOrElse(index: Int, defaultValue: (Int) ->
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this collection.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 public fun <T> Iterable<T>.elementAtOrNull(index: Int): T? {
     if (this is List)
@@ -137,7 +141,7 @@ public fun <T> Iterable<T>.elementAtOrNull(index: Int): T? {
 /**
  * Returns an element at the given [index] or `null` if the [index] is out of bounds of this list.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> List<T>.elementAtOrNull(index: Int): T? {

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

@@ -32,7 +32,7 @@ public operator fun <@kotlin.internal.OnlyInputTypes T> Sequence<T>.contains(ele
  *
  * The operation is _terminal_.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 public fun <T> Sequence<T>.elementAt(index: Int): T {
     return elementAtOrElse(index) { throw IndexOutOfBoundsException("Sequence doesn't contain element at index $index.") }
@@ -42,6 +42,8 @@ public fun <T> Sequence<T>.elementAt(index: Int): T {
  * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this sequence.
  *
  * The operation is _terminal_.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 public fun <T> Sequence<T>.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T {
     if (index < 0)
@@ -61,7 +63,7 @@ public fun <T> Sequence<T>.elementAtOrElse(index: Int, defaultValue: (Int) -> T)
  *
  * The operation is _terminal_.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 public fun <T> Sequence<T>.elementAtOrNull(index: Int): T? {
     if (index < 0)

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

@@ -21,7 +21,7 @@ import kotlin.random.*
 /**
  * Returns a character at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this char sequence.
  * 
- * @sample samples.collections.Collections.Usage.elementAt
+ * @sample samples.collections.Collections.Elements.elementAt
  */
 @kotlin.internal.InlineOnly
 public inline fun CharSequence.elementAt(index: Int): Char {
@@ -30,6 +30,8 @@ public inline fun CharSequence.elementAt(index: Int): Char {
 
 /**
  * Returns a character at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this char sequence.
+ * 
+ * @sample samples.collections.Collections.Elements.elementAtOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun CharSequence.elementAtOrElse(index: Int, defaultValue: (Int) -> Char): Char {
@@ -39,7 +41,7 @@ public inline fun CharSequence.elementAtOrElse(index: Int, defaultValue: (Int) -
 /**
  * Returns a character at the given [index] or `null` if the [index] is out of bounds of this char sequence.
  * 
- * @sample samples.collections.Collections.Usage.elementAtOrNull
+ * @sample samples.collections.Collections.Elements.elementAtOrNull
  */
 @kotlin.internal.InlineOnly
 public inline fun CharSequence.elementAtOrNull(index: Int): Char? {

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

@@ -487,16 +487,16 @@ class Collections {
         }
     }
 
-    class Usage {
+    class Elements {
         @Sample
         fun elementAt() {
             val list = listOf(1, 2, 3)
             assertPrints(list.elementAt(0), "1")
             assertPrints(list.elementAt(2), "3")
-            assertFails { list.elementAt(3) }
+            assertFailsWith<IndexOutOfBoundsException> { list.elementAt(3) }
 
             val emptyList = emptyList<Int>()
-            assertFails { emptyList.elementAt(0) }
+            assertFailsWith<IndexOutOfBoundsException> { emptyList.elementAt(0) }
         }
 
         @Sample
@@ -509,5 +509,16 @@ class Collections {
             val emptyList = emptyList<Int>()
             assertPrints(emptyList.elementAtOrNull(0), "null")
         }
+
+        @Sample
+        fun elementAtOrElse() {
+            val list = listOf(1, 2, 3)
+            assertPrints(list.elementAtOrElse(0) { 42 }, "1")
+            assertPrints(list.elementAtOrElse(2) { 42 }, "3")
+            assertPrints(list.elementAtOrElse(3) { 42 }, "42")
+
+            val emptyList = emptyList<Int>()
+            assertPrints(emptyList.elementAtOrElse(0) { "no int" }, "no int")
+        }
     }
 }

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

@@ -242,7 +242,7 @@ object Elements : TemplateGroupBase() {
     } builder {
         val index = '$' + "index"
         doc { "Returns ${f.element.prefixWithArticle()} at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this ${f.collection}." }
-        sample("samples.collections.Collections.Usage.elementAt")
+        sample("samples.collections.Collections.Elements.elementAt")
         returns("T")
         body {
             """
@@ -269,6 +269,7 @@ object Elements : TemplateGroupBase() {
         include(CharSequences, Lists)
     } builder {
         doc { "Returns ${f.element.prefixWithArticle()} at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this ${f.collection}." }
+        sample("samples.collections.Collections.Elements.elementAtOrElse")
         returns("T")
         body {
             """
@@ -328,7 +329,7 @@ object Elements : TemplateGroupBase() {
         include(CharSequences, Lists)
     } builder {
         doc { "Returns ${f.element.prefixWithArticle()} at the given [index] or `null` if the [index] is out of bounds of this ${f.collection}." }
-        sample("samples.collections.Collections.Usage.elementAtOrNull")
+        sample("samples.collections.Collections.Elements.elementAtOrNull")
         returns("T?")
         body {
             """