High-performance Kotlin Multiplatform BigInteger and BigDecimal for JVM, Android, and Apple native targets.

On JVM and Android, BigInteger and BigDecimal are zero-overhead typealiases to java.math.BigInteger and java.math.BigDecimal. On Apple native targets, BigInteger uses pure Kotlin hot paths plus LibTomMath for larger or specialized work, and BigDecimal is implemented in Kotlin on top of the shared API. The library is zero-dependency except for LibTomMath on native targets.

bignum-kt is published to Maven Central. Add mavenCentral() to your repositories:

repositories {
    mavenCentral()
}

For Kotlin Multiplatform projects, add the dependency to commonMain:

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation("io.github.artificialpb:bignum:1.0.1")
            }
        }
    }
}

For JVM or Android-only projects, add the same dependency in the regular dependencies block:

dependencies {
    implementation("io.github.artificialpb:bignum:1.0.1")
}

Snapshot builds use the same coordinates with the snapshot version, plus the Maven Central snapshots repository:

repositories {
    maven("https://central.sonatype.com/repository/maven-snapshots/")
}

dependencies {
    implementation("io.github.artificialpb:bignum:1.0.2-SNAPSHOT")
}

import io.github.artificialpb.bignum.*

val a = bigIntegerOf("123456789012345678901234567890")
val b = bigIntegerOf(42L)

val sum = a + b
val shifted = a.shiftLeft(16)
val modPow = a.modPow(b, bigIntegerOf(1000000007L))

val price = bigDecimalOf("19.99")
val taxRate = bigDecimalOf("0.20")
val quantity = 3.toBigDecimal()

val subtotal = price.multiply(quantity)
val total = (subtotal + subtotal * taxRate).setScale(2, RoundingMode.HALF_UP)
val unscaled = total.toBigInteger()

The :benchmarks module compares bignum-kt against kotlin-multiplatform-bignum on macOS ARM64 across three operand profiles: small, medium, and large. The numbers below come from the latest full benchmark reports generated on April 19, 2026 using the checked-in benchmark configuration: 2 warmups, 3 measurement iterations, and 1 second per iteration.

All timings are in us/op. Lower is better.

bignum-kt is faster in 135 of 138 comparable macOS ARM64 benchmark cases. The only losses are the three hashCode cells. The biggest wins are large toString (333x), large radix toString (290x), large toDouble (283x), large byte-array construction (73x), and sqrt on the small profile (40x).

The same :benchmarks module also compares bignum-kt against kotlin-multiplatform-bignum for BigDecimal on macOS ARM64 across the same small, medium, and large operand profiles. The numbers below come from the latest full benchmark reports generated on April 23, 2026 using the checked-in benchmark configuration: 2 warmups, 3 measurement iterations, and 1 second per iteration.

All timings are in us/op. Lower is better.

bignum-kt is faster in 147 of 162 comparable macOS ARM64 BigDecimal benchmark cases. The losses cluster in the cheapest accessors: small-profile %, toFloat, and the scale, precision, signum, and unscaled value accessors. The biggest wins are large toPlainString (624630x), large toString (571556x), large equal-scale subtract (212052x), large factoryBigInteger construction (140958x), and large constructor(BigInteger) (123643x).

Constructors - BigInteger(String), BigInteger(String, radix), BigInteger(ByteArray), BigInteger(ByteArray, off, len)

Arithmetic - add, subtract, multiply, divide, mod, divideAndRemainder, abs, pow, gcd, lcm, sqrt, modPow, modInverse

Operators - +, -, *, /, %, unary -, ++, --, ..

Bitwise - and, or, xor, not, andNot, shiftLeft, shiftRight, testBit, setBit, clearBit, flipBit, bitLength, bitCount, getLowestSetBit

Number theory - isProbablePrime, nextProbablePrime

Conversions - toByteArray, toInt, toLong, toDouble, toString(radix), signum

Comparison - compareTo, min, max, equals, hashCode

Factory and extensions - bigIntegerOf(String), bigIntegerOf(Long), bigIntegerOf(Int), String.toBigInteger(), Long.toBigInteger(), Int.toBigInteger()

Constructors - BigDecimal(String), BigDecimal(BigInteger), BigDecimal(BigInteger, scale)

Arithmetic - add, subtract, multiply, divide, remainder, divideAndRemainder, divideToIntegralValue, abs, negate, plus, pow, sqrt, ulp

Operators - +, -, *, /, %, unary -, unary +

Scale and precision - scale, precision, setScale, movePointLeft, movePointRight, scaleByPowerOfTen, stripTrailingZeros, round, MathContext, RoundingMode

Conversions - toBigInteger, toBigIntegerExact, toInt, toLong, toFloat, toDouble, toString, toPlainString, toEngineeringString

Comparison - compareTo, min, max, equals, hashCode, signum

Factory and extensions - bigDecimalOf(String), bigDecimalOf(BigInteger), bigDecimalOf(BigInteger, scale), bigDecimalOf(Long), bigDecimalOf(Int), bigDecimalOf(Double), String.toBigDecimal(), BigInteger.toBigDecimal(), BigInteger.toBigDecimal(scale), Long.toBigDecimal(), Int.toBigDecimal(), Double.toBigDecimal()

The library is tested at several levels:

• Data-driven tests validate operations against known inputs and expected outputs.
• Property-based tests verify algebraic laws and invariants with generated values.
• Differential fuzz tests generate a JVM fixture corpus and replay it on native targets to catch semantic drift.
• Edge-case tests cover sign handling, negative bitwise behavior, and boundary conditions.

Tests live in commonTest, so the same cases run across JVM, Android, and Apple native targets.

Coverage reports are generated with Kover for the JVM target, which means commonMain and jvmAndroidMain code exercised by JVM tests is reported. Apple native tests still run via the normal test tasks, but Kotlin-native coverage is not collected by the current JetBrains coverage tooling.

Requires JDK 17+. Xcode is required for Apple targets. The Android SDK is required if you build the Android artifact.

# Build everything
./gradlew build

# Run all tests
./gradlew allTests

# Run ktlint
./gradlew ktlintCheck
./gradlew ktlintFormat

# Library tests only
./gradlew :bignum:jvmTest
./gradlew :bignum:macosArm64Test

# Generate JVM/common coverage reports
./gradlew coverage
./gradlew coverageHtml
./gradlew coverageXml

# Regenerate differential fuzz fixtures
./gradlew :bignum:generateDifferentialFixtures

# Regenerate differential fuzz fixtures with a custom seed
./gradlew :bignum:generateDifferentialFixtures -PdifferentialFixtureSeed=0xB16B00B4

# Compile benchmark sources for every benchmark target
./gradlew :benchmarks:compileAllBenchmarks

# Full macOS ARM64 benchmark sweep
./gradlew :benchmarks:macosArm64Benchmark

# Targeted macOS ARM64 benchmark suites
./gradlew :benchmarks:macosArm64ArithmeticBenchmark
./gradlew :benchmarks:macosArm64BitwiseBenchmark
./gradlew :benchmarks:macosArm64ComparisonBenchmark
./gradlew :benchmarks:macosArm64ConstructionBenchmark
./gradlew :benchmarks:macosArm64ConversionBenchmark
./gradlew :benchmarks:macosArm64NumberTheoryBenchmark
./gradlew :benchmarks:macosArm64RangeBenchmark

# BigDecimal macOS ARM64 benchmark suites
./gradlew :benchmarks:macosArm64BigDecimalArithmeticBenchmark
./gradlew :benchmarks:macosArm64BigDecimalComparisonBenchmark
./gradlew :benchmarks:macosArm64BigDecimalConstructionBenchmark
./gradlew :benchmarks:macosArm64BigDecimalConversionBenchmark
./gradlew :benchmarks:macosArm64BigDecimalScaleBenchmark

# Ionspin's kotlin-multiplatform-bignum comparison suites
./gradlew :benchmarks:macosArm64IonspinArithmeticBenchmark
./gradlew :benchmarks:macosArm64IonspinBitwiseBenchmark
./gradlew :benchmarks:macosArm64IonspinComparisonBenchmark
./gradlew :benchmarks:macosArm64IonspinConstructionBenchmark
./gradlew :benchmarks:macosArm64IonspinConversionBenchmark
./gradlew :benchmarks:macosArm64IonspinNumberTheoryBenchmark

# Ionspin BigDecimal comparison suites
./gradlew :benchmarks:macosArm64IonspinBigDecimalArithmeticBenchmark
./gradlew :benchmarks:macosArm64IonspinBigDecimalComparisonBenchmark
./gradlew :benchmarks:macosArm64IonspinBigDecimalConstructionBenchmark
./gradlew :benchmarks:macosArm64IonspinBigDecimalConversionBenchmark
./gradlew :benchmarks:macosArm64IonspinBigDecimalScaleBenchmark

1. Clone the repository with submodules:

   git clone --recurse-submodules https://github.com/ArtificialPB/bignum-kt.git

2. Open the project in IntelliJ IDEA (or another IDE with Kotlin Multiplatform support).
3. Run ./gradlew build.
4. Run ./gradlew allTests.

• Follow JVM semantics. If native and JVM behavior differ, JVM behavior is the reference.
• Prefer commonTest unless you are testing something that is genuinely platform-specific.
• Re-run the relevant benchmark suites when you touch hot paths.
• Regenerate differential fixtures when new cross-platform behavior needs fixture coverage.
• Keep the common API surface small and behaviorally consistent across platforms.
• Preserve the hybrid native design: optimize hot paths in Kotlin when that buys real wins, and use LibTomMath where it is still the best backend.

bignum-kt/
├── bignum/
│   └── src/
│       ├── commonMain/        # expect declarations + common API
│       ├── commonTest/        # shared tests and differential fixtures
│       ├── jvmMain/           # actual typealias to java.math.BigInteger
│       ├── nativeMain/        # hybrid Kotlin + LibTomMath native implementation
│       └── nativeInterop/     # LibTomMath sources and cinterop glue
├── benchmarks/
│   └── src/
│       └── commonMain/        # shared benchmark fixtures and suites
├── build.gradle.kts
├── settings.gradle.kts
└── gradle/libs.versions.toml