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/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.