How to use Matcher.invertIf method of io.kotest.matchers.internal class

1package io.kotest.matchers2import io.kotest.matchers.MatcherResult.Companion.invoke3/**4 * A [Matcher] is the main abstraction in the assertions library.5 *6 * Implementations contain a single function, called 'test', which7 * accepts a value of type T and returns an instance of [MatcherResult].8 * This [MatcherResult] return value contains the state of the assertion9 * after it has been evaluated.10 *11 * A matcher will typically be invoked when used with the `should`12 * functions in the assertions DSL. For example, `2 should beLessThan(4)`13 *14 */15interface Matcher<in T> {16   fun test(value: T): MatcherResult17   infix fun <U> contramap(f: (U) -> T): Matcher<U> = Matcher { this@Matcher.test(f(it)) }18   fun invert(): Matcher<T> = Matcher {19      with(test(it)) {20         MatcherResult(!passed(), { negatedFailureMessage() }, { failureMessage() })21      }22   }23   fun <T> Matcher<T>.invertIf(invert: Boolean): Matcher<T> = if (invert) invert() else this24   @Deprecated("Use contramap. Deprecated in 5.3", ReplaceWith("contramap(fn)"))25   infix fun <U> compose(fn: (U) -> T): Matcher<U> = Matcher { this@Matcher.test(fn(it)) }26   companion object {27      /**28       * Returns a [Matcher] for type T that will always fail with the given [error] message.29       */30      fun <T> failure(error: String) = Matcher<T> { invoke(false, { error }, { "" }) }31      /**32       * Create matcher with the given function to evaluate the value and return a MatcherResult33       *34       * @param tester The function that evaluates a value and returns a MatcherResult35       */36      inline operator fun <T> invoke(crossinline tester: (T) -> MatcherResult) = object : Matcher<T> {37         override fun test(value: T) = tester(value)38      }39   }40}41infix fun <T> Matcher<T>.and(other: Matcher<T>): Matcher<T> = Matcher {42   test(it)43      .takeUnless(MatcherResult::passed)44      ?: other.test(it)45}46infix fun <T> Matcher<T>.or(other: Matcher<T>): Matcher<T> = Matcher {47   test(it)48      .takeIf(MatcherResult::passed)49      ?: other.test(it)50}51/**52 * A [Matcher] that asserts that the value is not `null` before performing the test.53 *54 * The matcher returned by [invert] will _also_ assert that the value is not `null`. Use this for matchers that55 * should fail on `null` values, whether called with `should` or `shouldNot`.56 */57internal abstract class NeverNullMatcher<T : Any?> : Matcher<T?> {58   final override fun test(value: T?): MatcherResult {59      return if (value == null) invoke(false, { "Expecting actual not to be null" }, { "" })60      else testNotNull(value)61   }62   override fun invert(): Matcher<T?> = object : NeverNullMatcher<T?>() {63      override fun testNotNull(value: T?): MatcherResult {64         if (value == null) return invoke(false, { "Expecting actual not to be null" }, { "" })65         val result = this@NeverNullMatcher.testNotNull(value)66         return invoke(!result.passed(), { result.negatedFailureMessage() }, { result.failureMessage() })67      }68   }69   abstract fun testNotNull(value: T): MatcherResult70   companion object {71      /**72       * Create matcher with the given function to evaluate the value and return a MatcherResult73       *74       * @param tester The function that evaluates a value and returns a MatcherResult75       */76      inline operator fun <T : Any> invoke(crossinline tester: (T) -> MatcherResult) = object : NeverNullMatcher<T>() {77         override fun testNotNull(value: T) = tester(value)78      }79   }80}81fun <T : Any> neverNullMatcher(t: (T) -> MatcherResult): Matcher<T?> {82   return object : NeverNullMatcher<T>() {83      override fun testNotNull(value: T): MatcherResult {84         return t(value)85      }86   }87}88/**89 * An instance of [MatcherResult] contains the result of an evaluation of a [Matcher].90 */91interface MatcherResult {92   /**93    * Returns true if the matcher indicated this was a valid94    * value and false if the matcher indicated an invalid value.95    */96   fun passed(): Boolean97   /**98    * Returns a message indicating why the matcher failed for when this matcher99    * is used in the positive sense. For example, if a size matcher was used100    * like `mylist should haveSize(5)` then an appropriate error message would101    * be "list should be size 5".102    */103   fun failureMessage(): String104   /**105    * Returns a message indicating why the matcher failed for when this matcher106    * is used in the negative sense. For example, if a size matcher was used107    * like `mylist shouldNot haveSize(5)` then an appropriate negated failure108    * would be "List should not have size 5".109    */110   fun negatedFailureMessage(): String111   companion object {112      @Deprecated(113         "Prefer the version that accepts functions - this avoids eager creation of messages. This was deprecated in 5.0.",114         ReplaceWith(115            "MatcherResult(\npassed,\n{ failureMessage },\n{ negatedFailureMessage }\n)"116         )117      )118      operator fun invoke(119         passed: Boolean,120         failureMessage: String,121         negatedFailureMessage: String122      ) = invoke(passed, { failureMessage }, { negatedFailureMessage })123      operator fun invoke(124         passed: Boolean,125         failureMessageFn: () -> String,126         negatedFailureMessageFn: () -> String127      ) = object : MatcherResult {128         override fun passed(): Boolean = passed129         override fun failureMessage(): String = failureMessageFn()130         override fun negatedFailureMessage(): String = negatedFailureMessageFn()131      }132   }133}134interface ComparableMatcherResult : MatcherResult {135   fun actual(): String136   fun expected(): String137   companion object {138      operator fun invoke(139         passed: Boolean,140         failureMessageFn: () -> String,141         negatedFailureMessageFn: () -> String,142         actual: String,143         expected: String,144      ) = object : ComparableMatcherResult {145         override fun passed(): Boolean = passed146         override fun failureMessage(): String = failureMessageFn()147         override fun negatedFailureMessage(): String = negatedFailureMessageFn()148         override fun actual(): String = actual149         override fun expected(): String = expected150      }151   }152}...