KT-20357: Add getOrElse sample for Collections

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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.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.Arrays.Usage.getOrElse
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes

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

@@ -60,6 +60,30 @@ class Arrays {
             val sameArray = nonEmptyArray.ifEmpty { arrayOf(2) }
             assertTrue(nonEmptyArray === sameArray)
         }
+
+        @Sample
+        fun getOrElse() {
+            val emptyArray: Array<Any> = emptyArray()
+            assertPrints(emptyArray.getOrElse(0) { "default" }, "default")
+
+            val array = arrayOf(1)
+            assertPrints(array.getOrElse(0) { "default" }, "1")
+            assertPrints(array.getOrElse(-1) { "default" }, "default")
+
+            // arrays of primitive types
+            val intArray = intArrayOf(1, 2, 3)
+            assertPrints(intArray.getOrElse(0) { 0 }, "1")
+
+            val booleanArray = booleanArrayOf(true, false)
+            assertPrints(booleanArray.getOrElse(0) { false }, "true")
+
+            val charArray = charArrayOf('a', 'b', 'c')
+            assertPrints(charArray.getOrElse(0) { 'z' }, "a")
+
+            // arrays of unsigned types
+            val uIntArray = uintArrayOf(1u, 2u, 3u)
+            assertPrints(uIntArray.getOrElse(0) { 10u }, "1")
+        }
     }
 
     class Transformations {

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

@@ -1233,6 +1233,18 @@ 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")
+            assertPrints(list.getOrElse(-1) { 42 }, "42")
+
+            val emptyList = emptyList<Int>()
+            assertPrints(emptyList.getOrElse(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,13 @@ 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(
+            when (family) {
+                CharSequences, Lists -> "samples.collections.Collections.Elements.getOrElse"
+                ArraysOfObjects, ArraysOfPrimitives, ArraysOfUnsigned -> "samples.collections.Arrays.Usage.getOrElse"
+                else -> "samples.collections.Collections.Elements.getOrElse"
+            }
+        )
         returns("T")
         inlineOnly()
         val indices = if (family == Lists) "0..<size" else "indices"