From 6bc7c060386d1777fb09241e07cf741740a9270c Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Tue, 12 Mar 2019 21:35:42 +0300
Subject: [PATCH] Add samples for is(|Not|NullOr)Empty and is(|Not|NullOr)Blank
 functions

---
 .../stdlib/jvm/src/kotlin/text/StringsJVM.kt  |  2 +
 .../samples/test/samples/text/strings.kt      | 77 ++++++++++++++++++-
 libraries/stdlib/src/kotlin/text/Strings.kt   | 10 +++
 3 files changed, 88 insertions(+), 1 deletion(-)

diff --git a/libraries/stdlib/jvm/src/kotlin/text/StringsJVM.kt b/libraries/stdlib/jvm/src/kotlin/text/StringsJVM.kt
index 0a9d375780f..d27bf1ae621 100644
--- a/libraries/stdlib/jvm/src/kotlin/text/StringsJVM.kt
+++ b/libraries/stdlib/jvm/src/kotlin/text/StringsJVM.kt
@@ -351,6 +351,8 @@ public inline fun String.intern(): String = (this as java.lang.String).intern()
 
 /**
  * Returns `true` if this string is empty or consists solely of whitespace characters.
+ *
+ * @sample samples.text.Strings.stringIsBlank
  */
 public actual fun CharSequence.isBlank(): Boolean = length == 0 || indices.all { this[it].isWhitespace() }
 
diff --git a/libraries/stdlib/samples/test/samples/text/strings.kt b/libraries/stdlib/samples/test/samples/text/strings.kt
index 97fbfb16ebf..f0fd8428a65 100644
--- a/libraries/stdlib/samples/test/samples/text/strings.kt
+++ b/libraries/stdlib/samples/test/samples/text/strings.kt
@@ -1,7 +1,7 @@
 package samples.text
 
 import samples.*
-import kotlin.test.assertTrue
+import kotlin.test.*
 
 class Strings {
 
@@ -177,6 +177,81 @@ class Strings {
         assertTrue(nonBlank === sameString)
     }
 
+    @Sample
+    fun stringIsBlank() {
+        fun validateName(name: String): String {
+            if (name.isBlank()) throw IllegalArgumentException("Name cannot be blank")
+            return name
+        }
+
+        assertPrints(validateName("Adam"), "Adam")
+        assertFails { validateName("") }
+        assertFails { validateName("  \t\n") }
+    }
+
+    @Sample
+    fun stringIsNotBlank() {
+        fun validateName(name: String): String {
+            require(name.isNotBlank()) { "Name cannot be blank" }
+            return name
+        }
+
+        assertPrints(validateName("Adam"), "Adam")
+        assertFails { validateName("") }
+        assertFails { validateName("  \t\n") }
+    }
+
+    @Sample
+    fun stringIsNullOrBlank() {
+        fun validateName(name: String?): String {
+            if (name.isNullOrBlank()) throw IllegalArgumentException("Name cannot be blank")
+            // name is not nullable here anymore due to a smart cast after calling isNullOrBlank
+            return name
+        }
+
+        assertPrints(validateName("Adam"), "Adam")
+        assertFails { validateName(null) }
+        assertFails { validateName("") }
+        assertFails { validateName("  \t\n") }
+    }
+
+    @Sample
+    fun stringIsEmpty() {
+        fun markdownLink(title: String, url: String) =
+            if (title.isEmpty()) url else "[$title]($url)"
+
+        // plain link
+        assertPrints(markdownLink(title = "", url = "https://kotlinlang.org"), "https://kotlinlang.org")
+
+        // link with custom title
+        assertPrints(markdownLink(title = "Kotlin Language", url = "https://kotlinlang.org"), "[Kotlin Language](https://kotlinlang.org)")
+    }
+
+    @Sample
+    fun stringIsNotEmpty() {
+        fun markdownLink(title: String, url: String) =
+            if (title.isNotEmpty()) "[$title]($url)" else url
+
+        // plain link
+        assertPrints(markdownLink(title = "", url = "https://kotlinlang.org"), "https://kotlinlang.org")
+
+        // link with custom title
+        assertPrints(markdownLink(title = "Kotlin Language", url = "https://kotlinlang.org"), "[Kotlin Language](https://kotlinlang.org)")
+    }
+
+
+    @Sample
+    fun stringIsNullOrEmpty() {
+        fun markdownLink(title: String?, url: String) =
+            if (title.isNullOrEmpty()) url else "[$title]($url)"
+
+        // plain link
+        assertPrints(markdownLink(title = null, url = "https://kotlinlang.org"), "https://kotlinlang.org")
+
+        // link with custom title
+        assertPrints(markdownLink(title = "Kotlin Language", url = "https://kotlinlang.org"), "[Kotlin Language](https://kotlinlang.org)")
+    }
+
     @Sample
     fun commonPrefixWith() {
         assertPrints("Hot_Coffee".commonPrefixWith("Hot_cocoa"), "Hot_")
diff --git a/libraries/stdlib/src/kotlin/text/Strings.kt b/libraries/stdlib/src/kotlin/text/Strings.kt
index e679260d4c2..7a8a10369de 100644
--- a/libraries/stdlib/src/kotlin/text/Strings.kt
+++ b/libraries/stdlib/src/kotlin/text/Strings.kt
@@ -213,6 +213,8 @@ public fun String.padEnd(length: Int, padChar: Char = ' '): String =
 
 /**
  * Returns `true` if this nullable char sequence is either `null` or empty.
+ *
+ * @sample samples.text.Strings.stringIsNullOrEmpty
  */
 @kotlin.internal.InlineOnly
 public inline fun CharSequence?.isNullOrEmpty(): Boolean {
@@ -225,12 +227,16 @@ public inline fun CharSequence?.isNullOrEmpty(): Boolean {
 
 /**
  * Returns `true` if this char sequence is empty (contains no characters).
+ *
+ * @sample samples.text.Strings.stringIsEmpty
  */
 @kotlin.internal.InlineOnly
 public inline fun CharSequence.isEmpty(): Boolean = length == 0
 
 /**
  * Returns `true` if this char sequence is not empty.
+ *
+ * @sample samples.text.Strings.stringIsNotEmpty
  */
 @kotlin.internal.InlineOnly
 public inline fun CharSequence.isNotEmpty(): Boolean = length > 0
@@ -241,12 +247,16 @@ public inline fun CharSequence.isNotEmpty(): Boolean = length > 0
 
 /**
  * Returns `true` if this char sequence is not empty and contains some characters except of whitespace characters.
+ *
+ * @sample samples.text.Strings.stringIsNotBlank
  */
 @kotlin.internal.InlineOnly
 public inline fun CharSequence.isNotBlank(): Boolean = !isBlank()
 
 /**
  * Returns `true` if this nullable char sequence is either `null` or empty or consists solely of whitespace characters.
+ *
+ * @sample samples.text.Strings.stringIsNullOrBlank
  */
 @kotlin.internal.InlineOnly
 public inline fun CharSequence?.isNullOrBlank(): Boolean {