
Safe, precise monetary arithmetic pairing arbitrary-precision decimals with currency metadata — enforces currency consistency, currency-aware rounding, lossless allocation/splitting, conversion, formatting, and JSON serialization.
A Kotlin Multiplatform library for working with monetary amounts safely and precisely.
KmpMoney pairs an arbitrary-precision BigDecimal
value with a Currency, and enforces currency consistency on every operation — mixing currencies
throws instead of silently producing a wrong result.
import com.amarula.kmpMoney.Currency
import com.amarula.kmpMoney.KmpMoney
val price = KmpMoney.of("19.99", Currency.USD)
val tax = price.percentage(8.5)
val total = price + tax
println(total.toMoneyString()) // "$ 21.69"dependencies {
implementation("com.amarulasolutions:kmp-money:0.1.0")
}Representing money as Double or Float invites rounding bugs; representing it as a bare
BigDecimal loses track of what currency it's actually in. KmpMoney fixes both: every amount
carries its currency, arithmetic between mismatched currencies fails loudly, and rounding always
follows the currency's own decimal places (so JPY rounds to whole yen, BHD to three decimal
places, and so on).
Amounts of different currencies can't be combined by accident:
val usd = KmpMoney.of("10.00", Currency.USD)
val eur = KmpMoney.of("10.00", Currency.EUR)
usd.add(eur) // throws IllegalArgumentException: Currency mismatch: USD vs EURSplitting a bill without losing a cent:
val bill = KmpMoney.of("100.00", Currency.USD)
bill.split(3) // [33.34, 33.33, 33.33] — sums back to exactly 100.00add, subtract, multiply, divide, and the + - * operators,
all guarded by currency checks.percentage, addPercentage, subtractPercentage (reverse/embedded percentage).allocate(ratios) and split(n) distribute an amount proportionally
without losing or duplicating a single minor unit; leftover pennies go to the first slots.round(mode) and roundToCashDenomination(denomination) for cash rounding (e.g.
nearest 0.05).convertTo(currency, rate), plus an ExchangeRateProvider interface so an app
can plug in its own rate source (the library does no networking or caching itself).isGreaterThan, isLessThan, isEqualTo, isBetween, coerceAtLeast,
coerceAtMost, coerceIn, and full Comparable support.toMoneyString(), format(showSymbol, useCode, groupingSeparator), and
toCompactString() (e.g. $ 1.5K, $ 2.3M).toMinorUnits() / ofMinorUnits() for integer-cents interop,
toMap() / fromMap() for key-value storage.KmpMoneySerializer for kotlinx.serialization.sum(), max(), min(), average(), sumMoneyOf { } on
List<KmpMoney>, and sumMoney() / totalByCurrency() on Flow<KmpMoney>.kmp-money/ — the library module (commonMain), published as a Kotlin Multiplatform
library targeting JVM, Android, and iOS.example/ — an Android Compose app that showcases every feature of the library through
small, interactive examples.The example module is a single-screen Jetpack Compose app (ExampleApp.kt) with one button per
category; picking a category swaps in a small live demo backed by real KmpMoney calls, each
showing the exact API call and its result. Categories include:
Basics · Arithmetic · Multiply / Divide · Percentage · Comparisons · Rounding · Allocation · Conversion · Compact format · Collections · Sign & zero · Full comparisons · Clamping · Currency mismatch · Negation & abs · Operators · Integer division · Raw & interop · Minor units · Factory methods · Map round-trip · JSON serialization · Sorting · sumMoneyOf · Flow extensions · Currency metadata
Each example lives in its own file under
example/src/main/java/com/amarula/kmpMoney/example/examples/, built from a small set of shared
components (ExampleCard, AmountField, ResultField, CalculateButton) in
example/src/main/java/com/amarula/kmpMoney/example/components/ExampleComponents.kt. This makes
the examples a good reference for API usage and a good starting point for adding a demo of a new
feature.
Run the library's unit tests:
./gradlew :kmp-money:testRun static analysis (ktlint + detekt) and coverage:
./gradlew ktlintCheck detekt koverHtmlReportRun the example app on a connected device or emulator:
./gradlew :example:installDebugApache License 2.0 -- see LICENSE.
A Kotlin Multiplatform library for working with monetary amounts safely and precisely.
KmpMoney pairs an arbitrary-precision BigDecimal
value with a Currency, and enforces currency consistency on every operation — mixing currencies
throws instead of silently producing a wrong result.
import com.amarula.kmpMoney.Currency
import com.amarula.kmpMoney.KmpMoney
val price = KmpMoney.of("19.99", Currency.USD)
val tax = price.percentage(8.5)
val total = price + tax
println(total.toMoneyString()) // "$ 21.69"dependencies {
implementation("com.amarulasolutions:kmp-money:0.1.0")
}Representing money as Double or Float invites rounding bugs; representing it as a bare
BigDecimal loses track of what currency it's actually in. KmpMoney fixes both: every amount
carries its currency, arithmetic between mismatched currencies fails loudly, and rounding always
follows the currency's own decimal places (so JPY rounds to whole yen, BHD to three decimal
places, and so on).
Amounts of different currencies can't be combined by accident:
val usd = KmpMoney.of("10.00", Currency.USD)
val eur = KmpMoney.of("10.00", Currency.EUR)
usd.add(eur) // throws IllegalArgumentException: Currency mismatch: USD vs EURSplitting a bill without losing a cent:
val bill = KmpMoney.of("100.00", Currency.USD)
bill.split(3) // [33.34, 33.33, 33.33] — sums back to exactly 100.00add, subtract, multiply, divide, and the + - * operators,
all guarded by currency checks.percentage, addPercentage, subtractPercentage (reverse/embedded percentage).allocate(ratios) and split(n) distribute an amount proportionally
without losing or duplicating a single minor unit; leftover pennies go to the first slots.round(mode) and roundToCashDenomination(denomination) for cash rounding (e.g.
nearest 0.05).convertTo(currency, rate), plus an ExchangeRateProvider interface so an app
can plug in its own rate source (the library does no networking or caching itself).isGreaterThan, isLessThan, isEqualTo, isBetween, coerceAtLeast,
coerceAtMost, coerceIn, and full Comparable support.toMoneyString(), format(showSymbol, useCode, groupingSeparator), and
toCompactString() (e.g. $ 1.5K, $ 2.3M).toMinorUnits() / ofMinorUnits() for integer-cents interop,
toMap() / fromMap() for key-value storage.KmpMoneySerializer for kotlinx.serialization.sum(), max(), min(), average(), sumMoneyOf { } on
List<KmpMoney>, and sumMoney() / totalByCurrency() on Flow<KmpMoney>.kmp-money/ — the library module (commonMain), published as a Kotlin Multiplatform
library targeting JVM, Android, and iOS.example/ — an Android Compose app that showcases every feature of the library through
small, interactive examples.The example module is a single-screen Jetpack Compose app (ExampleApp.kt) with one button per
category; picking a category swaps in a small live demo backed by real KmpMoney calls, each
showing the exact API call and its result. Categories include:
Basics · Arithmetic · Multiply / Divide · Percentage · Comparisons · Rounding · Allocation · Conversion · Compact format · Collections · Sign & zero · Full comparisons · Clamping · Currency mismatch · Negation & abs · Operators · Integer division · Raw & interop · Minor units · Factory methods · Map round-trip · JSON serialization · Sorting · sumMoneyOf · Flow extensions · Currency metadata
Each example lives in its own file under
example/src/main/java/com/amarula/kmpMoney/example/examples/, built from a small set of shared
components (ExampleCard, AmountField, ResultField, CalculateButton) in
example/src/main/java/com/amarula/kmpMoney/example/components/ExampleComponents.kt. This makes
the examples a good reference for API usage and a good starting point for adding a demo of a new
feature.
Run the library's unit tests:
./gradlew :kmp-money:testRun static analysis (ktlint + detekt) and coverage:
./gradlew ktlintCheck detekt koverHtmlReportRun the example app on a connected device or emulator:
./gradlew :example:installDebugApache License 2.0 -- see LICENSE.