ifEmpty and isBlank extensions

- Introduce ifEmpty extension for Collections, Maps, Arrays, Sequences
- Introduce ifEmpty and isBlank for CharSequences

#KT-15695 Fixed

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

@@ -45,6 +45,21 @@ class Arrays {
             val array: Array<Char>? = arrayOf('a', 'b', 'c')
             assertFalse(array.isNullOrEmpty())
         }
+
+        @Sample
+        fun arrayIfEmpty() {
+            val emptyArray: Array<Any> = emptyArray()
+
+            val emptyOrNull: Array<Any>? = emptyArray.ifEmpty { null }
+            assertPrints(emptyOrNull, "null")
+
+            val emptyOrDefault: Array<Any> = emptyArray.ifEmpty { arrayOf("default") }
+            assertPrints(emptyOrDefault.contentToString(), "[default]")
+
+            val nonEmptyArray = arrayOf(1)
+            val sameArray = nonEmptyArray.ifEmpty { arrayOf(2) }
+            assertTrue(nonEmptyArray === sameArray)
+        }
     }
 
     class Transformations {

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

@@ -63,6 +63,21 @@ class Collections {
             assertFalse(collection.isNullOrEmpty())
         }
 
+        @Sample
+        fun collectionIfEmpty() {
+            val empty: List<Int> = emptyList()
+
+            val emptyOrNull: List<Int>? = empty.ifEmpty { null }
+            assertPrints(emptyOrNull, "null")
+
+            val emptyOrDefault: List<Any> = empty.ifEmpty { listOf("default") }
+            assertPrints(emptyOrDefault, "[default]")
+
+            val nonEmpty = listOf("x")
+            val sameList: List<String> = nonEmpty.ifEmpty { listOf("empty") }
+            assertTrue(nonEmpty === sameList)
+        }
+
         @Sample
         fun collectionContainsAll() {
             val collection = mutableListOf('a', 'b')

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

@@ -118,6 +118,21 @@ class Maps {
             val map: Map<Char, Int>? = mapOf('a' to 1, 'b' to 2, 'c' to 3)
             assertFalse(map.isNullOrEmpty())
         }
+
+        @Sample
+        fun mapIfEmpty() {
+            val emptyMap: Map<String, Int> = emptyMap()
+
+            val emptyOrNull = emptyMap.ifEmpty { null }
+            assertPrints(emptyOrNull, "null")
+
+            val emptyOrDefault: Map<String, Any> = emptyMap.ifEmpty { mapOf("s" to "a") }
+            assertPrints(emptyOrDefault, "{s=a}")
+
+            val nonEmptyMap = mapOf("x" to 1)
+            val sameMap = nonEmptyMap.ifEmpty { null }
+            assertTrue(nonEmptyMap === sameMap)
+        }
     }
 
     class Filtering {

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

@@ -169,6 +169,19 @@ class Sequences {
             val sequence: Sequence<Int>? = sequenceOf(1, 2, 3)
             assertPrints(sequence.orEmpty().toList(), "[1, 2, 3]")
         }
+
+        @Sample
+        fun sequenceIfEmpty() {
+            val empty = emptySequence<Int>()
+
+            val emptyOrDefault = empty.ifEmpty { sequenceOf("default") }
+            assertPrints(emptyOrDefault.toList(), "[default]")
+
+            val nonEmpty = sequenceOf("value")
+
+            val nonEmptyOrDefault = nonEmpty.ifEmpty { sequenceOf("default") }
+            assertPrints(nonEmptyOrDefault.toList(), "[value]")
+        }
     }
 
     class Transformations {

libraries/stdlib/samples/test/samples/text/strings.kt

@@ -1,6 +1,7 @@
 package samples.text
 
 import samples.*
+import kotlin.test.assertTrue
 
 class Strings {
 
@@ -146,4 +147,33 @@ class Strings {
         assertPrints(builder, "")
     }
 
+    @Sample
+    fun stringIfEmpty() {
+        val empty = ""
+
+        val emptyOrNull: String? = empty.ifEmpty { null }
+        assertPrints(emptyOrNull, "null")
+
+        val emptyOrDefault = empty.ifEmpty { "default" }
+        assertPrints(emptyOrDefault, "default")
+
+        val nonEmpty = "abc"
+        val sameString = nonEmpty.ifEmpty { "def" }
+        assertTrue(nonEmpty === sameString)
+    }
+
+    @Sample
+    fun stringIfBlank() {
+        val blank = "    "
+
+        val blankOrNull: String? = blank.ifBlank { null }
+        assertPrints(blankOrNull, "null")
+
+        val blankOrDefault = blank.ifBlank { "default" }
+        assertPrints(blankOrDefault, "default")
+
+        val nonBlank = "abc"
+        val sameString = nonBlank.ifBlank { "def" }
+        assertTrue(nonBlank === sameString)
+    }
 }

libraries/stdlib/src/kotlin/collections/Arrays.kt

@@ -53,3 +53,15 @@ public inline fun Array<*>?.isNullOrEmpty(): Boolean {
 
     return this == null || this.isEmpty()
 }
+
+/**
+ * Returns this array if it's not empty
+ * or the result of calling [defaultValue] function if the array is empty.
+ *
+ * @sample samples.collections.Arrays.Usage.arrayIfEmpty
+ */
+@SinceKotlin("1.3")
+@kotlin.internal.InlineOnly
+@Suppress("UPPER_BOUND_CANNOT_BE_ARRAY")
+public inline fun <C, R> C.ifEmpty(defaultValue: () -> R): R where C : Array<*>, C : R =
+    if (isEmpty()) defaultValue() else this

libraries/stdlib/src/kotlin/collections/Collections.kt

@@ -197,6 +197,18 @@ public inline fun <T> Collection<T>?.orEmpty(): Collection<T> = this ?: emptyLis
 @kotlin.internal.InlineOnly
 public inline fun <T> List<T>?.orEmpty(): List<T> = this ?: emptyList()
 
+/**
+ * Returns this collection if it's not empty
+ * or the result of calling [defaultValue] function if the collection is empty.
+ *
+ * @sample samples.collections.Collections.Collections.collectionIfEmpty
+ */
+@SinceKotlin("1.3")
+@kotlin.internal.InlineOnly
+public inline fun <C, R> C.ifEmpty(defaultValue: () -> R): R where C : Collection<*>, C : R =
+    if (isEmpty()) defaultValue() else this
+
+
 /**
  * Checks if all elements in the specified collection are contained in this collection.
  *

libraries/stdlib/src/kotlin/collections/Maps.kt

@@ -162,6 +162,17 @@ public inline fun <K, V> Map<out K, V>?.isNullOrEmpty(): Boolean {
 @kotlin.internal.InlineOnly
 public inline fun <K, V> Map<K, V>?.orEmpty(): Map<K, V> = this ?: emptyMap()
 
+/**
+ * Returns this map if it's not empty
+ * or the result of calling [defaultValue] function if the map is empty.
+ *
+ * @sample samples.collections.Maps.Usage.mapIfEmpty
+ */
+@SinceKotlin("1.3")
+@kotlin.internal.InlineOnly
+public inline fun <M, R> M.ifEmpty(defaultValue: () -> R): R where M : Map<*, *>, M : R =
+    if (isEmpty()) defaultValue() else this
+
 /**
  * Checks if the map contains the given key.
  *

libraries/stdlib/src/kotlin/collections/Sequences.kt

@@ -9,6 +9,7 @@
 package kotlin.sequences
 
 import kotlin.*
+import kotlin.coroutines.experimental.buildSequence
 
 /**
  * Given an [iterator] function constructs a [Sequence] that returns values through the [Iterator]
@@ -55,6 +56,23 @@ private object EmptySequence : Sequence<Nothing>, DropTakeSequence<Nothing> {
 @kotlin.internal.InlineOnly
 public inline fun <T> Sequence<T>?.orEmpty(): Sequence<T> = this ?: emptySequence()
 
+
+/**
+ * Returns a sequence that iterates through the elements either of this sequence
+ * or, if this sequence turns out to be empty, of the sequence returned by [defaultValue] function.
+ *
+ * @sample samples.collections.Sequences.Usage.sequenceIfEmpty
+ */
+@SinceKotlin("1.3")
+public fun <T> Sequence<T>.ifEmpty(defaultValue: () -> Sequence<T>): Sequence<T> = buildSequence {
+    val iterator = this@ifEmpty.iterator()
+    if (iterator.hasNext()) {
+        yieldAll(iterator)
+    } else {
+        yieldAll(defaultValue())
+    }
+}
+
 /**
  * Returns a sequence of all elements from all sequences in this sequence.
  *

libraries/stdlib/src/kotlin/text/Strings.kt

@@ -276,6 +276,28 @@ public operator fun CharSequence.iterator(): CharIterator = object : CharIterato
 @kotlin.internal.InlineOnly
 public inline fun String?.orEmpty(): String = this ?: ""
 
+/**
+ * Returns this char sequence if it's not empty
+ * or the result of calling [defaultValue] function if the char sequence is empty.
+ *
+ * @sample samples.text.Strings.stringIfEmpty
+ */
+@SinceKotlin("1.3")
+@kotlin.internal.InlineOnly
+public inline fun <C, R> C.ifEmpty(defaultValue: () -> R): R where C : CharSequence, C : R =
+    if (isEmpty()) defaultValue() else this
+
+/**
+ * Returns this char sequence if it is not empty and doesn't consist solely of whitespace characters,
+ * or the result of calling [defaultValue] function otherwise.
+ *
+ * @sample samples.text.Strings.stringIfBlank
+ */
+@SinceKotlin("1.3")
+@kotlin.internal.InlineOnly
+public inline fun <C, R> C.ifBlank(defaultValue: () -> R): R where C : CharSequence, C : R =
+    if (isBlank()) defaultValue() else this
+
 /**
  * Returns the range of valid character indices for this char sequence.
  */

libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt

@@ -4486,6 +4486,7 @@ public final class kotlin/sequences/SequencesKt {
 	public static final fun groupByTo (Lkotlin/sequences/Sequence;Ljava/util/Map;Lkotlin/jvm/functions/Function1;)Ljava/util/Map;
 	public static final fun groupByTo (Lkotlin/sequences/Sequence;Ljava/util/Map;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)Ljava/util/Map;
 	public static final fun groupingBy (Lkotlin/sequences/Sequence;Lkotlin/jvm/functions/Function1;)Lkotlin/collections/Grouping;
+	public static final fun ifEmpty (Lkotlin/sequences/Sequence;Lkotlin/jvm/functions/Function0;)Lkotlin/sequences/Sequence;
 	public static final fun indexOf (Lkotlin/sequences/Sequence;Ljava/lang/Object;)I
 	public static final fun indexOfFirst (Lkotlin/sequences/Sequence;Lkotlin/jvm/functions/Function1;)I
 	public static final fun indexOfLast (Lkotlin/sequences/Sequence;Lkotlin/jvm/functions/Function1;)I