money

Currency amounts on Decimal: exact arithmetic, ISO 4217 minor units, and allocation that never loses a cent. Pure - no capabilities.

ecko get github.com/ecko-lang/money
import money

Pure computation: it declares no capabilities, so it cannot touch the network, the filesystem or the environment.

Version 0.39.0 - source - MIT.


minor_unit_table()

The ISO 4217 table this package knows: a map from currency code to its number of decimal places.

money.minor_unit_table().KWD   # 3

minor_units(code)

How many decimal places a currency uses: 2 for USD, 0 for JPY, 3 for KWD.

The code is normalised first, so "usd" works. A code that is not an active ISO 4217 currency is refused rather than assumed to have two.

errors: money/bad_currency when the code is not three letters; money/unknown_currency when it is not an ISO 4217 currency; bug when code is not a string.

money.minor_units("JPY")   # 0

normalize_code(code)

The code uppercased, once its shape is checked. It does not check that the code is a known currency; minor_units does.

errors: money/bad_currency when the code is not three letters; bug when code is not a string.

money.normalize_code("eur")   # "EUR"

of(amount, code, rounding = false)

An amount from a Decimal (or an Int) and a currency code.

An amount with more decimal places than the currency has (12.345 USD) is refused, because keeping it would round it later, out of sight; pass rounding: true to round it here, half away from zero.

errors: money/too_precise when the amount is finer than the currency and rounding is false; money/bad_currency or money/unknown_currency for the code; bug when the amount is a Float or not a number.

money.of(19.99m, "USD")   # { amount: 19.99, currency: "USD" }

parse(text, code, rounding = false)

An amount from a string such as "19.99". Refused, like of, when it has more decimal places than the currency; rounding: true rounds it.

errors: money/bad_amount when the text is not a number; money/too_precise, money/bad_currency and money/unknown_currency as for of.

money.parse("12.345", "USD", rounding: true)   # 12.35 USD

zero(code)

Zero in the given currency.

errors: money/bad_currency or money/unknown_currency for the code.

money.to_string(money.zero("JPY"))   # "0 JPY"

to_minor(m)

The amount as an Int count of minor units: 10.50 USD is 1050.

An amount carrying extra places from mul is rounded half away from zero, in decimal.

errors: bug when m is not an amount.

money.to_minor(money.parse("10.50", "USD"))   # 1050

from_minor(units, code)

An amount from an Int count of minor units: 1050 with USD is 10.50.

errors: money/bad_currency or money/unknown_currency for the code; bug when units is not an Int.

money.to_string(money.from_minor(1050, "USD"))   # "10.50 USD"

add(a, b)

The sum of two amounts in the same currency.

errors: money/currency_mismatch when the currencies differ; bug when either is not an amount.

money.add(money.parse("0.10", "USD"), money.parse("0.20", "USD"))   # 0.30 USD

sub(a, b)

a minus b, both in the same currency.

errors: money/currency_mismatch when the currencies differ; bug when either is not an amount.

mul(m, factor)

The amount scaled by an Int or a Decimal factor.

The result may carry more places than the currency (mul by a tax rate); to_string and to_minor round it at the end, while split and allocate refuse it until it is rounded with of(m.amount, m.currency, rounding: true).

errors: bug when m is not an amount or factor is a Float or not a number.

money.to_string(money.mul(money.parse("10.00", "USD"), 0.0825m))   # "0.83 USD"

neg(m)

The amount with its sign flipped.

errors: bug when m is not an amount.

abs_of(m)

The amount without its sign.

errors: bug when m is not an amount.

sum(items, code)

The total of a list of amounts. code names the currency, which is what the empty list sums to.

errors: money/currency_mismatch when an item is in another currency; bug when items is not a list or an item is not an amount.

money.to_string(money.sum([], "USD"))   # "0.00 USD"

compare(a, b)

-1, 0 or 1 as a is less than, equal to or greater than b.

errors: money/currency_mismatch when the currencies differ; bug when either is not an amount.

eq(a, b)

Whether two amounts in the same currency are equal. 1.0 and 1.00 USD are.

errors: as for compare.

lt(a, b)

Whether a is less than b.

errors: as for compare.

gt(a, b)

Whether a is greater than b.

errors: as for compare.

is_zero(m)

Whether the amount is exactly zero.

errors: bug when m is not an amount.

is_negative(m)

Whether the amount is below zero.

errors: bug when m is not an amount.

split(m, n)

n parts that sum back to the original exactly, the remainder going one minor unit at a time to the first parts.

errors: money/too_precise when the amount has more places than its currency (round it first); bug when n is not a positive Int or m is not an amount.

map(money.split(money.parse("0.10", "USD"), 3), money.to_string)   # 0.04, 0.03, 0.03

allocate(m, ratios)

Shares by ratio, in the currency's smallest unit, that sum back exactly.

Each share gets the whole minor units its ratio earns; the units left over go one at a time to the shares with the largest remainders (ties to the earlier share). So 59.97 as 3:7 is 17.99 and 41.98, and a zero ratio never receives anything. Ratios are non-negative Ints or Decimals. A negative amount allocates like its positive, sign carried through, so a refund splits like the charge it reverses.

errors: money/too_precise when the amount has more places than its currency (round it first); bug when ratios is not a non-empty list of non-negative Ints or Decimals that sum above zero, or m is not an amount.

map(money.allocate(money.parse("59.97", "USD"), [3, 7]), money.to_string)   # 17.99, 41.98

to_string(m)

The amount as text with the number of decimals the currency uses: yen render whole, dinar to three places, and extra places from mul round half away from zero, in decimal.

errors: bug when m is not an amount.

money.to_string(money.parse("10.5", "USD"))   # "10.50 USD"