feat(core): implement divRem

This is an optimisation on JVM & native.

Author: ObserverOfTime

kbigint/src/androidMain/kotlin/io/github/observeroftime/kbigint/KBigInt.kt

@@ -98,6 +98,18 @@ actual class KBigInt private constructor(private var value: BigInteger) : Compar
     /** Perform a bitwise `XOR` operation. */
     actual infix fun xor(other: KBigInt) = KBigInt(value xor other.value)
 
+    /**
+     * Divide two [KBigInt] values and include the remainder.
+     *
+     * @since 0.5.0
+     * @return a `(quotient, remainder)` pair
+     */
+    @JvmName("divideAndRemainder")
+    actual fun divRem(other: KBigInt): Pair<KBigInt, KBigInt> {
+        val (quotient, remainder) = value.divideAndRemainder(other.value)
+        return Pair(KBigInt(quotient), KBigInt(remainder))
+    }
+
     /**
      * Find the (absolute) GCD of two [KBigInt] values.
      *

kbigint/src/androidUnitTest/kotlin/io/github/observeroftime/kbigint/KBigIntTest.kt

@@ -42,6 +42,8 @@ actual class KBigIntTest {
         assertEquals(KBigInt("19807040628566084398385987584"), string * long)
         assertEquals(KBigInt(4294967296L), string / long)
         assertEquals(KBigInt(0), string % long)
+
+        assertEquals(Pair(KBigInt(4294967296L), KBigInt(0)), string.divRem(long))
     }
 
     @Test

kbigint/src/commonMain/kotlin/io/github/observeroftime/kbigint/KBigInt.kt

@@ -75,6 +75,14 @@ expect class KBigInt : Comparable<KBigInt> {
     /** Perform a bitwise `XOR` operation. */
     infix fun xor(other: KBigInt): KBigInt
 
+    /**
+     * Divide two [KBigInt] values and include the remainder.
+     *
+     * @since 0.5.0
+     * @return a `(quotient, remainder)` pair
+     */
+    fun divRem(other: KBigInt): Pair<KBigInt, KBigInt>
+
     /**
      * Find the (absolute) GCD of two [KBigInt] values.
      *

kbigint/src/jsMain/kotlin/io/github/observeroftime/kbigint/KBigInt.kt

@@ -135,6 +135,22 @@ actual class KBigInt private constructor(@JsExternalArgument private var value:
         return KBigInt(js("a ^ b").unsafeCast<BigInt>())
     }
 
+    /**
+     * Divide two [KBigInt] values and include the remainder.
+     *
+     * @since 0.5.0
+     * @return a `(quotient, remainder)` pair
+     */
+    @JsName("_divideAndRemainder")
+    @Suppress("NON_EXPORTABLE_TYPE")
+    actual fun divRem(other: KBigInt): Pair<KBigInt, KBigInt> {
+        val a = this.value
+        val b = other.value
+        val quotient = js("a / b").unsafeCast<BigInt>()
+        val remainder = js("a % b").unsafeCast<BigInt>()
+        return Pair(KBigInt(quotient), KBigInt(remainder))
+    }
+
     /**
      * Find the (absolute) GCD of two [KBigInt] values.
      *

kbigint/src/jsTest/kotlin/io/github/observeroftime/kbigint/KBigIntTest.kt

@@ -43,6 +43,8 @@ actual class KBigIntTest {
         assertEquals(KBigInt("19807040628566084398385987584"), string * long)
         assertEquals(KBigInt(4294967296L), string / long)
         assertEquals(KBigInt(0), string % long)
+
+        assertEquals(Pair(KBigInt(4294967296L), KBigInt(0)), string.divRem(long))
     }
 
     @Test

kbigint/src/jvmMain/kotlin/io/github/observeroftime/kbigint/KBigInt.kt

@@ -96,6 +96,18 @@ actual class KBigInt private constructor(private var value: BigInteger) : Compar
     /** Perform a bitwise `XOR` operation. */
     actual infix fun xor(other: KBigInt) = KBigInt(value xor other.value)
 
+    /**
+     * Divide two [KBigInt] values and include the remainder.
+     *
+     * @since 0.5.0
+     * @return a `(quotient, remainder)` pair
+     */
+    @JvmName("divideAndRemainder")
+    actual fun divRem(other: KBigInt): Pair<KBigInt, KBigInt> {
+        val (quotient, remainder) = value.divideAndRemainder(other.value)
+        return Pair(KBigInt(quotient), KBigInt(remainder))
+    }
+
     /**
      * Find the (absolute) GCD of two [KBigInt] values.
      *

kbigint/src/jvmTest/kotlin/io/github/observeroftime/kbigint/KBigIntTest.kt

@@ -43,6 +43,8 @@ actual class KBigIntTest {
         assertEquals(KBigInt("19807040628566084398385987584"), string * long)
         assertEquals(KBigInt(4294967296L), string / long)
         assertEquals(KBigInt(0), string % long)
+
+        assertEquals(Pair(KBigInt(4294967296L), KBigInt(0)), string.divRem(long))
     }
 
     @Test

kbigint/src/nativeMain/kotlin/io/github/observeroftime/kbigint/KBigInt.kt

@@ -297,6 +297,20 @@ actual class KBigInt private constructor(private var value: mp_int) : Comparable
         KBigInt(result.ptr)
     }
 
+    /**
+     * Divide two [KBigInt] values and include the remainder.
+     *
+     * @since 0.5.0
+     * @return a `(quotient, remainder)` pair
+     */
+    @ObjCName("divideAndRemainder")
+    actual fun divRem(other: KBigInt) = memScoped {
+        val quotient = alloc<mp_int>()
+        val remainder = alloc<mp_int>()
+        mp_div(value.ptr, other.value.ptr, quotient.ptr, remainder.ptr).check()
+        Pair(KBigInt(quotient.ptr), KBigInt(remainder.ptr))
+    }
+
     /**
      * Find the (absolute) GCM of two [KBigInt] values.
      *

kbigint/src/nativeTest/kotlin/io/github/observeroftime/kbigint/KBigIntTest.kt

@@ -50,6 +50,8 @@ actual class KBigIntTest {
         assertEquals(KBigInt("19807040628566084398385987584"), string * long)
         assertEquals(KBigInt(4294967296L), string / long)
         assertEquals(KBigInt(0), string % long)
+
+        assertEquals(Pair(KBigInt(4294967296L), KBigInt(0)), string.divRem(long))
     }
 
     @Test