Money, a standard type

An amount of money: a whole number of a currency's smallest units, and the currency.

Use it for every amount of money. Never hold money in a Decimal: this type can't lose a penny to rounding, and it can't add pounds to euros. For an amount with whether tax is included, use Price. To fix the currency, build your own type on it.

Shape

One value, with no fields to fill in. As text it reads GBP 1234.50.

Example

example

money.from_minor(1050, Currency.gbp)

text.parse(raw, as: Money) reads one from text that comes from outside. Text that isn't one at all fails malformed, such as 10.50, GBP 10.505 or GBP 10.5.

These operations give one: money.allocate, money.convert, money.from_minor, money.of, money.split and money.sum.

Good to know

money.from_minor(1050, Currency.gbp) is £10.50, since it takes pence. money.of takes a decimal amount instead.
A percentage scales it: price * 120% adds 20%. To share it out, use money.split, which loses nothing: £10.00 three ways is £3.34, £3.33 and £3.33. price / 3 is refused.
< compares two amounts in one currency. With two different currencies the compiler refuses it, or, if a currency is only known while running, it fails with currency_mismatch.
A narrower type is often better: type Sterling = Money { currency: Currency.gbp min: 0 }.
== tells you whether two are the same, and < and list.sort_by compare and sort them.

In JSON

An object of its parts, in a request, a response or json.write:

json

{"amount":-500,"currency":"GBP"}{"amount":5,"currency":"GBP"}{"amount":1050,"currency":"GBP"}

Details

Text form, storage, how it is shown, and operations

Money is in the group Money and banking, and has been in Jadpo since 0.1.0.

Text form

text.from writes one standard text form, the same form text.parse reads back: GBP -5.00, GBP 0.05 and GBP 10.50.

How it is stored

It is stored in 2 columns, each named for the field, _ and its suffix. This is GBP 10.50:

Column	Type	Holds
`<field>_amount`	`bigint`	`1050`
`<field>_currency`	`char(3)`	`'GBP'`

How it is shown to people

text.format(value, locale:) shows it to people in their locale. A call may also give precision:, display: or sign:.

With locale: Locale.en_gb:

Value	Shown
`GBP -5.00`	`-£5.00`
`GBP 0.05`	`£0.05`
`GBP 10.50`	`£10.50`
`GBP 1234.50`	`£1,234.50`

Operations

money.allocate(total: Money, ratios: List<Int>) -> List<Money>: total shared in proportion to ratios, whole numbers never below 0, at least one of them; a share of ratio 0 is nothing.
money.convert(value: Money, rate: ExchangeRate) -> Money: value in rate's to currency, from its from one: the major units times rate.rate, rounded half to even to a minor unit, so £10.50 at a GBP/EUR rate of 1.17 is €12.28. It fails with currency_mismatch when value isn't in rate.from, unless that is known: an inverted rate is then a compile error. The rate is one the app holds; nothing here fetches one.
money.currency(value: Money) -> Currency: The currency value is in.
money.from_minor(amount: Int, currency: Currency) -> Money: amount minor units of currency: money.from_minor(1050, Currency.gbp) is £10.50.
money.minor(value: Money) -> Int: value's minor units: 1050 for £10.50.
money.of(amount: Decimal, currency: Currency) -> Money: amount major units of currency, a Decimal: money.of(10.50, Currency.gbp) is £10.50. It fails with too_many_places for more places than the currency has (10.505 in pounds), unless the currency is written out and the amount proved to have no more.
money.split(total: Money, parts: Int) -> List<Money>: total in parts near-equal shares, parts at least 1: £10.00 in 3 is £3.34, £3.33 and £3.33.
money.sum(items: List<Money>, currency: Currency) -> Money: The items added up in currency, the zero an empty list gives. It fails with currency_mismatch for an item in another currency, unless the items' type fixes currency.

It also takes text.parse, text.from, text.format, json.read, json.write and ==. How every standard type behaves says how they work.