rename bigDecimalAssertion functions to new schema in api-infix

apis/infix-en_GB/atrium-api-infix-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/infix/en_GB/throwableExpectations.kt

@@ -17,6 +17,8 @@ import kotlin.reflect.KClass
  * so that you can mix [String] and [Int] for instance.
  *
  * @return an [Expect] for the subject of `this` expectation.
+ *
+ * @since 0.17.0
  */
 infix fun <T : Throwable> Expect<T>.messageToContain(expected: CharSequenceOrNumberOrChar): Expect<T> =
     this messageToContain values(expected)
@@ -32,6 +34,8 @@ infix fun <T : Throwable> Expect<T>.messageToContain(expected: CharSequenceOrNum
  *   -- use the function `values(t, ...)` to create a [Values].
  *
  * @return an [Expect] for the subject of `this` expectation.
+ *
+ * @since 0.17.0
  */
 infix fun <T : Throwable> Expect<T>.messageToContain(values: Values<Any>): Expect<T> =
     message { toContain(values) }

apis/infix-en_GB/atrium-api-infix-en_GB-jvm/src/main/kotlin/ch/tutteli/atrium/api/infix/en_GB/bigDecimalAssertions.kt

@@ -51,7 +51,8 @@ infix fun <T : BigDecimal?> Expect<T>.toBe(expected: T): Nothing =
  * Expects that the subject of `this` expectation (a [BigDecimal]) is `null`.
  *
  * @return an [Expect] for the subject of `this` expectation.
-
+ *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.deprecated.BigDecimalAssertionSamples.toBe
  */
 @JvmName("toBeNull")
 infix fun <T : BigDecimal> Expect<T?>.toBe(expected: Nothing?): Expect<T?> =

apis/infix-en_GB/atrium-api-infix-en_GB-jvm/src/main/kotlin/ch/tutteli/atrium/api/infix/en_GB/bigDecimalExpectations.kt

@@ -0,0 +1,172 @@
+@file:Suppress(
+    // TODO remove once https://youtrack.jetbrains.com/issue/KT-35343 is fixed
+    "JAVA_MODULE_DOES_NOT_READ_UNNAMED_MODULE"
+)
+
+package ch.tutteli.atrium.api.infix.en_GB
+
+import ch.tutteli.atrium.creating.Expect
+import ch.tutteli.atrium.creating.PleaseUseReplacementException
+import ch.tutteli.atrium.logic.*
+import java.math.BigDecimal
+
+/**
+ * Deprecated as it would compare the subject against [expected] including scale
+ * -- many developers are not aware of that.
+ *
+ * Use [toEqualNumerically] if you expect that the following assertion holds:
+ * ```
+ * expect(BigDecimal("10").toBe(BigDecimal("10.0"))
+ * ```
+ * However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use [toEqualIncludingScale].
+ *
+ * @since 0.17.0
+ */
+@Deprecated(
+    "Use `toEqualNumerically` if you expect that the following assertion holds:\n" +
+        "`expect(BigDecimal(\"10\")).toBe(BigDecimal(\"10.0\"))`\n" +
+        "However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use `toEqualIncludingScale`.",
+    ReplaceWith("toEqualNumerically(expected) or toEqualIncludingScale(expected)")
+)
+@Suppress("UNUSED_PARAMETER", "unused")
+infix fun <T : BigDecimal> Expect<T>.toEqual(expected: T): Nothing =
+    throw PleaseUseReplacementException(
+        "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" +
+            "If you know it and want that `scale` is included in the comparison, then use `toEqualIncludingScale`."
+    )
+
+/**
+ * Deprecated as it would compare the subject against [expected] including scale
+ * -- many developers are not aware of that.
+ *
+ * Use [toEqualNumerically] if you expect that the following assertion holds:
+ * ```
+ * expect(BigDecimal("10").toBe(BigDecimal("10.0"))
+ * ```
+ * However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use [toEqualIncludingScale].
+ *
+ * @since 0.17.0
+ */
+@Suppress("UNUSED_PARAMETER", "unused")
+@JvmName("toBeNullable")
+@Deprecated(
+    "Use `toEqualNumerically` if you expect that the following assertion holds:\n" +
+        "`expect(BigDecimal(\"10\")).toBe(BigDecimal(\"10.0\"))`\n" +
+        "However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use `toEqualIncludingScale`.",
+    ReplaceWith("toEqualNumerically(expected) or toEqualIncludingScale(expected)")
+)
+infix fun <T : BigDecimal?> Expect<T>.toEqual(expected: T): Nothing =
+    throw PleaseUseReplacementException(
+        "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" +
+            "If you know it and want that `scale` is included in the comparison, then use `toEqualIncludingScale`."
+    )
+
+/**
+ * Expects that the subject of `this` expectation (a [BigDecimal]) is `null`.
+ *
+ * @return an [Expect] for the subject of `this` expectation.
+ *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.BigDecimalExpectationSamples.toEqual
+ *
+ * @since 0.17.0
+ */
+@JvmName("toBeNull")
+infix fun <T : BigDecimal> Expect<T?>.toEqual(expected: Nothing?): Expect<T?> =
+    _logicAppend { toBe(expected) }
+
+/**
+ * Deprecated as it would compare the subject against [expected] including scale
+ * -- many developers are not aware of that.
+ *
+ * Use [isNotNumericallyEqualTo] if you expect that the following assertion is wrong:
+ * ```
+ * expect(BigDecimal("10").notToBe(BigDecimal("10.0"))
+ * ```
+ * However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use [notToEqualIncludingScale].
+ *
+ * @since 0.17.0
+ */
+@Deprecated(
+    "Use `isNotNumericallyEqualTo` if you expect that the following assertion is wrong:\n" +
+        "`expect(BigDecimal(\"10\")).notToBe(BigDecimal(\"10.0\"))`\n" +
+        "However, if you expect it to hold (because `BigDecimal.scale` differ), then use `notToEqualIncludingScale`.",
+    ReplaceWith("isNotNumericallyEqualTo(expected) or notToEqualIncludingScale(expected)")
+)
+@Suppress("UNUSED_PARAMETER", "unused")
+infix fun <T : BigDecimal> Expect<T>.notToEqual(expected: T): Nothing =
+    throw PleaseUseReplacementException(
+        "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" +
+            "If you know it and want that `scale` is included in the comparison, then use `notToEqualIncludingScale`."
+    )
+
+/**
+ * Expects that the subject of `this` expectation (a [BigDecimal]) is numerically equal to [expected].
+ *
+ * By numerically is meant that it will not compare [BigDecimal.scale] (or in other words,
+ * it uses `compareTo(expected) == 0`)
+ *
+ * Most of the time you want to use this function instead of [toEqualIncludingScale] because
+ * [toEqualIncludingScale] compares [BigDecimal.scale].
+ * Following the two functions compared:
+ * - `expect(BigDecimal("10")).toEqualIncludingScale(BigDecimal("10.0"))` does not hold.
+ * - `expect(BigDecimal("10")).toEqualNumerically(BigDecimal("10.0"))` holds.
+ *
+ * @return an [Expect] for the subject of `this` expectation.
+ *
+ * @since 0.17.0
+
+ */
+infix fun <T : BigDecimal> Expect<T>.toEqualNumerically(expected: T): Expect<T> =
+    _logicAppend { isNumericallyEqualTo(expected) }
+
+/**
+ * Expects that the subject of `this` expectation (a [BigDecimal]) is not numerically equal to [expected].
+ *
+ * By numerically is meant that it will not compare [BigDecimal.scale] (or in other words,
+ * it uses `compareTo(expected) != 0`)
+ *
+ * Most of the time you want to use this function instead of [notToEqualIncludingScale] because
+ * [notToEqualIncludingScale] compares [BigDecimal.scale].
+ * Following the two functions compared:
+ * - `expect(BigDecimal("10")).notToEqualIncludingScale(BigDecimal("10.0"))` holds.
+ * - `expect(BigDecimal("10")).notToEqualNumerically(BigDecimal("10.0"))`  does not hold.
+ *
+ * @return an [Expect] for the subject of `this` expectation.
+ *
+ * @since 0.17.0
+ */
+infix fun <T : BigDecimal> Expect<T>.notToEqualNumerically(expected: T): Expect<T> =
+    _logicAppend { isNotNumericallyEqualTo(expected) }
+
+
+/**
+ * Expects that the subject of `this` expectation (a [BigDecimal]) is equal to [expected] including [BigDecimal.scale].
+ *
+ * Most of the time you want to use [toEqualNumerically] which does not compare [BigDecimal.scale]
+ * in contrast to this function.
+ * Following the two functions compared:
+ * - `expect(BigDecimal("10")).toEqualIncludingScale(BigDecimal("10.0"))` does not hold.
+ * - `expect(BigDecimal("10")).toEqualNumerically(BigDecimal("10.0"))` holds.
+ *
+ * @return an [Expect] for the subject of `this` expectation.
+ *
+ * @since 0.17.0
+ */
+infix fun <T : BigDecimal> Expect<T>.toEqualIncludingScale(expected: T): Expect<T> =
+    _logicAppend { isEqualIncludingScale(expected, Expect<T>::toEqualNumerically.name) }
+
+/**
+ * Expects that the subject of `this` expectation (a [BigDecimal]) is not equal to [expected] including [BigDecimal.scale].
+ *
+ * Most of the time you want to use [notToEqualNumerically] which does not compare [BigDecimal.scale]
+ * in contrast to this function.
+ * Following the two functions compared:
+ * - `expect(BigDecimal("10")).notToEqualIncludingScale(BigDecimal("10.0"))` holds.
+ * - `expect(BigDecimal("10")).notToEqualNumerically(BigDecimal("10.0"))`  does not hold.
+ *
+ * @return an [Expect] for the subject of `this` expectation.
+ *
+ * @since 0.17.0
+ */
+infix fun <T : BigDecimal> Expect<T>.notToEqualIncludingScale(expected: T): Expect<T> =
+    _logicAppend { isNotEqualIncludingScale(expected) }

apis/infix-en_GB/atrium-api-infix-en_GB-jvm/src/test/kotlin/ch/tutteli/atrium/api/infix/en_GB/BigDecimalExpectationsSpec.kt

@@ -11,43 +11,43 @@ import java.math.BigDecimal
 
 class BigDecimalAssertionsSpec : Spek({
     include(object : BigDecimalExpectationsSpec(
-        fun1(Companion::toBeBigDecimal),
-        fun1(Companion::toBeNullable).withNullableSuffix(),
-        fun1(Companion::toBeNull).withNullableSuffix(),
+        fun1(Companion::toEqualBigDecimal),
+        fun1(Companion::toEqualNullable).withNullableSuffix(),
+        fun1(Companion::toEqualNull).withNullableSuffix(),
         Expect<Any>::toEqual,
-        fun1(Companion::notToBe),
+        fun1(Companion::notToEqual),
         Expect<Any>::notToEqual,
-        fun1(Companion::isNumericallyEqualTo),
-        fun1(Companion::isNotNumericallyEqualTo),
-        fun1(Companion::isEqualIncludingScale),
-        fun1(Companion::isNotEqualIncludingScale)
+        fun1(Companion::toEqualNumerically),
+        fun1(Companion::notToEqualNumerically),
+        fun1(Companion::toEqualIncludingScale),
+        fun1(Companion::notToEqualIncludingScale)
     ) {})
 
-    describe("fun toBe for BigDecimal? and subject is null") {
+    describe("fun toEqual for BigDecimal? and subject is null") {
         it("chooses the correct overload if `null` is passed, does not throw") {
-            expect(null as BigDecimal?) toBe null
+            expect(null as BigDecimal?) toEqual null
         }
     }
 }) {
 
     companion object {
         @Suppress("DEPRECATION")
-        fun toBeBigDecimal(expect: Expect<BigDecimal>, a: BigDecimal): Nothing = expect toBe a
+        fun toEqualBigDecimal(expect: Expect<BigDecimal>, a: BigDecimal): Nothing = expect toEqual a
 
         @Suppress("DEPRECATION")
-        fun toBeNullable(expect: Expect<BigDecimal?>, a: BigDecimal?): Nothing = expect toBe a
+        fun toEqualNullable(expect: Expect<BigDecimal?>, a: BigDecimal?): Nothing = expect toEqual a
 
-        fun toBeNull(expect: Expect<BigDecimal?>, nothing: Nothing?) = expect toBe nothing
+        fun toEqualNull(expect: Expect<BigDecimal?>, nothing: Nothing?) = expect toEqual nothing
 
         @Suppress("DEPRECATION")
-        fun notToBe(expect: Expect<BigDecimal>, a: BigDecimal): Nothing = expect notToBe a
+        fun notToEqual(expect: Expect<BigDecimal>, a: BigDecimal): Nothing = expect notToEqual a
 
-        fun isNumericallyEqualTo(expect: Expect<BigDecimal>, a: BigDecimal) = expect isNumericallyEqualTo a
+        fun toEqualNumerically(expect: Expect<BigDecimal>, a: BigDecimal) = expect toEqualNumerically a
 
-        fun isNotNumericallyEqualTo(expect: Expect<BigDecimal>, a: BigDecimal) = expect isNotNumericallyEqualTo a
+        fun notToEqualNumerically(expect: Expect<BigDecimal>, a: BigDecimal) = expect notToEqualNumerically a
 
-        fun isEqualIncludingScale(expect: Expect<BigDecimal>, a: BigDecimal) = expect isEqualIncludingScale a
+        fun toEqualIncludingScale(expect: Expect<BigDecimal>, a: BigDecimal) = expect toEqualIncludingScale a
 
-        fun isNotEqualIncludingScale(expect: Expect<BigDecimal>, a: BigDecimal) = expect isNotEqualIncludingScale a
+        fun notToEqualIncludingScale(expect: Expect<BigDecimal>, a: BigDecimal) = expect notToEqualIncludingScale a
     }
 }

apis/infix-en_GB/atrium-api-infix-en_GB-jvm/src/test/kotlin/ch/tutteli/atrium/api/infix/en_GB/samples/BigDecimalExpectationSamples.kt

@@ -0,0 +1,15 @@
+package ch.tutteli.atrium.api.infix.en_GB.samples
+
+import ch.tutteli.atrium.api.infix.en_GB.*
+import ch.tutteli.atrium.api.verbs.internal.expect
+import java.math.BigDecimal
+import kotlin.test.Test
+
+class BigDecimalExpectationSamples {
+
+    @Test
+    fun toEqual() {
+        // only use toEqual to check against null, otherwise use toEqualNumerically or toEqualIncludingScale
+        expect(null as BigDecimal?).toEqual(null)
+    }
+}