simplified the test cases for the preconditions and add them to the API docs; also added requireNotNull() and checkNotNull() helper methods for converting nullables to non-nullables easily in code with optional exception messages

libraries/stdlib/src/kotlin/Preconditions.kt

@@ -6,98 +6,103 @@ object Assertions {
 }
 
 /**
- * Throws an [[AssertionError]] if the `value` is false and runtime assertions have been
- * enabled on the JVM using the `-ea` JVM option.
+* Throws an [[AssertionError]] with specified *message* if the *value* is false
+* and runtime assertions have been enabled on the JVM using the *-ea* JVM option.
+*/
+public inline fun assert(value: Boolean, message: Any = "Assertion failed") {
+    if (Assertions._ENABLED) {
+        if (!value) {
+            throw AssertionError(message)
+        }
+    }
+}
+
+/**
+ * Throws an [[AssertionError]] with specified *message* if the *value* is false
+ * and runtime assertions have been enabled on the JVM using the *-ea* JVM option.
  */
-public inline fun assert(value: Boolean): Unit {
-    if(Assertions._ENABLED) {
-        if(!value) {
-            throw AssertionError();
-        }
-    }
-}
-
-/**
-* Throws an [[AssertionError]] with specified `message` if the `value` is false
-* and runtime assertions have been enabled on the JVM using the `-ea` JVM option.
-*/
-public inline fun assert(value: Boolean, message: Any) {
-    if(Assertions._ENABLED) {
-        if(!value) {
-            throw AssertionError(message);
-        }
-    }
-}
-
-/**
-* Throws an [[AssertionError]] with specified `message` if the `value` is false
-* and runtime assertions have been enabled on the JVM using the `-ea` JVM option.
-*/
 public inline fun assert(value: Boolean, lazyMessage: () -> String) {
-    if(Assertions._ENABLED) {
-        if(!value) {
+    if (Assertions._ENABLED) {
+        if (!value) {
             val message = lazyMessage()
-            throw AssertionError(message);
+            throw AssertionError(message)
         }
     }
 }
 
 /**
- * Throws an [[IllegalArgumentException]] if the `value` is false.
+ * Throws an [[IllegalArgumentException]] with specified *message* if the *value* is false.
+ *
+ * @includeFunctionBody ../../test/PreconditionsTest.kt failingRequireWithMessage
  */
-public inline fun require(value: Boolean): Unit {
-    if(!value) {
-        throw IllegalArgumentException();
+public inline fun require(value: Boolean, message: Any = "Failed requirement"): Unit {
+    if (!value) {
+        throw IllegalArgumentException(message.toString())
     }
 }
 
 /**
- * Throws an [[IllegalArgumentException]] with specified `message` if the `value` is false.
- */
-public inline fun require(value: Boolean, message: Any): Unit {
-    if(!value) {
-        throw IllegalArgumentException(message.toString());
-    }
-}
-
-/**
- * Throws an [[IllegalArgumentException]] with specified `message` if the `value` is false.
+ * Throws an [[IllegalArgumentException]] with specified *message* if the *value* is false.
+ *
+ * @includeFunctionBody ../../test/PreconditionsTest.kt failingRequireWithLazyMessage
  */
 public inline fun require(value: Boolean, lazyMessage: () -> String): Unit {
-    if(!value) {
+    if (!value) {
         val message = lazyMessage()
-        throw IllegalArgumentException(message.toString());
+        throw IllegalArgumentException(message.toString())
     }
 }
 
 /**
- * Throws an [[IllegalStateException]] if the `value` is false.
+ * Throws an [[IllegalArgumentException]] with the given *message* if the *value* is null otherwise
+ * the not null value is returned.
+ *
+ *  @includeFunctionBody ../../test/PreconditionsTest.kt requireNotNull
  */
-public inline fun check(value: Boolean): Unit {
-    if(!value) {
-        throw IllegalStateException();
+public inline fun <T> requireNotNull(value: T?, message: Any = "Required value was null"): T {
+    if (value == null) {
+        throw IllegalArgumentException(message.toString())
+    } else {
+        return value
     }
 }
 
 /**
- * Throws an [[IllegalStateException]] with specified `message` if the `value` is false.
+ * Throws an [[IllegalStateException]] with specified *message* if the *value* is false.
+ *
+ * @includeFunctionBody ../../test/PreconditionsTest.kt failingCheckWithMessage
  */
-public inline fun check(value: Boolean, message: Any): Unit {
-    if(!value) {
-        throw IllegalStateException(message.toString());
+public inline fun check(value: Boolean, message: Any = "Check failed"): Unit {
+    if (!value) {
+        throw IllegalStateException(message.toString())
     }
 }
 
-
-
 /**
- * Throws an [[IllegalStateException]] with specified `message` if the `value` is false.
+ * Throws an [[IllegalStateException]] with specified *message* if the *value* is false.
+ *
+ * @includeFunctionBody ../../test/PreconditionsTest.kt failingCheckWithMessage
  */
 public inline fun check(value: Boolean, lazyMessage: () -> String): Unit {
-    if(!value) {
+    if (!value) {
         val message = lazyMessage()
-        throw IllegalStateException(message.toString());
+        throw IllegalStateException(message.toString())
+    }
+}
+
+/**
+ * Throws an [[IllegalStateException]] with the given *message* if the *value* is null otherwise
+ * the not null value is returned.
+ *
+ *  @includeFunctionBody ../../test/PreconditionsTest.kt checkNotNull
+ */
+public inline fun <T> checkNotNull(value: T?, message: String = "Required value was null"): T {
+    if (value == null) {
+        throw IllegalStateException(message)
+    } else {
+        return value
     }
 }
 
 
+

libraries/stdlib/src/kotlin/test/Test.kt

@@ -63,8 +63,9 @@ public inline fun assertEquals(expected: Any?, actual: Any?, message: String = "
 }
 
 /** Asserts that the expression is not null, with an optional message */
-public inline fun assertNotNull(actual: Any?, message: String = "") {
+public inline fun <T> assertNotNull(actual: T?, message: String = ""): T {
     asserter.assertNotNull(message, actual)
+    return actual!!
 }
 
 /** Asserts that the expression is not null, with an optional message and a function block to process the not-null value */