From 18672c99caf692290802433963af89baebae02f0 Mon Sep 17 00:00:00 2001
From: Yuya Urano <yuyaurano@me.com>
Date: Fri, 30 Oct 2020 08:15:48 +0900
Subject: [PATCH] KT-20357: Add a sample for requireNotNull

---
 .../test/samples/misc/preconditions.kt        | 25 +++++++++++++++++++
 .../stdlib/src/kotlin/util/Preconditions.kt   |  2 +-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/libraries/stdlib/samples/test/samples/misc/preconditions.kt b/libraries/stdlib/samples/test/samples/misc/preconditions.kt
index 8bd1a057fb9..be1943f1866 100644
--- a/libraries/stdlib/samples/test/samples/misc/preconditions.kt
+++ b/libraries/stdlib/samples/test/samples/misc/preconditions.kt
@@ -27,6 +27,31 @@ class Preconditions {
         assertPrints(getIndices(3), "[1, 2, 3]")
     }
 
+    @Sample
+    fun failRequireNotNullWithLazyMessage() {
+
+        fun printRequiredParam(params: Map<String, String?>) {
+            val required: String = requireNotNull(params["required"]) { "Required value must be non-null" } // returns a non-null value
+            println(required)
+            // ...
+        }
+
+        fun printRequiredParamByUpperCase(params: Map<String, String?>) {
+            val requiredParam: String? = params["required"]
+            requireNotNull(requiredParam) { "Required value must be non-null" }
+            // now requiredParam is smartcast to String so that it is unnecessary to use the safe call(?.)
+            println(requiredParam.toUpperCase())
+        }
+
+        val params: MutableMap<String, String?> = mutableMapOf("required" to null)
+        assertFailsWith<IllegalArgumentException> { printRequiredParam(params) }
+        assertFailsWith<IllegalArgumentException> { printRequiredParamByUpperCase(params) }
+
+        params["required"] = "non-empty-param"
+        printRequiredParam(params) // prints "non-empty-param"
+        printRequiredParamByUpperCase(params) // prints "NON-EMPTY-PARAM"
+    }
+
     @Sample
     fun failCheckWithLazyMessage() {
 
diff --git a/libraries/stdlib/src/kotlin/util/Preconditions.kt b/libraries/stdlib/src/kotlin/util/Preconditions.kt
index 7190100a645..84a4741e628 100644
--- a/libraries/stdlib/src/kotlin/util/Preconditions.kt
+++ b/libraries/stdlib/src/kotlin/util/Preconditions.kt
@@ -54,7 +54,7 @@ public inline fun <T : Any> requireNotNull(value: T?): T {
  * Throws an [IllegalArgumentException] with the result of calling [lazyMessage] if the [value] is null. Otherwise
  * returns the not null value.
  *
- * @sample samples.misc.Preconditions.failRequireWithLazyMessage
+ * @sample samples.misc.Preconditions.failRequireNotNullWithLazyMessage
  */
 @kotlin.internal.InlineOnly
 public inline fun <T : Any> requireNotNull(value: T?, lazyMessage: () -> Any): T {