KT-20357: Add a sample for requireNotNull

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() {