The abstract type of objects representing a single value in one currency, or a collection of values in a set of currencies. These objects should behave like Monetary or Basket objects.

A representation of a monetary value, denominated in some currency. The currency used is part of the type and not the object. The value is internally represented as a quantity of some integer type. The usual way to construct a Monetary directly, if needed, is:

Monetary(:USD)      # 1.00 USD
Monetary(:USD, 325) # 3.25 USD

Be careful about the decimal point, as the Monetary constructor takes an integer, representing the number of smallest denominations of the currency. Typically, this constructor is not called directly. It is easier to use the @usingcurrencies macro and the 100USD form instead.

Although this type is flexible enough to support values internally represented as any integer type, such as BigInt, it is recommended to use the built-in Int type on your architecture unless you need a bigger type. Do not mix different kinds of internal types. To use a different internal representation, change the type of the second argument to Monetary:

Monetary(:USD, BigInt(100))

In some applications, the minor denomination of a currency is not precise enough. It is sometimes useful to override the number of decimal points stored. For these applications, a third type parameter can be provided, indicating the number of decimal points to keep after the major denomination:

Monetary{:USD, BigInt, 4}(10000)            # 1.0000 USD
Monetary(:USD, BigInt(10000); precision=4)  # 1.0000 USD

currency(m::Monetary) → Symbol

Return a symbol corresponding to the ISO 4217 currency code of the currency that the given monetary amount is representing. For example, currency(80USD) will return :USD. If the given monetary value is of a non-ISO 4217 currency, then the returned symbol should contain only lowercase letters.

Prefer iso4217alpha to this function if a string is desired.

Get a brief human-readable English-language description of the currency. The description should begin with the common name of the currency, which should describe it unambiguously (up to variations on the same currency). Optionally, parentheses following the main description may include additional information (such as the unit of a major currency unit).

This function may be called with either a symbol, a Monetary type, or a Monetary object.

decimals(m::Monetary) → Int
decimals(s::Symbol)   → Int
decimals(d::DataType) → Int

Get the precision, in terms of the number of decimal places after the major currency unit, of the given Monetary value or type. Alternatively, if given a symbol, gets the default exponent (the number of decimal places to represent the minor currency unit) for that symbol. Return -1 if there is no sane minor unit, such as for several kinds of precious metal.

iso4217alpha(s::Symbol)   → String
iso4217alpha(m::Monetary) → String
iso4217alpha(t::DataType) → String

Get the ISO 4217 alphabetic code for a currency. For custom currencies, a lowercase string will be returned, and this should not be interpreted as an ISO 4217 code. Otherwise, a three-letter uppercase string will be returned. This function may be called with either a symbol, a Monetary type, or a Monetary object.

iso4217num(s::Symbol)   → Int
iso4217num(m::Monetary) → Int
iso4217num(t::DataType) → Int

Get the ISO 4217 numeric code for a currency. For custom currencies, a value of 0 will be returned. This function may be called with either a symbol, a Monetary type, or a Monetary object. Note that most applications should zero-pad this code to three digits.

longsymbol(s::Symbol)   → String
longsymbol(m::Monetary) → String
longsymbol(t::DataType) → String

Get a commonly-used currency symbol for a currency, with at least enough disambiguation to be non-ambiguous. This function may be called with either a symbol, a Monetary type, or a Monetary object.

majorunit(s::Symbol)   → Monetary{s}
majorunit(m::Monetary) → typeof(m)
majorunit(t::DataType) → t

Get the major unit of the currency. This function may be called with either a symbol, a Monetary type, or a Monetary object.

Add a new currency to the (global) currency list and return a unit for that currency. Prefer the @usingcustomcurrency macro, which leads to more clear code, whenever possible. This function takes three arguments: the symbol for the currency, a string description of the currency (following the conventions outlined in the documentation for currencyinfo), and an exponent representing the number of decimal points to describe the minor currency unit in terms of the major currency unit. Conventionally, the symbol used to describe custom currencies should consist of only lowercase letters.

btc = newcurrency!(:btc, "Bitcoin", 8)  # 1.00000000 BTC

shortsymbol(s::Symbol)   → String
shortsymbol(m::Monetary) → String
shortsymbol(t::DataType) → String

Get a short, possibly ambiguous, commonly-used symbol for a currency. This function may be called with either a symbol, a Monetary type, or a Monetary object.

Export each given currency symbol into the current namespace. The individual unit exported will be a full unit of the currency specified, not the smallest possible unit. For instance, @usingcurrencies EUR will export EUR, a currency unit worth 1€, not a currency unit worth 0.01€.

@usingcurrencies EUR, GBP, AUD
7AUD  # 7.00 AUD

There is no sane unit for certain currencies like XAU or XAG, so this macro does not work for those. Instead, define them manually:

const XAU = Monetary(:XAU; precision=4)

Add a new currency to the (global) currency list and assign a variable in the local namespace to that currency's unit. Provide three arguments: an identifier for the currency, a string description of the currency (following the conventions outlined in the documentation for currencyinfo), and an exponent representing the number of decimal points to describe the minor currency unit in terms of the major currency unit. Conventionally, the identifer used to describe custom currencies should consist of only lowercase letters.

@usingcustomcurrency btc "Bitcoin" 8
10btc  # 10.00000000 btc

A simpler variant of Monetary that is expected to eventually be the default. The currency represented is part of the type and not the object. The value is internally represented as a quantity of some number type. The usual way to construct a Currency directly, if needed, is:

Currency{:USD}(FixedDecimal{Int, 2}(1))  # 1.00 USD

filltype(typ) → typ

Fill in default type parameters to get a fully-specified concrete type from a partially-specified one.