Improve isNullOrEmpty() extensions

- Annotate with SinceKotlin("1.3") and InlineOnly
- Add contract linking the receiver and the returned value
- Unify wording in docs
- Add sample for Map.isNullOrEmpty

#KT-23279

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

@@ -17,6 +17,7 @@
 package samples.collections
 
 import samples.*
+import kotlin.test.*
 
 
 @RunWith(Enclosed::class)
@@ -38,10 +39,10 @@ class Arrays {
             val nullArray: Array<Any>? = null
             assertTrue(nullArray.isNullOrEmpty())
 
-            val emptyArray = emptyArray<Any>()
+            val emptyArray: Array<Any>? = emptyArray<Any>()
             assertTrue(emptyArray.isNullOrEmpty())
 
-            val array = arrayOf('a', 'b', 'c')
+            val array: Array<Char>? = arrayOf('a', 'b', 'c')
             assertFalse(array.isNullOrEmpty())
         }
     }

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

@@ -106,6 +106,18 @@ class Maps {
             }
         }
 
+
+        @Sample
+        fun mapIsNullOrEmpty() {
+            val nullMap: Map<String, Any>? = null
+            assertTrue(nullMap.isNullOrEmpty())
+
+            val emptyMap: Map<String, Any>? = emptyMap<String, Any>()
+            assertTrue(emptyMap.isNullOrEmpty())
+
+            val map: Map<Char, Int>? = mapOf('a' to 1, 'b' to 2, 'c' to 3)
+            assertFalse(map.isNullOrEmpty())
+        }
     }
 
     class Filtering {

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

@@ -9,6 +9,8 @@
 
 package kotlin.collections
 
+import kotlin.internal.contracts.*
+
 
 /**
  * Returns a single list of all elements from all arrays in the given array.
@@ -39,7 +41,15 @@ public fun <T, R> Array<out Pair<T, R>>.unzip(): Pair<List<T>, List<R>> {
 }
 
 /**
- * Returns `true` if this array is null or empty.
+ * Returns `true` if this nullable array is either null or empty.
  * @sample samples.collections.Arrays.Usage.arrayIsNullOrEmpty
  */
-public fun Array<*>?.isNullOrEmpty(): Boolean = this == null || this.isEmpty()
+@SinceKotlin("1.3")
+@kotlin.internal.InlineOnly
+public inline fun Array<*>?.isNullOrEmpty(): Boolean {
+    contract {
+        returns(false) implies (this@isNullOrEmpty != null)
+    }
+
+    return this == null || this.isEmpty()
+}

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

@@ -170,9 +170,10 @@ public val <T> List<T>.lastIndex: Int
 public inline fun <T> Collection<T>.isNotEmpty(): Boolean = !isEmpty()
 
 /**
- * Returns `true` if the collection is null or if it is empty.
+ * Returns `true` if this nullable collection is either null or empty.
  * @sample samples.collections.Collections.Collections.collectionIsNullOrEmpty
  */
+@SinceKotlin("1.3")
 @kotlin.internal.InlineOnly
 public inline fun <T> Collection<T>?.isNullOrEmpty(): Boolean {
     contract {

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

@@ -8,6 +8,8 @@
 
 package kotlin.collections
 
+import kotlin.internal.contracts.*
+
 private object EmptyMap : Map<Any?, Nothing>, Serializable {
     private const val serialVersionUID: Long = 8246714829545688274
 
@@ -140,9 +142,19 @@ private const val INT_MAX_POWER_OF_TWO: Int = Int.MAX_VALUE / 2 + 1
 @kotlin.internal.InlineOnly
 public inline fun <K, V> Map<out K, V>.isNotEmpty(): Boolean = !isEmpty()
 
-/** Returns `true` if this map is null or empty. */
+/**
+ * Returns `true` if this nullable map is either null or empty.
+ * @sample samples.collections.Maps.Usage.mapIsNullOrEmpty
+ */
+@SinceKotlin("1.3")
 @kotlin.internal.InlineOnly
-public inline fun <K, V> Map<out K, V>?.isNullOrEmpty(): Boolean = this == null || isEmpty()
+public inline fun <K, V> Map<out K, V>?.isNullOrEmpty(): Boolean {
+    contract {
+        returns(false) implies (this@isNullOrEmpty != null)
+    }
+
+    return this == null || isEmpty()
+}
 
 /**
  * Returns the [Map] if its not `null`, or the empty [Map] otherwise.