Skip to content

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.

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 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"
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"})
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"})
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"
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
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")

impl Literal for Currency

fn from_fragments(fragments: List<Fragment<String>>) -> Result<Currency, Error>

impl Literal.from_fragments

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.

impl Display for Currency

fn to_string(currency: Currency) -> String

impl Display.to_string

The code.

impl Debug for Currency

fn inspect(currency: Currency) -> String

impl Debug.inspect

The typed literal that builds the currency.

impl Equatable for Currency

fn equal(a: Currency, b: Currency) -> Bool

impl Equatable.equal

impl Hashable for Currency

fn hash(value: Currency) -> Int

impl Hashable.hash

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

  • Malformed

    text is not a code: a code is 1 to 12 of A–Z and 0–9, starting with a letter.

  • IsoCode

    code is an ISO 4217 currency, whose minor digits CLDR gives, so it is not a custom one.

  • NotIso

    code is not an ISO 4217 currency, so a custom currency of that code names its minor digits.

  • Digits

    digits is not a count of minor digits, 0 to 18.

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\""

impl Debug for Error

fn inspect(value: Error) -> String

impl Debug.inspect

impl Equatable for Error

fn equal(a: Error, b: Error) -> Bool

impl Equatable.equal