KT-20357: Add a sample for the collections package

Author: hondaya14

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

@@ -1467,6 +1467,8 @@ public inline fun CharArray.firstOrNull(predicate: (Char) -> Boolean): 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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> Array<out T>.getOrElse(index: Int, defaultValue: (Int) -> T): T {
@@ -1478,6 +1480,8 @@ public inline fun <T> Array<out T>.getOrElse(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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun ByteArray.getOrElse(index: Int, defaultValue: (Int) -> Byte): Byte {
@@ -1489,6 +1493,8 @@ public inline fun ByteArray.getOrElse(index: Int, defaultValue: (Int) -> Byte):
 
 /**
  * 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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun ShortArray.getOrElse(index: Int, defaultValue: (Int) -> Short): Short {
@@ -1500,6 +1506,8 @@ public inline fun ShortArray.getOrElse(index: Int, defaultValue: (Int) -> Short)
 
 /**
  * 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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun IntArray.getOrElse(index: Int, defaultValue: (Int) -> Int): Int {
@@ -1511,6 +1519,8 @@ public inline fun IntArray.getOrElse(index: Int, defaultValue: (Int) -> 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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun LongArray.getOrElse(index: Int, defaultValue: (Int) -> Long): Long {
@@ -1522,6 +1532,8 @@ public inline fun LongArray.getOrElse(index: Int, defaultValue: (Int) -> Long):
 
 /**
  * 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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun FloatArray.getOrElse(index: Int, defaultValue: (Int) -> Float): Float {
@@ -1533,6 +1545,8 @@ public inline fun FloatArray.getOrElse(index: Int, defaultValue: (Int) -> Float)
 
 /**
  * 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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun DoubleArray.getOrElse(index: Int, defaultValue: (Int) -> Double): Double {
@@ -1544,6 +1558,8 @@ public inline fun DoubleArray.getOrElse(index: Int, defaultValue: (Int) -> Doubl
 
 /**
  * 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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun BooleanArray.getOrElse(index: Int, defaultValue: (Int) -> Boolean): Boolean {
@@ -1555,6 +1571,8 @@ public inline fun BooleanArray.getOrElse(index: Int, defaultValue: (Int) -> Bool
 
 /**
  * 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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun CharArray.getOrElse(index: Int, defaultValue: (Int) -> Char): Char {

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

@@ -298,6 +298,8 @@ public inline fun <T> Iterable<T>.firstOrNull(predicate: (T) -> Boolean): 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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> List<T>.getOrElse(index: Int, defaultValue: (Int) -> T): T {

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

@@ -133,6 +133,8 @@ public inline fun CharSequence.firstOrNull(predicate: (Char) -> Boolean): 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.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun CharSequence.getOrElse(index: Int, defaultValue: (Int) -> Char): Char {

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

@@ -737,6 +737,8 @@ public inline fun UShortArray.firstOrNull(predicate: (UShort) -> Boolean): UShor
 
 /**
  * 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.getOrElse
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -750,6 +752,8 @@ public inline fun UIntArray.getOrElse(index: Int, defaultValue: (Int) -> UInt):
 
 /**
  * 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.getOrElse
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -763,6 +767,8 @@ public inline fun ULongArray.getOrElse(index: Int, defaultValue: (Int) -> ULong)
 
 /**
  * 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.getOrElse
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -776,6 +782,8 @@ public inline fun UByteArray.getOrElse(index: Int, defaultValue: (Int) -> UByte)
 
 /**
  * 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.getOrElse
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes

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

@@ -1233,6 +1233,17 @@ class Collections {
             assertPrints(lastEven, "6")
         }
 
+        @Sample
+        fun getOrElse() {
+            val list = listOf(1, 2, 3)
+            assertPrints(list.getOrElse(0) { 42 }, "1")
+            assertPrints(list.getOrElse(2) { 42 }, "3")
+            assertPrints(list.getOrElse(3) { 42 }, "42")
+
+            val emptyList = emptyList<Int>()
+            assertPrints(emptyList.elementAtOrElse(0) { "no int" }, "no int")
+        }
+
         @Sample
         fun getOrNull() {
             val list = listOf(1, 2, 3)

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

@@ -402,6 +402,7 @@ object Elements : TemplateGroupBase() {
         include(CharSequences, Lists, ArraysOfObjects, ArraysOfPrimitives, ArraysOfUnsigned)
     } 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.getOrElse")
         returns("T")
         inlineOnly()
         val indices = if (family == Lists) "0..<size" else "indices"