diff --git a/README.md b/README.md index a90389f..56b5b6a 100644 --- a/README.md +++ b/README.md @@ -14,56 +14,15 @@ # KBox -KBox is a very small but useful utility library for Kotlin (JVM, Android and JS). +KBox is a very small but useful utility library for Kotlin (JVM, Android and JS) providing functions which are missing +in the stdlib such as: +- failIf +- takeIf +- blankToNull +- isNotNullAndNotEmpty +- identity -Current extension functions: -- [`Array/List/Iterable/Sequence.appendtoStringBuilder`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/appendToString.kt#L37) - with the ability to define a different separator for the last separation - => handy if you want to form sentences like `a, b and c` - -- [`CharSequence.blankToNull`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/blanktoNull.kt#L7) - returns the same `CharSequence` if not blank, `null` otherwise - -- [`forEachIn(Array/Iterable/Sequence, Array/Iterable/Sequence, ..., action: (E) -> Unit)`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/forEachIn.kt#L6) - applies the given action to each entry in the given `Iterable`s. - -- [` forElementAndEachIn(E, Array/Iterable/Sequence, action: (E) -> Unit)`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/forThisAndForEach.kt#L6) - applies the given action to `this` and each entry in Iterable - -- [`Iterable.forEachRemaining()`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/forEachRemaining.kt#L9) - shortcut for `while(hasNext()) yourLambda(next())` - -- [`Array/List.ifWithinBound`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/ifWithinBound.kt#L13) - shortcut for `if(index < size){ thenBlock() } else { elseBlock() }` - -- [`CharSequence?.isNotNullAndNotEmpty/isNotNullAndNotBlank`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/isNotNullAndNot.kt#L6) - -- [`Array/List/Iterable/Sequence.joinToString`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/joinToString.kt#L31) - with the ability to define a different separator for the last separation - => handy if you want to form sentences like `a, b and c` - -- [`Map.mapParents`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/mapParents.kt#L13) - maps child-parent relations. - -- [`Iterator.mapRemaining/mapRemainingWithCounter`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/mapRemaining.kt#L9) - maps remaining entries with the help of a transform function (where `mapRemainingWithCounter` passes a counter variable to the transform function). - -- [`Array/Iterable/Sequence.mapWithIndex`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/mapWithIndex.kt#L11) - -- [`Sequence.dynamicTraversal`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/dynamicTraversal.kt#L34) - allows to iterator over a tree/graph like structure lazily - -- [`Iterator.toPeekingIterator()`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/PeekingIteratorUnsynchronized.kt) - which allows to have a look what the next element is without consuming it. - -- [`varargsToList/glue`](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/varargToList.kt#L11) - creates a `List` out of a single `E` and an `Array`. - -- [takeIf](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/takeIf.kt#L12) - same behaviour as `takeIf` but as prefix operator and not postfix. - -Moreover, the following function might come in handy for you as well: -- [identity](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/identity.kt) +and more, see the [Documentation](#documentation) for a full list. # Installation @@ -72,13 +31,10 @@ KBox is published to maven central. ``` repositories { mavenCentral() } dependencies { - implementation("ch.tutteli.kbox:kbox-jvm:0.16.0") + implementation("ch.tutteli.kbox:kbox:0.16.0") } ``` -Accordingly, you can use `kbox-js` as artifactId instead of `kbox-jvm` -(or simply `kbox` in case of a MPP project in commonMain). - # Documentation Visit [https://robstoll.github.io/kbox/kdoc](https://robstoll.github.io/kbox/kdoc/). diff --git a/src/commonMain/kotlin/ch/tutteli/kbox/failIf.kt b/src/commonMain/kotlin/ch/tutteli/kbox/failIf.kt new file mode 100644 index 0000000..0c4fed9 --- /dev/null +++ b/src/commonMain/kotlin/ch/tutteli/kbox/failIf.kt @@ -0,0 +1,11 @@ +package ch.tutteli.kbox + +/** + * Delegates to [check] but inverting the [predicate], i.e. throws an [IllegalStateException] if predicate is true. + * + * @param predicate the predicate which defines if the exception should be thrown or not. + * @param errorMessage The message which as [IllegalStateException.message] + * + * @since 1.0.0 + */ +inline fun failIf(predicate: Boolean, errorMessage: () -> String) = check(predicate.not(), errorMessage) diff --git a/src/commonTest/kotlin/ch/tutteli/kbox/FailIfTest.kt b/src/commonTest/kotlin/ch/tutteli/kbox/FailIfTest.kt new file mode 100644 index 0000000..49aa8c5 --- /dev/null +++ b/src/commonTest/kotlin/ch/tutteli/kbox/FailIfTest.kt @@ -0,0 +1,24 @@ +package ch.tutteli.kbox + +import ch.tutteli.atrium.api.fluent.en_GB.messageToContain +import ch.tutteli.atrium.api.fluent.en_GB.notToThrow +import ch.tutteli.atrium.api.fluent.en_GB.toThrow +import ch.tutteli.kbox.atrium.expect +import kotlin.test.Test + +class FailIfTest { + @Test + fun it_throws_an_IllegalStateException_if_predicate_is_true() { + expect { + failIf(true) { "my message" } + }.toThrow { messageToContain("my message") } + } + + @Test + fun it_does_not_throw_if_predicate_holds() { + expect { + failIf(false) { throw UnsupportedOperationException("bla") } + }.notToThrow() + } +} +