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"