std::currency
Currencies: what an amount of money is counted in. A Currency is an
ISO 4217 currency, current or historical, named by its code
(Currency"EUR", Currency"JPY"), whose minor digits come from
CLDR: two for the euro, none for the yen. A currency ISO does not list,
such as a cryptocurrency or a shop’s loyalty points, is a custom
currency, named by its code and minor digits: Currency"BTC:8", or
Currency.custom("BTC", 8) while the program runs. Both literal forms
are checked when the program is checked, and in a module a literal’s
custom currency must be one its nomi.toml lists:
[money] custom_currencies = ["BTC:8", "PTS:0"]
Two currencies are equal when their codes and minor digits are, so two
libraries that each define Currency"PTS:0" share it, and PTS:0
and PTS:2 are two currencies. Money (std::money) pairs an amount with
its currency.
Import with import std::currency.
Exports
Section titled “Exports”Listed custom currencies
Section titled “Listed custom currencies”A custom currency needs no setup, so a typo makes another one. In a file
of a module (one with a nomi.toml above it), a Currency"…" or
Money"…" literal naming a custom currency must name one its module’s
[money].custom_currencies lists, code and
digits; otherwise it is a compile error at the literal that suggests a
listed entry with the same code or one edit away:
typed literal Currency"PST:0": `PST:0` is a custom currency this module does not list: add it to [money].custom_currencies in nomi.toml, with
help: did you mean `PTS:0`? nomi.toml lists it.
A Currency.custom("PTS", 0) call whose code and digits are both literals
is checked the same way, at the call, and its error’s help names the
literal form. The editor shows a warning at every such call that is no
error, naming the literal (write Currency"PTS:0", which the compiler checks); nomi check prints none. A currency made from values while
the program runs (Currency.custom(code, digits), Currency.parse,
Money.parse_in) is not checked, and a file in no module (a script, the
REPL) and the standard library’s own files may name any.
type Currency
Section titled “type Currency”type Currency String
opaque — construction surface is private to its defining module
A currency: an ISO 4217 code, or a custom code with its minor digits.
Display gives the code; Debug gives the literal that builds it.
assert Display.to_string(Currency"EUR") == "EUR"
assert Debug.inspect(Currency"BTC:8") == "Currency\"BTC:8\""
assert Currency"PTS:0" == Currency"PTS:0"
refute Currency"PTS:0" == Currency"PTS:2"
Currency.parse
Section titled “Currency.parse”fn parse(text: String) -> Result<Currency, Error>
type function on Currency
Read a currency as its literal writes it: an ISO 4217 code (EUR),
or a custom code and its minor digits (BTC:8).
assert Currency.parse("EUR") == Ok(Currency"EUR")
assert Currency.parse("JPY") |> Result.map(&Currency.minor_digits(&1)) == Ok(0)
assert Currency.parse("PTS:0") == Currency.custom("PTS", 0)
assert Currency.parse("eur") == Err(Error.Malformed{text: "eur"})
assert Currency.parse("EUR:2") == Err(Error.IsoCode{code: "EUR"})
assert Currency.parse("BTC") == Err(Error.NotIso{code: "BTC"})
Currency.custom
Section titled “Currency.custom”fn custom(code: String, minor_digits: Int) -> Result<Currency, Error>
type function on Currency
A custom currency: code, 1 to 12 of A–Z and 0–9 starting
with a letter, that is not an ISO 4217 code, with minor_digits
digits after the decimal point, 0 to 18. A three-letter code such as
BTC is allowed; if CLDR ever lists it as ISO, this returns
Err(.IsoCode) and its literal stops compiling.
assert Currency.custom("BTC", 8) |> Result.map(&Currency.minor_digits(&1)) == Ok(8)
assert Currency.custom("EUR", 2) == Err(Error.IsoCode{code: "EUR"})
assert Currency.custom("POINTS", 19) == Err(Error.Digits{digits: 19})
assert Currency.custom("1UP", 0) == Err(Error.Malformed{text: "1UP"})
Currency.code
Section titled “Currency.code”fn code(currency: Currency) -> String
type function on Currency
The currency’s code: EUR, or a custom currency’s own (BTC).
assert Currency.code(Currency"BTC:8") == "BTC"
Currency.minor_digits
Section titled “Currency.minor_digits”fn minor_digits(currency: Currency) -> NonNegativeInt
type function on Currency
How many digits the currency has after the decimal point: an ISO currency’s as CLDR gives them (EUR 2, JPY 0, BHD 3), a custom one’s as it was made with.
assert Currency.minor_digits(Currency"EUR") == 2
assert Currency.minor_digits(Currency"JPY") == 0
assert Currency.minor_digits(Currency"BTC:8") == 8
Currency.is_iso
Section titled “Currency.is_iso”fn is_iso(currency: Currency) -> Bool
type function on Currency
Whether the currency is an ISO 4217 one, not a custom one.
assert Currency.is_iso(Currency"EUR")
refute Currency.is_iso(Currency"BTC:8")
Currency.from_fragments
Section titled “Currency.from_fragments”impl Literal for Currency
fn from_fragments(fragments: List<Fragment<String>>) -> Result<Currency, Error>
Currency"EUR" is the ISO currency of the code, current or
historical, as the pinned CLDR lists it, and Currency"BTC:8" the
custom currency of a code and its minor digits, as Currency.parse
reads them. A literal without slots is checked when the program is checked, so
a code CLDR does not list is a compile error at the literal:
typed literal Currency"BTC" is invalid: `BTC` is not an ISO 4217 currency: a custom currency names its minor digits, as Currency"BTC:2" .
The literal checks a custom currency by Currency.custom’s rules, and
in a module, against the custom currencies its nomi.toml lists.
Currency.to_string
Section titled “Currency.to_string”impl Display for Currency
fn to_string(currency: Currency) -> String
impl Display.to_string
The code.
Currency.inspect
Section titled “Currency.inspect”impl Debug for Currency
fn inspect(currency: Currency) -> String
impl Debug.inspect
The typed literal that builds the currency.
Currency.equal
Section titled “Currency.equal”impl Equatable for Currency
fn equal(a: Currency, b: Currency) -> Bool
impl Equatable.equal
Currency.hash
Section titled “Currency.hash”impl Hashable for Currency
fn hash(value: Currency) -> Int
impl Hashable.hash
enum Error
Section titled “enum Error”enum Error Malformed { text: String } IsoCode { code: String } NotIso { code: String } Digits { digits: Int } end
Why text, or a code and its digits, are not a currency.
Variants
-
Malformedtextis not a code: a code is 1 to 12 ofA–Zand0–9, starting with a letter. -
IsoCodecodeis an ISO 4217 currency, whose minor digits CLDR gives, so it is not a custom one. -
NotIsocodeis not an ISO 4217 currency, so a custom currency of that code names its minor digits. -
Digitsdigitsis not a count of minor digits, 0 to 18.
Error.to_string
Section titled “Error.to_string”impl Display for Error
fn to_string(e: Error) -> String
impl Display.to_string
What is wrong, as a compile error at a Currency"…" literal shows
it.
assert Display.to_string(Error.IsoCode{code: "EUR"})
== "`EUR` is an ISO 4217 currency, whose minor digits CLDR gives: write Currency\"EUR\""
assert Display.to_string(
Error.NotIso{code: "BTC"}
) == "`BTC` is not an ISO 4217 currency: a custom currency names its minor digits, as Currency\"BTC:2\""
Error.inspect
Section titled “Error.inspect”impl Debug for Error
fn inspect(value: Error) -> String
impl Debug.inspect
Error.equal
Section titled “Error.equal”impl Equatable for Error
fn equal(a: Error, b: Error) -> Bool
impl Equatable.equal