currency_kt

Accurate currency arithmetic and formatting using integer-backed amounts to avoid floating-point errors; parsing, increment rounding, distribution, international formatting, customizable symbols and precision.

#utility
#serialization
#parsing
#localization
#language-extensions

Suggest an edit

Android

JVM

iOS

GitHub stars0

AuthorsRyiski

Dependents0

LicenseMIT License

Creation date22 days ago

Last activity21 days ago

Latest release1.0.0 (21 days ago)

GitHub repository

currency_kt

currency_kt is a Kotlin Multiplatform (KMP) library for handling currency values — a port of currency_rs, inspired by currency.js. It works with values as integers behind the scenes, resolving floating point precision issues.

2.51 + 0.01                              // 2.5199999999999996
Currency(2.51).add(0.01).value           // 2.52

2.52 - 0.01                              // 2.5100000000000002
Currency(2.52).subtract(0.01).value      // 2.51

Works for values up to 2⁵³ in cents (90,071,992,547,409.91).

Platforms

Platform	Target
Android	`androidTarget()`
iOS	`iosArm64()`, `iosSimulatorArm64()`, `iosX64()`

Installation

// settings.gradle.kts
repositories {
    mavenCentral()
}

// build.gradle.kts
dependencies {
    implementation("org.currency_kt:currency_kt:1.0.0")
}

Usage

Create currency values from numbers, strings, or existing currency objects:

Currency(123.0).toString()              // 123.00
Currency(1.23).toString()               // 1.23
Currency.fromString("1.23").getOrThrow().toString()    // 1.23
Currency.fromString("\$12.30").getOrThrow().toString()   // 12.30

val value = Currency.fromString("123.45").getOrThrow()
Currency.fromCurrency(value).toString()   // 123.45

From Cents

Parse amounts as minor currency units (e.g. cents in a dollar):

val opts = CurrencyOpts(fromCents = true)

Currency(123.0, opts).toString()          // 1.23
Currency.fromString("123", opts).getOrThrow().toString()  // 1.23

Currency(123.0, CurrencyOpts(fromCents = true, precision = 0)).toString()  // 123
Currency(123.0, CurrencyOpts(fromCents = true, precision = 3)).toString()  // 0.123

Arithmetic

Currency(123.5).add(0.23).value           // 123.73
Currency(5.0).subtract(0.5).value         // 4.50
Currency(45.25).multiply(3.0).value       // 135.75
Currency(1.12).distribute(5).map { it.value }
    // [0.23, 0.23, 0.22, 0.22, 0.22]

Operator overloads:

(Currency(123.5) + 0.23).value            // 123.73
(Currency(5.0) - 0.5).value               // 4.50
(Currency(45.25) * 3.0).value             // 135.75

Formatting

Currency.fromString("2,573,693.75").getOrThrow()
    .addString("\$100,275.50").getOrThrow()
    .format()                              // "\$2,673,969.25"

Currency.fromString("1,237.72").getOrThrow()
    .subtract(300.0)
    .format()                              // "\$937.72"

Internationalization

val euro = CurrencyOpts(symbol = "€", separator = ".", decimal = ",")

Currency.fromString("2.573.693,75", euro).getOrThrow()
    .addString("100.275,50").getOrThrow()
    .format()                              // "€2.673.969,25"

Currency.fromString("1.237,72", euro).getOrThrow()
    .subtract(300.0)
    .format()                              // "€937,72"

Factory functions for multiple currencies:

fun usd(value: Double) = Currency(value, CurrencyOpts(symbol = "\$", precision = 2))
fun jpy(value: Double) = Currency(value, CurrencyOpts(symbol = "¥", precision = 0))
fun gas(value: Double) = Currency(value, CurrencyOpts(precision = 3))

usd(1234.56).format()   // "\$1,234.56"
jpy(1234.56).format()   // "¥1,235"
gas(1234.56).format()   // "\$1,234.560"

Options

Option	Default	Description
`symbol`	`"$"`	Currency symbol used in `format()`
`separator`	`","`	Thousands separator
`decimal`	`"."`	Decimal point
`precision`	`2`	Number of decimal places
`pattern`	`"!#"`	Format pattern: `!` = symbol, `#` = amount
`negativePattern`	`"-!#"`	Negative format pattern
`increment`	`null`	Round to nearest increment (e.g. `0.05` for nickel rounding)
`useVedic`	`false`	Indian Numbering System groupings (`10,00,000.00`)
`fromCents`	`false`	Parse values as minor currency units
`errorOnInvalid`	`false`	Throw `CurrencyErr.ParseErr` on invalid string input

Increment Rounding

val opts = CurrencyOpts(increment = 0.05)
Currency(1.48, opts).format()   // "\$1.50"

License

MIT

Android

JVM

iOS

GitHub stars0

AuthorsRyiski

Dependents0

LicenseMIT License

Creation date22 days ago

Last activity21 days ago

Latest release1.0.0 (21 days ago)

GitHub repository

currency_kt

2.51 + 0.01                              // 2.5199999999999996
Currency(2.51).add(0.01).value           // 2.52

2.52 - 0.01                              // 2.5100000000000002
Currency(2.52).subtract(0.01).value      // 2.51

Works for values up to 2⁵³ in cents (90,071,992,547,409.91).

Platforms

Platform	Target
Android	`androidTarget()`
iOS	`iosArm64()`, `iosSimulatorArm64()`, `iosX64()`

Installation

// settings.gradle.kts
repositories {
    mavenCentral()
}

// build.gradle.kts
dependencies {
    implementation("org.currency_kt:currency_kt:1.0.0")
}

Usage

Create currency values from numbers, strings, or existing currency objects:

Currency(123.0).toString()              // 123.00
Currency(1.23).toString()               // 1.23
Currency.fromString("1.23").getOrThrow().toString()    // 1.23
Currency.fromString("\$12.30").getOrThrow().toString()   // 12.30

val value = Currency.fromString("123.45").getOrThrow()
Currency.fromCurrency(value).toString()   // 123.45

From Cents

Parse amounts as minor currency units (e.g. cents in a dollar):

val opts = CurrencyOpts(fromCents = true)

Currency(123.0, opts).toString()          // 1.23
Currency.fromString("123", opts).getOrThrow().toString()  // 1.23

Currency(123.0, CurrencyOpts(fromCents = true, precision = 0)).toString()  // 123
Currency(123.0, CurrencyOpts(fromCents = true, precision = 3)).toString()  // 0.123

Arithmetic

Currency(123.5).add(0.23).value           // 123.73
Currency(5.0).subtract(0.5).value         // 4.50
Currency(45.25).multiply(3.0).value       // 135.75
Currency(1.12).distribute(5).map { it.value }
    // [0.23, 0.23, 0.22, 0.22, 0.22]

Operator overloads:

(Currency(123.5) + 0.23).value            // 123.73
(Currency(5.0) - 0.5).value               // 4.50
(Currency(45.25) * 3.0).value             // 135.75

Formatting

Currency.fromString("2,573,693.75").getOrThrow()
    .addString("\$100,275.50").getOrThrow()
    .format()                              // "\$2,673,969.25"

Currency.fromString("1,237.72").getOrThrow()
    .subtract(300.0)
    .format()                              // "\$937.72"

Internationalization

val euro = CurrencyOpts(symbol = "€", separator = ".", decimal = ",")

Currency.fromString("2.573.693,75", euro).getOrThrow()
    .addString("100.275,50").getOrThrow()
    .format()                              // "€2.673.969,25"

Currency.fromString("1.237,72", euro).getOrThrow()
    .subtract(300.0)
    .format()                              // "€937,72"

Factory functions for multiple currencies:

fun usd(value: Double) = Currency(value, CurrencyOpts(symbol = "\$", precision = 2))
fun jpy(value: Double) = Currency(value, CurrencyOpts(symbol = "¥", precision = 0))
fun gas(value: Double) = Currency(value, CurrencyOpts(precision = 3))

usd(1234.56).format()   // "\$1,234.56"
jpy(1234.56).format()   // "¥1,235"
gas(1234.56).format()   // "\$1,234.560"

Options

Option	Default	Description
`symbol`	`"$"`	Currency symbol used in `format()`
`separator`	`","`	Thousands separator
`decimal`	`"."`	Decimal point
`precision`	`2`	Number of decimal places
`pattern`	`"!#"`	Format pattern: `!` = symbol, `#` = amount
`negativePattern`	`"-!#"`	Negative format pattern
`increment`	`null`	Round to nearest increment (e.g. `0.05` for nickel rounding)
`useVedic`	`false`	Indian Numbering System groupings (`10,00,000.00`)
`fromCents`	`false`	Parse values as minor currency units
`errorOnInvalid`	`false`	Throw `CurrencyErr.ParseErr` on invalid string input

Increment Rounding

val opts = CurrencyOpts(increment = 0.05)
Currency(1.48, opts).format()   // "\$1.50"

License

MIT