Money
Handle amounts of money as exact decimals, with the number of decimals of each ISO 4217 currency: round, format, add, convert with a given rate, split without losing a cent, and convert to and from minor units. Typical uses: split an invoice into installments, send an amount in cents to a payment API.
money roundmoney roundmoney formatmoney formatmoney convertmoney convertmoney allocatemoney allocatemoney summoney summoney to_minormoney from_minormoney currency

money round <amount> <currency>


Description

    Round an amount to the decimals of its currency, half up. Returns the amount with exactly these decimals

Parameters

    amount:   The amount, with a point - String - required
    currency:   The ISO 4217 code, ex: EUR - String - required
admin
money round "19.995" "EUR"
mentdb
20.00
yen have no decimals
admin
money round "1234.5" "JPY"
mentdb
1235
Kuwaiti dinars have 3
admin
money round "1.2345" "KWD"
mentdb
1.235
a decimal comma is refused
admin
money round "12,30" "EUR"
mentdb
ERROR: Sorry, an error appears (the parameter 'amount' must be a decimal number with a point, ex: 1234.50 (here '12,30')).

money round <amount> <currency> <params>


Description

    Round with parameters: mode (half_up, half_even, half_down, up, down, ceiling, floor, exact), scale (the decimals, instead of those of the currency), increment (a cash step, ex: 0.05)

Parameters

    amount:   The amount - String - required
    currency:   The ISO 4217 code - String - required
    params:   The parameters as JSON - String - required
admin
money round "2.665" "EUR" "{\"mode\": \"half_even\"}"
mentdb
2.66
Swiss cash: steps of 5 centimes
admin
money round "12.37" "CHF" "{\"increment\": \"0.05\"}"
mentdb
12.35
exact: an error rather than a silent rounding
admin
money round "10.005" "EUR" "{\"mode\": \"exact\"}"
mentdb
ERROR: Sorry, an error appears (the amount 10.005 needs rounding to 2 decimals and the mode is exact).

money format <amount> <currency>


Description

    Format an amount for people, in en-US

Parameters

    amount:   The amount - String - required
    currency:   The ISO 4217 code - String - required
admin
money format "-1234.5" "USD"
mentdb
-$1,234.50

money format <amount> <currency> <params>


Description

    Format with parameters: locale (a language tag: fr-FR, de-DE, de-CH, en-GB, ja-JP...), display (symbol, code or none), mode, scale, increment, grouping (false: no thousands separator), plain_spaces (true: ordinary spaces instead of the no-break spaces)

Parameters

    amount:   The amount - String - required
    currency:   The ISO 4217 code - String - required
    params:   The parameters as JSON - String - required
admin
money format "1234567.891" "EUR" "{\"locale\": \"fr-FR\"}"
mentdb
1 234 567,89 €
German, with the code
admin
money format "1234.5" "EUR" "{\"locale\": \"de-DE\", \"display\": \"code\"}"
mentdb
1.234,50 EUR
Swiss German
admin
money format "1234.5" "CHF" "{\"locale\": \"de-CH\"}"
mentdb
CHF 1’234.50
only the number, for a column of a table
admin
money format "1234.5" "EUR" "{\"locale\": \"fr-FR\", \"display\": \"none\", \"plain_spaces\": true}"
mentdb
1 234,50
Used in use cases (1 recipe)

    Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
Often used with

    money allocate  ·  money sum  ·  money to_minor

money convert <amount> <from> <to> <rate>


Description

    Convert with a rate given by the caller (1 unit of from = rate units of to), rounded half up to the decimals of the target currency

Parameters

    amount:   The amount - String - required
    from:   The source currency - String - required
    to:   The target currency - String - required
    rate:   The rate - String - required
admin
money convert "100" "EUR" "USD" "1.0834"
mentdb
108.34
euros to yen
admin
money convert "100" "EUR" "JPY" "162.4567"
mentdb
16246

money convert <amount> <from> <to> <rate> <params>


Description

    Convert with parameters: inverse (true: the rate is 1 unit of to = rate units of from, as the ECB publishes it for EUR; the exact quotient is rounded once, so mode exact and the half modes are always right), mode, scale, increment

Parameters

    amount:   The amount - String - required
    from:   The source currency - String - required
    to:   The target currency - String - required
    rate:   The rate - String - required
    params:   The parameters as JSON - String - required
admin
money convert "100" "USD" "EUR" "1.0834" "{\"inverse\": true}"
mentdb
92.30

money allocate <amount> <currency> <ratios>


Description

    Split an amount without losing a cent. ratios: a number of equal parts, or a JSON array of ratios (any scale: [50, 30, 20] or [0.5, 0.3, 0.2]). Returns a JSON array of amounts

Parameters

    amount:   The amount - String - required
    currency:   The ISO 4217 code - String - required
    ratios:   A number of parts, or a JSON array of ratios - String - required
admin
money allocate "100" "EUR" "3"
mentdb
["33.34", "33.33", "33.33"]
a discount of 10 euros on 3 lines, by their amounts
admin
money allocate "10.00" "EUR" "[129.90, 45.50, 9.99]"
mentdb
["7.01", "2.45", "0.54"]
a refund: negative amounts
admin
money allocate "-0.05" "EUR" "2"
mentdb
["-0.03", "-0.02"]

money allocate <amount> <currency> <ratios> <params>


Description

    Split with the parameter scale (the decimals, for a currency without minor unit or a finer split)

Parameters

    amount:   The amount - String - required
    currency:   The ISO 4217 code - String - required
    ratios:   A number of parts, or a JSON array of ratios - String - required
    params:   The parameters as JSON - String - required
admin
money allocate "100" "XAU" "3" "{\"scale\": 3}"
mentdb
["33.334", "33.333", "33.333"]
Used in use cases (1 recipe)

    Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
Often used with

    money format  ·  money sum  ·  money to_minor

money sum <amounts>


Description

    Add amounts of one currency: "12.50 EUR", "EUR 12.50" or {"amount": ..., "currency": ...}. Returns {amount, currency, count}. Two currencies, or an amount with more decimals than its currency, are an error

Parameters

    amounts:   A JSON array of amounts - String - required
admin
money sum "[\"12.50 EUR\", \"EUR 3.10\", {\"amount\": \"0.40\", \"currency\": \"EUR\"}]"
mentdb
{"amount": "16.00", "currency": "EUR", "count": 3}
two currencies
admin
money sum "[\"12.50 EUR\", \"3 USD\"]"
mentdb
ERROR: Sorry, an error appears (the item 1 is in USD, not in EUR: convert it first with money convert).

money sum <amounts> <params>


Description

    Add amounts with the parameter currency (for the amounts written without currency, and for an empty list)

Parameters

    amounts:   A JSON array of amounts - String - required
    params:   The parameters as JSON - String - required
admin
money sum "[0.1, 0.2]" "{\"currency\": \"EUR\"}"
mentdb
{"amount": "0.30", "currency": "EUR", "count": 2}
Used in use cases (1 recipe)

    Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
Often used with

    money allocate  ·  money format  ·  money to_minor

money to_minor <amount> <currency>


Description

    The amount in minor units (cents), as payment APIs want it. An amount with more decimals is an error

Parameters

    amount:   The amount - String - required
    currency:   The ISO 4217 code - String - required
admin
money to_minor "19.90" "EUR"
mentdb
1990
yen have no minor unit
admin
money to_minor "1500" "JPY"
mentdb
1500
Used in use cases (1 recipe)

    Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
Often used with

    money allocate  ·  money format  ·  money sum

money from_minor <units> <currency>


Description

    Minor units (cents) back to an amount

Parameters

    units:   An integer number of minor units - String - required
    currency:   The ISO 4217 code - String - required
admin
money from_minor "1990" "EUR"
mentdb
19.90
fils to Bahraini dinars (3 decimals)
admin
money from_minor "1990" "BHD"
mentdb
1.990

money currency <currency>


Description

    The ISO 4217 data of a currency: {code, numeric_code, minor_units, name}. minor_units is null for a code without minor unit

Parameters

    currency:   The ISO 4217 code - String - required
admin
money currency "EUR"
mentdb
{"code": "EUR", "numeric_code": "978", "minor_units": 2, "name": "Euro"}
the CFP franc of French Polynesia
admin
money currency "XPF"
mentdb
{"code": "XPF", "numeric_code": "953", "minor_units": 0, "name": "CFP Franc"}
an unknown code
admin
money currency "ABC"
mentdb
ERROR: Sorry, an error appears (the parameter 'currency': 'ABC' is not an ISO 4217 currency).