Bankster library, front API version 2 currency helpers.
Bankster library, front API version 2 currency helpers.
(->edn currency)(->edn currency opts)Serializes currency to an EDN tagged literal string.
Serializes currency to an EDN tagged literal string.
(->json currency)(->json currency opts)Serializes currency to a JSON string identifier.
Serializes currency to a JSON string identifier.
(->map currency)Coerces a currency representation to a map of fields.
Coerces a currency representation to a map of fields.
(add-countries registry currency-id country-ids)Associates the given country or countries with a currency. If the currency does not exist, exception is thrown. If the currency exists but differs in any detail from the existing currency from the registry, exception is thrown. If the currency exists and equals to the given in any aspect, country associations are added. Links from other countries to the currency are not removed unless the country is already linked with some other currency; in this case it will be unlinked first.
Associates the given country or countries with a currency. If the currency does not exist, exception is thrown. If the currency exists but differs in any detail from the existing currency from the registry, exception is thrown. If the currency exists and equals to the given in any aspect, country associations are added. Links from other countries to the currency are not removed unless the country is already linked with some other currency; in this case it will be unlinked first.
(add-countries! currency country-ids)Associates the given country (a keyword) or countries (seqable collection of keywords) with a currency in the global registry. If the currency does not exist, exception is thrown. If the currency exists but differs in any detail from the existing currency from the registry, exception is thrown. If the currency exists and equals to the given in any aspect, country associations are added. Links from other countries to the currency are not removed unless the country is already linked with some other currency; in this case it will be unlinked first.
If the currency is nil, returns current state of a global registry (but not a dynamic registry, even if it is set).
Associates the given country (a keyword) or countries (seqable collection of keywords) with a currency in the global registry. If the currency does not exist, exception is thrown. If the currency exists but differs in any detail from the existing currency from the registry, exception is thrown. If the currency exists and equals to the given in any aspect, country associations are added. Links from other countries to the currency are not removed unless the country is already linked with some other currency; in this case it will be unlinked first. If the currency is nil, returns current state of a global registry (but not a dynamic registry, even if it is set).
(add-localized-properties registry currency-id properties)Adds localized properties of a currency to the given registry. Overwrites existing properties.
Adds localized properties of a currency to the given registry. Overwrites existing properties.
(add-localized-props! currency properties)Associates the given currency with a map of localized properties.
If the currency is nil, returns current state of a global registry (but not a dynamic registry, even if it is set).
Associates the given currency with a map of localized properties. If the currency is nil, returns current state of a global registry (but not a dynamic registry, even if it is set).
(add-traits registry currency-id traits)Adds traits for the given currency in the registry (union).
Passing nil or an empty collection is a no-op.
Throws when the currency cannot be resolved in the registry.
Adds traits for the given currency in the registry (union). Passing `nil` or an empty collection is a no-op. Throws when the currency cannot be resolved in the registry.
(add-traits! currency-id traits)Adds traits for the given currency in the global registry. See add-traits.
Adds traits for the given currency in the global registry. See `add-traits`.
(add-weighted-code registry currency-id)Associates the existing currency code with the currency object in the given registry using the currency weight attribute. The given currency-id may be expressed with any object that can be used to get the currency from a registry (internally the unit function is used). Therefore, passing the currency object having a different weight will not cause the weight to be updated since it will be used for identification only.
Currency must exist in the cur-id->cur database of the registry. This function will add an association to the cur-code->curs database. If both, the weight and code are the same, registry is returned as is.
This is a low-level function used to ensure that a code-to-currency mapping is created within a registry. To simply update currency's weight, use the update or update! function.
Associates the existing currency code with the currency object in the given registry using the currency weight attribute. The given currency-id may be expressed with any object that can be used to get the currency from a registry (internally the unit function is used). Therefore, passing the currency object having a different weight will not cause the weight to be updated since it will be used for identification only. Currency must exist in the cur-id->cur database of the registry. This function will add an association to the cur-code->curs database. If both, the weight and code are the same, registry is returned as is. This is a low-level function used to ensure that a code-to-currency mapping is created within a registry. To simply update currency's weight, use the update or update! function.
(all)(all registry)Returns a sequence of all Currency objects in a registry or nil if there are
no currencies.
Delegates to io.randomseed.bankster.currency/all.
Returns a sequence of all `Currency` objects in a registry or `nil` if there are no currencies. Delegates to `io.randomseed.bankster.currency/all`.
(asset? c)(asset? c registry)Returns true if the given currency is a kind of asset.
Returns `true` if the given currency is a kind of asset.
(attempt c)(attempt c registry)Soft currency coercion function.
Returns c when it is already an instance of io.randomseed.bankster.Currency.
If c is a definitive currency representation (see Monetary/definitive?), it is
coerced locally using to-currency. Otherwise it attempts to resolve c in a
registry and returns the registered Currency instance or nil when it cannot be
resolved.
This is intended for "non-throwing" code paths (e.g. property predicates) and
complements unit and of-id which may throw when a currency is missing.
Soft currency coercion function. Returns `c` when it is already an instance of `io.randomseed.bankster.Currency`. If `c` is a definitive currency representation (see `Monetary/definitive?`), it is coerced locally using `to-currency`. Otherwise it attempts to resolve `c` in a registry and returns the registered `Currency` instance or `nil` when it cannot be resolved. This is intended for "non-throwing" code paths (e.g. property predicates) and complements `unit` and `of-id` which may throw when a currency is missing.
(attempt* c)(attempt* c registry)Soft currency coercion macro.
Returns c when it is already an instance of io.randomseed.bankster.Currency.
If c is a definitive currency representation (see Monetary/definitive?), it is
coerced locally using to-currency. Otherwise it attempts to resolve c in a
registry and returns the registered Currency instance or nil when it cannot be
resolved.
Unlike unit and of-id, this helper is meant to be used in "non-throwing" code
paths (e.g. property predicates). Argument c is evaluated exactly once.
When registry is not provided, the default registry is used (preferring
io.randomseed.bankster.registry/*default* when bound).
Soft currency coercion macro. Returns `c` when it is already an instance of `io.randomseed.bankster.Currency`. If `c` is a definitive currency representation (see `Monetary/definitive?`), it is coerced locally using `to-currency`. Otherwise it attempts to resolve `c` in a registry and returns the registered `Currency` instance or `nil` when it cannot be resolved. Unlike `unit` and `of-id`, this helper is meant to be used in "non-throwing" code paths (e.g. property predicates). Argument `c` is evaluated exactly once. When `registry` is not provided, the default registry is used (preferring `io.randomseed.bankster.registry/*default*` when bound).
Represents the scale of a currency that is automatic and not limited to specific decimal places.
Note: This is an alias for scale/auto-scaled. The canonical definition lives in
io.randomseed.bankster.scale.
Represents the scale of a currency that is automatic and not limited to specific decimal places. Note: This is an alias for `scale/auto-scaled`. The canonical definition lives in `io.randomseed.bankster.scale`.
(auto-scaled? currency)(auto-scaled? currency registry)Returns true if the currency scale is auto-scaled.
Delegates to io.randomseed.bankster.currency/auto-scaled?.
Returns `true` if the currency scale is auto-scaled. Delegates to `io.randomseed.bankster.currency/auto-scaled?`.
(big? c)(big? c registry)Returns true if the given currency has an automatic scale (decimal places).
Returns `true` if the given currency has an automatic scale (decimal places).
(claim? c)(claim? c registry)Returns true if the given currency is a kind of claim.
Returns `true` if the given currency is a kind of claim.
(clear-weight registry currency-id)Removes an explicit weight entry for the given currency from the registry (defaults to weight 0) and updates all weight-dependent indexes.
Throws when the currency cannot be resolved in the registry.
Removes an explicit weight entry for the given currency from the registry (defaults to weight 0) and updates all weight-dependent indexes. Throws when the currency cannot be resolved in the registry.
(clear-weight! currency-id)Clears an explicit currency weight entry in the global registry. See clear-weight.
Clears an explicit currency weight entry in the global registry. See `clear-weight`.
(code currency)(code currency registry)Returns currency code as a string (without namespace).
Delegates to io.randomseed.bankster.currency/code.
Returns currency code as a string (without namespace). Delegates to `io.randomseed.bankster.currency/code`.
(code-literal arg)Tagged literal handler for Clojure code. Emits compound forms that are going to be evaluated.
Tagged literal handler for Clojure code. Emits compound forms that are going to be evaluated.
(code-str currency)Returns a currency code string without interning keywords.
Delegates to io.randomseed.bankster.currency/to-code-str.
Returns a currency code string without interning keywords. Delegates to `io.randomseed.bankster.currency/to-code-str`.
(codes)(codes registry)Returns a sequence of keywords for all currency codes (without namespaces!) in a
registry or nil if there are no currencies with codes. When registry is not given
or nil, the default is used.
Returns a sequence of keywords for all currency codes (without namespaces!) in a registry or `nil` if there are no currencies with codes. When registry is not given or `nil`, the default is used.
(commodity? c)(commodity? c registry)Returns true if the given currency is a kind of commodity currency.
Returns `true` if the given currency is a kind of commodity currency.
(config->registry)(config->registry resource-path)(config->registry resource-path regi)Loads currencies and countries from an EDN file. First argument should be a string with path to the EDN resource file containing registry data, second should be a registry. Returns a registry initialized using values from the EDN file.
Loads currencies and countries from an EDN file. First argument should be a string with path to the EDN resource file containing registry data, second should be a registry. Returns a registry initialized using values from the EDN file.
(countries c)(countries c registry)(countries c _locale registry)Returns a set of country IDs (keywords) for which the given currency is main currency. If there are no countries associated with a currency, returns nil. Locale argument is ignored.
Throws when a currency cannot be resolved in the registry. This lets consumers
distinguish "no countries" (nil) from "unknown currency" (exception).
Returns a set of country IDs (keywords) for which the given currency is main currency. If there are no countries associated with a currency, returns nil. Locale argument is ignored. Throws when a currency cannot be resolved in the registry. This lets consumers distinguish "no countries" (`nil`) from "unknown currency" (exception).
(credit? c)(credit? c registry)Returns true if the given currency is a kind of credit.
Returns `true` if the given currency is a kind of credit.
(crypto? currency)(crypto? currency registry)Returns true if the given currency is a cryptocurrency.
Delegates to io.randomseed.bankster.currency/crypto?.
Returns `true` if the given currency is a cryptocurrency. Delegates to `io.randomseed.bankster.currency/crypto?`.
(currency? x)Returns true when x is an instance of io.randomseed.bankster.Currency.
Returns `true` when `x` is an instance of `io.randomseed.bankster.Currency`.
(data-literal arg)Tagged literal handler for EDN data files. Emits Currency objects or nil values.
Tagged literal handler for EDN data files. Emits Currency objects or nil values.
(decentralised? c)(decentralised? c registry)Alias for decentralized?
Alias for decentralized?
(decentralized? currency)(decentralized? currency registry)Returns true if the given currency is a kind of decentralized currency.
Delegates to io.randomseed.bankster.currency/decentralized?.
Returns `true` if the given currency is a kind of decentralized currency. Delegates to `io.randomseed.bankster.currency/decentralized?`.
(default-registry)Returns the default registry (honors io.randomseed.bankster.registry/*default*).
Returns the default registry (honors `io.randomseed.bankster.registry/*default*`).
(defined? currency)(defined? currency registry)Returns true if any currency can be resolved from the given value.
Returns `true` if any currency can be resolved from the given value.
(definitive? currency)Returns true if the given value is a definitive currency representation.
Returns `true` if the given value is a definitive currency representation.
(display-name currency)(display-name currency locale)(display-name currency locale registry)Returns a currency display name as a string for the given currency object and locale. If the locale is not given, a default one is used. Uses global registry if a registry is not given.
The following tactic is applied:
The registry field .cur-id->localized is looked up for the currency ID key. If
it's found then a key with the given locale object (a kind of java.util.Locale)
is obtained. If there is no such key, the default one :* is tried (a keyword). The
resulting value should be a map of localized properties in which an entry under the
key :symbol should exist. Its value will be returned, if found.
If the above method failed and the given currency is ISO-standardized then Java methods will be tried to obtain it.
If the above method failed a currency code will be returned.
A locale can be expressed as java.util.Locale object or any other object (like a
string or a keyword) which can be used to look up the locale.
Returns a currency display name as a string for the given currency object and locale. If the locale is not given, a default one is used. Uses global registry if a registry is not given. The following tactic is applied: - The registry field .cur-id->localized is looked up for the currency ID key. If it's found then a key with the given locale object (a kind of `java.util.Locale`) is obtained. If there is no such key, the default one :* is tried (a keyword). The resulting value should be a map of localized properties in which an entry under the key `:symbol` should exist. Its value will be returned, if found. - If the above method failed and the given currency is ISO-standardized then Java methods will be tried to obtain it. - If the above method failed a currency code will be returned. A locale can be expressed as `java.util.Locale` object or any other object (like a string or a keyword) which can be used to look up the locale.
(display-name-native currency)(display-name-native currency registry)Like display-name but for ISO-standardized currencies uses locale assigned to the first country where a currency is the default. When locale is given it is ignored.
Like display-name but for ISO-standardized currencies uses locale assigned to the first country where a currency is the default. When locale is given it is ignored.
(domain currency)(domain currency registry)Returns currency domain as a keyword or nil.
Returns currency domain as a keyword or `nil`.
(domains)(domains registry)Returns a sequence of keywords for all currency domains in a registry or nil if
there are no currencies with domains. When registry is not given or nil, the
default is used.
Returns a sequence of keywords for all currency domains in a registry or `nil` if there are no currencies with domains. When registry is not given or `nil`, the default is used.
(experimental? c)(experimental? c registry)Returns true if the given currency is a kind of experimental currency.
Returns `true` if the given currency is a kind of experimental currency.
(fiat? c)(fiat? c registry)Returns true if the given currency is a kind of fiat currency.
Returns `true` if the given currency is a kind of fiat currency.
(fiduciary? c)(fiduciary? c registry)Returns true if the given currency is a kind of fiduciary currency.
Returns `true` if the given currency is a kind of fiduciary currency.
(formatter currency)(formatter currency locale)(formatter currency locale registry)Returns currency formatter as java.text.DecimalFormat instance for the given
currency and locale. If locale is not given the default one will be used. Due to
caching strategy it is advised to express locale with a keyword.
The formatter is a mutable clone of Java data structure.
In case of currencies other than ISO-standardized (and predefined in Java) the currency field of this formatter will be set to the currency of XXX.
Returns currency formatter as `java.text.DecimalFormat` instance for the given currency and locale. If locale is not given the default one will be used. Due to caching strategy it is advised to express locale with a keyword. The formatter is a mutable clone of Java data structure. In case of currencies other than ISO-standardized (and predefined in Java) the currency field of this formatter will be set to the currency of XXX.
(formatter-extended currency)(formatter-extended currency locale)(formatter-extended currency locale opts)(formatter-extended currency
locale
{:keys [scale rounding-mode grouping grouping-size
negative-prefix negative-suffix positive-prefix
positive-suffix always-sep-dec currency-symbol-fn
min-fraction-digits max-fraction-digits
min-integer-digits max-integer-digits]
:as opts}
registry)Returns a currency formatter as java.text.DecimalFormat instance for the given
currency, customizable with the given opts map. If the locale is not given then the
default one will be used. Due to caching strategy it is advised to express locale
with a keyword.
The formatter is a mutable clone of Java data structure.
In case of currencies other than ISO-standardized (and predefined in Java) the currency field of this formatter will be set to the currency of XXX.
Options map can have the following keys:
:rounding-mode - RoundingMode, rounding mode to apply when scaling:grouping - Boolean, if true then grouping will be used:grouping-size - integer, size of a group when grouping:negative-prefix - String, negative prefix to use:negative-suffix - String, negative suffix to use:positive-prefix - String, positive prefix to use:positive-suffix - String, positive suffix to use:always-sep-dec - Boolean, if true then the decimal separator will always be shown:currency-symbol-fn - a function used on a bankster/Currency object to get its symbol as a string:min-fraction-digits - integer, the minimum number of digits allowed in the fraction portion of an amount:min-integer-digits - integer, the minimum number of digits allowed in the integer portion of an amount:max-fraction-digits - integer, the maximum number of digits allowed in the fraction portion of an amount:max-integer-digits - integer, the maximum number of digits allowed in the integer portion of an amount:scale - sets both :min-fraction-digits and :max-fraction-digits to the same value.When choosing different currency, all parameters of a formatter are initially set to that currency. Additionally re-scaling may take place for the amount if scales are different.
The function assigned to the :currency-symbol-fn should take 3 arguments:
currency, locale and registry.
It is advised to express locale using a keyword when huge amount of operations is expected.
Returns a currency formatter as `java.text.DecimalFormat` instance for the given currency, customizable with the given opts map. If the locale is not given then the default one will be used. Due to caching strategy it is advised to express locale with a keyword. The formatter is a mutable clone of Java data structure. In case of currencies other than ISO-standardized (and predefined in Java) the currency field of this formatter will be set to the currency of XXX. Options map can have the following keys: - `:rounding-mode` - RoundingMode, rounding mode to apply when scaling - `:grouping` - Boolean, if true then grouping will be used - `:grouping-size` - integer, size of a group when grouping - `:negative-prefix` - String, negative prefix to use - `:negative-suffix` - String, negative suffix to use - `:positive-prefix` - String, positive prefix to use - `:positive-suffix` - String, positive suffix to use - `:always-sep-dec` - Boolean, if true then the decimal separator will always be shown - `:currency-symbol-fn` - a function used on a bankster/Currency object to get its symbol as a string - `:min-fraction-digits` - integer, the minimum number of digits allowed in the fraction portion of an amount - `:min-integer-digits` - integer, the minimum number of digits allowed in the integer portion of an amount - `:max-fraction-digits` - integer, the maximum number of digits allowed in the fraction portion of an amount - `:max-integer-digits` - integer, the maximum number of digits allowed in the integer portion of an amount - `:scale` - sets both `:min-fraction-digits` and `:max-fraction-digits` to the same value. When choosing different currency, all parameters of a formatter are initially set to that currency. Additionally re-scaling may take place for the amount if scales are different. The function assigned to the `:currency-symbol-fn` should take 3 arguments: currency, locale and registry. It is advised to express locale using a keyword when huge amount of operations is expected.
(from-edn x)(from-edn x opts)Deserializes Currency from EDN string, keyword, or map.
Deserializes Currency from EDN string, keyword, or map.
(from-edn-text x)(from-edn-text x opts)Deserializes Currency from raw EDN text.
Deserializes Currency from raw EDN text.
(from-json x)(from-json x opts)Deserializes Currency from JSON string or map.
Deserializes Currency from JSON string or map.
(from-json-text x)(from-json-text x opts)Deserializes Currency from raw JSON text.
Deserializes Currency from raw JSON text.
(funds? c)(funds? c registry)Returns true if the given currency is a kind of funds/settlement currency.
Returns `true` if the given currency is a kind of funds/settlement currency.
(has-country? c)(has-country? c registry)Returns true if the given currency has at least one country for which it is an
official currency.
Returns `true` if the given currency has at least one country for which it is an official currency.
(has-domain? c)(has-domain? c registry)(has-domain? c ns)(has-domain? c ns registry)Returns true if the given currency c has its domain defined (when only currency
and optional registry is given). If ns is given it returns true if the currency
has its domain set to be the exact keyword given.
Returns `true` if the given currency `c` has its domain defined (when only currency and optional registry is given). If `ns` is given it returns `true` if the currency has its domain set to be the exact keyword given.
(has-kind? c)(has-kind? c registry)(has-kind? c tag registry)Returns true if the given currency c has its kind defined (when only currency
and optional registry is given). If tag is given it returns true if the
currency has its kind set to be the exact keyword given.
Returns `true` if the given currency `c` has its kind defined (when only currency and optional registry is given). If `tag` is given it returns `true` if the currency has its kind set to be the exact keyword given.
(has-numeric-id? c)(has-numeric-id? c registry)Returns true if the given currency has a numeric ID.
Returns `true` if the given currency has a numeric ID.
(has-trait? c)(has-trait? c registry)(has-trait? c tag)(has-trait? c tag registry)Returns true if the given currency c has any trait defined (when only currency
and optional registry is given). If tag is given it returns true if the
currency has one of its traits set to be the exact keyword given.
Traits are registry attributes (stored in Registry/:cur-id->traits). Any :traits
extension field present on ad-hoc Currency values is ignored.
Returns `true` if the given currency `c` has any trait defined (when only currency and optional registry is given). If `tag` is given it returns `true` if the currency has one of its traits set to be the exact keyword given. Traits are registry attributes (stored in `Registry/:cur-id->traits`). Any `:traits` extension field present on ad-hoc `Currency` values is ignored.
(id currency)(id currency registry)Returns currency ID (keyword).
Delegates to io.randomseed.bankster.currency/id.
([currency]) is registry-light: it may return a keyword even if the currency
is not registered.([currency registry]) is strict when registry is non-nil.Returns currency ID (keyword). Delegates to `io.randomseed.bankster.currency/id`. - `([currency])` is registry-light: it may return a keyword even if the currency is not registered. - `([currency registry])` is strict when `registry` is non-nil.
(id-str currency)Returns a currency identifier string without interning keywords.
Delegates to io.randomseed.bankster.currency/to-id-str.
Returns a currency identifier string without interning keywords. Delegates to `io.randomseed.bankster.currency/to-id-str`.
(ids)(ids registry)Returns a sequence of keywords for all currencies in a registry or nil if there
are no currencies. When registry is not given or nil, the default is used.
Returns a sequence of keywords for all currencies in a registry or `nil` if there are no currencies. When registry is not given or `nil`, the default is used.
(in-domain? ns c)(in-domain? ns c registry)Returns true if the given currency has a domain set to the first given argument.
Returns `true` if the given currency has a domain set to the first given argument.
(info currency)(info currency registry)(info currency locale registry)Returns a map describing the given currency, including registry-associated properties when available.
Base fields come from the currency's map representation (via into {}) and include
any extension fields. When a registry can be consulted (default or explicitly
passed), this function also adds:
:countries - a set of associated country IDs,:localized - a localized properties map (locale keywords, including :*),:traits - a set of associated traits.Returns nil when the given value points to a registry currency but cannot be
resolved. Locale argument is ignored.
When registry is true, the default registry is used.
Returns a map describing the given currency, including registry-associated
properties when available.
Base fields come from the currency's map representation (via `into {}`) and include
any extension fields. When a registry can be consulted (default or explicitly
passed), this function also adds:
- `:countries` - a set of associated country IDs,
- `:localized` - a localized properties map (locale keywords, including `:*`),
- `:traits` - a set of associated traits.
Returns `nil` when the given value points to a registry currency but cannot be
resolved. Locale argument is ignored.
When `registry` is `true`, the default registry is used.(iso-legacy? c)(iso-legacy? c registry)Returns true if the given currency was an official currency but is now considered a
legacy currency having an identifier compliant with the ISO standard. It is just a
helper which checks if the :domain field of a currency equals to
:ISO-4217-LEGACY.
Returns `true` if the given currency was an official currency but is now considered a legacy currency having an identifier compliant with the ISO standard. It is just a helper which checks if the `:domain` field of a currency equals to `:ISO-4217-LEGACY`.
(iso-possible? c)(iso-possible? c registry)Returns true if the given value is a possible ISO-4217 currency: can be used to
get an ISO currency from a registry, can be used to create ISO currency on its own,
or is an ISO currency.
This predicate is semantically wide. If the string or keyword alone cannot be used
to create a valid, ad-hoc ISO currency but it can get an ISO currency from a
registry, then the function will return true. Same for certain numbers: if they
cannot be used to create an ISO currency on their own (since there is no ID) but
can be used to look one up in a registry (treating a number as an ISO-4217 code),
they will be positively tested as possible values for currency creation (if there
was a hit).
If registry is not given or is nil, the default one is used.
Returns `true` if the given value is a possible ISO-4217 currency: can be used to get an ISO currency from a registry, can be used to create ISO currency on its own, or is an ISO currency. This predicate is semantically wide. If the string or keyword alone cannot be used to create a valid, ad-hoc ISO currency but it can get an ISO currency from a registry, then the function will return `true`. Same for certain numbers: if they cannot be used to create an ISO currency on their own (since there is no ID) but can be used to look one up in a registry (treating a number as an ISO-4217 code), they will be positively tested as possible values for currency creation (if there was a hit). If `registry` is not given or is `nil`, the default one is used.
(iso-strict-code? kid)Returns true when the given currency code, expressed as a keyword, is exactly a
3-character, simple keyword consisting only of uppercase letters in the range A-Z.
Otherwise it returns false.
Returns `true` when the given currency code, expressed as a keyword, is exactly a 3-character, simple keyword consisting only of uppercase letters in the range A-Z. Otherwise it returns `false`.
(iso-strict? c)(iso-strict? c registry)Returns true if the given currency is an official currency which is currently in
use (not a legacy money) and its both identifier and numerical identifier is
compliant with the ISO standard.
Returns `true` if the given currency is an official currency which is currently in use (not a legacy money) and its both identifier and numerical identifier is compliant with the ISO standard.
(iso? c)(iso? c registry)Returns true if the given currency is classified as ISO because its kind is set to
:iso or its descendants. It may include not just current ISO currencies but also
legacy ones. See also io.randomseed.bankster.currency/iso-strict?.
Returns `true` if the given currency is classified as ISO because its kind is set to `:iso` or its descendants. It may include not just current ISO currencies but also legacy ones. See also `io.randomseed.bankster.currency/iso-strict?`.
(java currency)(java currency registry)For ISO-standardized currency, returns corresponding java.util.Currency object. If
the currency does not exist, is not ISO (its :domain is not :ISO-4217), has a
different scale (fraction digits), or a different numeric code, nil is returned.
For ISO-standardized currency, returns corresponding `java.util.Currency` object. If the currency does not exist, is not ISO (its `:domain` is not `:ISO-4217`), has a different scale (fraction digits), or a different numeric code, `nil` is returned.
A set of Java currencies (instances of java.util.Currency, including obsolete
currencies).
A set of Java currencies (instances of `java.util.Currency`, including obsolete currencies).
(kind currency)(kind currency registry)Returns currency kind as a keyword or nil.
Returns currency kind as a keyword or `nil`.
(kinds)(kinds registry)Returns a map of all registered currency kinds as keys and their ancestors as
sets. It will not contain ad-hoc kinds that wasn't added to a registry's
hierarchy. Uses the given registry or a global one.
Returns a map of all registered currency kinds as keys and their ancestors as sets. It will not contain ad-hoc kinds that wasn't added to a registry's hierarchy. Uses the given `registry` or a global one.
(legacy? c)(legacy? c registry)Alias for iso-legacy?
Alias for iso-legacy?
(localized-properties c)(localized-properties c registry)Returns a map of localized properties for the given currency. Locale objects are translated back to their keyword representations.
Throws when a currency cannot be resolved in the registry. Returns nil when there
are no localized properties for the currency.
Returns a map of localized properties for the given currency. Locale objects are translated back to their keyword representations. Throws when a currency cannot be resolved in the registry. Returns `nil` when there are no localized properties for the currency.
(localized-property property currency-id)(localized-property property currency-id locale)(localized-property property currency-id locale registry)Gets the localized property of a currency from the given registry and locale. If the registry is not given, the global one will be used. If the locale is not given, the default locale for the environment will be used. Locale can be expressed as a Locale object or any object which can be used to identify the locale (e.g. a keyword or a string).
Throws when a currency cannot be resolved in the registry. Returns nil when the
property is not present for the currency or when the currency has no localized
properties.
Localized properties are maps keyed by currency identifiers, containing another maps keyed by locale objects. There is a special key :* which identifies default properties used when there are no properties in locale-keyed maps.
Let's take a hypothetical entry of a registry database .cur-id->localized:
{:XXX {#object[java.util.Locale 0x3f5af72f "en_US"] {:symbol "$"}}
{#object[java.util.Locale 0x3f5af72f "en"] {:symbol "X$"}
{:* {:symbol "ABC"}}
(localized-property :symbol :XXX :en_US) will return $.(localized-property :symbol :XXX :en_GB) will return X$.(localized-property :symbol :XXX :pl_PL) will return ABC.The first is self-explanatory.
The second falls back to en because the function will re-try the language
part (en) alone when the property was not found. The same method is repeatedly
applied to other components of a locale (variant, script and extensions – if
any). So for the locale identified by th_TH_TH_#u-nu-thai the following keys will
be tried:
th_TH_TH_#u-nu-thai,th_TH_TH_#u-nu,th_TH_TH_#u,th_TH_TH,th_TH and th.The third example renders ABC because there is an entry of :symbol in the
default properties map under the key :*.
Please note that functions for getting particular properties may apply additional steps to obtain them. For instance, the display-name function will first call the localized-property and if it fails it will fall back to Java methods (if the currency is ISO-standardized). If that will fail too then it will return a currency code.
Gets the localized property of a currency from the given registry and locale. If the
registry is not given, the global one will be used. If the locale is not given, the
default locale for the environment will be used. Locale can be expressed as a
Locale object or any object which can be used to identify the locale (e.g. a keyword
or a string).
Throws when a currency cannot be resolved in the registry. Returns `nil` when the
property is not present for the currency or when the currency has no localized
properties.
Localized properties are maps keyed by currency identifiers, containing another
maps keyed by locale objects. There is a special key :* which identifies default
properties used when there are no properties in locale-keyed maps.
Let's take a hypothetical entry of a registry database `.cur-id->localized`:
```clojure
{:XXX {#object[java.util.Locale 0x3f5af72f "en_US"] {:symbol "$"}}
{#object[java.util.Locale 0x3f5af72f "en"] {:symbol "X$"}
{:* {:symbol "ABC"}}
```
* Calling `(localized-property :symbol :XXX :en_US)` will return `$`.
* Calling `(localized-property :symbol :XXX :en_GB)` will return `X$`.
* Calling `(localized-property :symbol :XXX :pl_PL)` will return `ABC`.
The first is self-explanatory.
The second falls back to `en` because the function will re-try the language
part (`en`) alone when the property was not found. The same method is repeatedly
applied to other components of a locale (variant, script and extensions – if
any). So for the locale identified by `th_TH_TH_#u-nu-thai` the following keys will
be tried:
- `th_TH_TH_#u-nu-thai`,
- `th_TH_TH_#u-nu`,
- `th_TH_TH_#u`,
- `th_TH_TH`,
- `th_TH` and `th`.
The third example renders `ABC` because there is an entry of `:symbol` in the
default properties map under the key `:*`.
Please note that functions for getting particular properties may apply additional
steps to obtain them. For instance, the display-name function will first call the
localized-property and if it fails it will fall back to Java methods (if the
currency is ISO-standardized). If that will fail too then it will return a currency
code.(map->new m)Creates a new currency record from a map.
Creates a new currency record from a map.
(metal? c)(metal? c registry)Returns true if the given currency is a kind of precious metal.
Returns `true` if the given currency is a kind of precious metal.
The Monetary protocol describes basic operations on currencies. It uses single dispatch to allow currencies to be expressed with different kinds of data (keywords, symbols, strings, native Currency objects etc.).
Methods prefixed with to- are cheap, local, and registry-free coercions.
Methods resolve and resolve-all consult a registry to map hints to concrete
registered currencies.
The Monetary protocol describes basic operations on currencies. It uses single dispatch to allow currencies to be expressed with different kinds of data (keywords, symbols, strings, native Currency objects etc.). Methods prefixed with `to-` are cheap, local, and registry-free coercions. Methods `resolve` and `resolve-all` consult a registry to map hints to concrete registered currencies.
(name currency)(name currency locale)(name currency locale registry)Returns a currency display name for the given currency and locale.
Delegates to io.randomseed.bankster.currency/display-name.
Returns a currency display name for the given currency and locale. Delegates to `io.randomseed.bankster.currency/display-name`.
(name-native currency)(name-native currency registry)Alias for display-name-native.
Alias for display-name-native.
(new id)(new id numeric-id)(new id numeric-id scale)(new id numeric-id scale kind)(new id numeric-id scale kind domain)(new id numeric-id scale kind domain weight)Creates new currency record from values passed as arguments.
Identifier casing rules:
:pln -> :PLN,
:crypto/usdt -> :crypto/USDT).ISO-4217, which is treated
case-insensitively and always stripped).When the given id has the ISO-4217 namespace (case insensitive), it will be
stripped of it.
When the namespace ISO-4217 was removed from the ID, the domain will be set to
:ISO-4217, unless the domain argument is given and it is not nil.
In short: setting ISO-4217 namespace in id will always cause it to be removed,
and a new currency will be treated as if it was an ISO currency, unless the domain
was explicitly given.
Domain property will also be automatically set to :ISO-4217 when:
domain was not given (or is nil) and was not set automatically,numeric-id is given and is greater than 0,id is a simple keyword (after potential stripping the ISO namespace)
and consists of exactly 3 uppercase letters from A to Z only.Setting the domain manually to :ISO-4217 (with domain argument or by setting a
namespace of id to ISO-4217) will cause the currency to be treated as an ISO
currency without any checks regarding its scale or numerical identifier. Use with
caution. This is intended for applications requiring high elasticity.
Creates new currency record from values passed as arguments. Identifier casing rules: - Currency *name* (code) is canonicalized to upper-case (`:pln` -> `:PLN`, `:crypto/usdt` -> `:crypto/USDT`). - Namespace casing is preserved as provided (except `ISO-4217`, which is treated case-insensitively and always stripped). When the given `id` has the `ISO-4217` namespace (case insensitive), it will be stripped of it. When the namespace `ISO-4217` was removed from the ID, the domain will be set to `:ISO-4217`, unless the `domain` argument is given and it is not `nil`. In short: setting `ISO-4217` namespace in `id` will always cause it to be removed, and a new currency will be treated as if it was an ISO currency, unless the domain was explicitly given. Domain property will also be automatically set to `:ISO-4217` when: - `domain` was not given (or is `nil`) and was not set automatically, - `numeric-id` is given and is greater than 0, - the given `id` is a simple keyword (after potential stripping the ISO namespace) and consists of exactly 3 uppercase letters from A to Z only. Setting the domain manually to `:ISO-4217` (with `domain` argument or by setting a namespace of `id` to `ISO-4217`) will cause the currency to be treated as an ISO currency without any checks regarding its scale or numerical identifier. Use with caution. This is intended for applications requiring high elasticity.
(new-currency id)(new-currency id numeric-id)(new-currency id numeric-id scale)(new-currency id numeric-id scale kind)(new-currency id numeric-id scale kind domain)(new-currency id numeric-id scale kind domain weight)Creates new currency record from values passed as arguments.
Identifier casing rules:
:pln -> :PLN,
:crypto/usdt -> :crypto/USDT).ISO-4217, which is treated
case-insensitively and always stripped).When the given id has the ISO-4217 namespace (case insensitive), it will be
stripped of it.
When the namespace ISO-4217 was removed from the ID, the domain will be set to
:ISO-4217, unless the domain argument is given and it is not nil.
In short: setting ISO-4217 namespace in id will always cause it to be removed,
and a new currency will be treated as if it was an ISO currency, unless the domain
was explicitly given.
Domain property will also be automatically set to :ISO-4217 when:
domain was not given (or is nil) and was not set automatically,numeric-id is given and is greater than 0,id is a simple keyword (after potential stripping the ISO namespace)
and consists of exactly 3 uppercase letters from A to Z only.Setting the domain manually to :ISO-4217 (with domain argument or by setting a
namespace of id to ISO-4217) will cause the currency to be treated as an ISO
currency without any checks regarding its scale or numerical identifier. Use with
caution. This is intended for applications requiring high elasticity.
Creates new currency record from values passed as arguments. Identifier casing rules: - Currency *name* (code) is canonicalized to upper-case (`:pln` -> `:PLN`, `:crypto/usdt` -> `:crypto/USDT`). - Namespace casing is preserved as provided (except `ISO-4217`, which is treated case-insensitively and always stripped). When the given `id` has the `ISO-4217` namespace (case insensitive), it will be stripped of it. When the namespace `ISO-4217` was removed from the ID, the domain will be set to `:ISO-4217`, unless the `domain` argument is given and it is not `nil`. In short: setting `ISO-4217` namespace in `id` will always cause it to be removed, and a new currency will be treated as if it was an ISO currency, unless the domain was explicitly given. Domain property will also be automatically set to `:ISO-4217` when: - `domain` was not given (or is `nil`) and was not set automatically, - `numeric-id` is given and is greater than 0, - the given `id` is a simple keyword (after potential stripping the ISO namespace) and consists of exactly 3 uppercase letters from A to Z only. Setting the domain manually to `:ISO-4217` (with `domain` argument or by setting a namespace of `id` to `ISO-4217`) will cause the currency to be treated as an ISO currency without any checks regarding its scale or numerical identifier. Use with caution. This is intended for applications requiring high elasticity.
Represents the value of a currency's numeric ID when no ID exists.
Represents the value of a currency's numeric ID when no ID exists.
(none? c)(none? c registry)Returns true if the given currency does not exist, or there is no currency (value
is nil, false, an empty collection), or it is a pseudo-currency with its kind
set to :NULL or its descendants.
Returns `true` if the given currency does not exist, or there is no currency (value is `nil`, `false`, an empty collection), or it is a pseudo-currency with its kind set to `:NULL` or its descendants.
(normalize currency)Normalizes currency literal input to a canonical representation.
Unwraps single-element vectors, keywordizes :id in maps, and normalizes symbols
to keywords when possible. Delegates to currency/parse-currency-code.
Normalizes currency literal input to a canonical representation. Unwraps single-element vectors, keywordizes `:id` in maps, and normalizes symbols to keywords when possible. Delegates to `currency/parse-currency-code`.
(nr currency)(nr currency registry)Returns currency numeric ID (ISO 4217 numeric code) as a long number or nil.
Returns currency numeric ID (ISO 4217 numeric code) as a long number or `nil`.
(ns c)(ns c registry)(ns c locale registry)Alias for domain.
Alias for domain.
(ns-code c)(ns-code c registry)(ns-code c _locale registry)Returns a currency code as a string for the given currency object. If the currency identifier is namespaced the namespace will be used as a prefix and slash character as a separator. Locale argument is ignored.
Returns a currency code as a string for the given currency object. If the currency identifier is namespaced the namespace will be used as a prefix and slash character as a separator. Locale argument is ignored.
(null? c)(null? c registry)Returns true if the given currency is a kind of null currency.
Returns `true` if the given currency is a kind of null currency.
(numeric c)(numeric c registry)(numeric c locale registry)Alias for nr.
Alias for nr.
(numeric-id c)(numeric-id c registry)(numeric-id c locale registry)Alias for nr.
Alias for nr.
(numeric-ids)(numeric-ids registry)Returns a sequence of long values for all currencies in a registry having numeric
identifiers or nil if there are no currencies with numeric identifiers. When
registry is not given or nil, the default is used.
Returns a sequence of long values for all currencies in a registry having numeric identifiers or `nil` if there are no currencies with numeric identifiers. When registry is not given or `nil`, the default is used.
(numerics)(numerics registry)Returns a lazy sequence of Currency objects for all numeric identifiers of
currencies in a registry or nil if there are no currencies with numeric
identifiers. When registry is not given or nil, the default is used.
Returns a lazy sequence of `Currency` objects for all numeric identifiers of currencies in a registry or `nil` if there are no currencies with numeric identifiers. When registry is not given or `nil`, the default is used.
(of currency)(of currency registry)Returns a currency for the given value by querying the given registry or a global
registry, which may be shadowed by the value of
io.randomseed.bankster.registry/*default* (see ``io.randomseed.bankster.registry/with`` orwith-registry`).
Returns a currency for the given value by querying the given registry or a global registry, which may be shadowed by the value of `io.randomseed.bankster.registry/*default* (see ``io.randomseed.bankster.registry/with`` or `with-registry`).
(of-country country-id)(of-country country-id registry)(of-country country-id _locale registry)Returns a currency for the given country identified by a country ID (which should be a keyword). If there is no currency or country of the given ID does not exist, returns nil. Locale argument is ignored.
Returns a currency for the given country identified by a country ID (which should be a keyword). If there is no currency or country of the given ID does not exist, returns nil. Locale argument is ignored.
(of-domain domain)(of-domain domain registry)Returns a set of currencies assigned to the given domain or nil if none exist.
Delegates to io.randomseed.bankster.currency/of-domain.
Returns a set of currencies assigned to the given domain or `nil` if none exist. Delegates to `io.randomseed.bankster.currency/of-domain`.
(of-domain? domain c)(of-domain? domain c registry)Checks if a domain of the given currency c equals to the one given as a first
argument domain or if it belongs to a domain (checked with clojure.core/isa?).
Checks if a domain of the given currency `c` equals to the one given as a first argument `domain` or if it belongs to a `domain` (checked with `clojure.core/isa?`).
(of-id id)(of-id id registry)Returns a currency object for the given ID and registry.
If the registry is not given, it will use the default registry (will first try a
registry bound to the io.randomseed.bankster.registry/*default* dynamic
variable, then the global registry).
The currency is always taken from a registry (on a basis of the extracted ID) even
if a Currency or currency-like object was given, with one exception: if
registry is explicitly set to nil then a Currency object will be returned as
is (or created out of currency-like object and returned) without consulting any
registry.
Returns a currency object for the given ID and registry. If the registry is not given, it will use the default registry (will first try a registry bound to the `io.randomseed.bankster.registry/*default*` dynamic variable, then the global registry). The currency is always taken from a registry (on a basis of the extracted ID) even if a `Currency` or currency-like object was given, with one exception: if `registry` is explicitly set to `nil` then a `Currency` object will be returned as is (or created out of currency-like object and returned) without consulting any registry.
(of-kind kind)(of-kind kind registry)Returns a set of currencies of the given kind or nil if none exist.
Uses io.randomseed.bankster.currency/of-kind? to filter currency/all.
Returns a set of currencies of the given kind or `nil` if none exist. Uses `io.randomseed.bankster.currency/of-kind?` to filter `currency/all`.
(of-kind? kind c)(of-kind? kind c registry)Checks if a kind of the given currency c equals to the one given as a second
argument kind or if it belongs to a kind (checked with clojure.core/isa?).
Checks if a kind of the given currency `c` equals to the one given as a second argument `kind` or if it belongs to a `kind` (checked with `clojure.core/isa?`).
(of-trait? tag c)(of-trait? tag c registry)Checks whether currency c has the given trait tag (directly or via
clojure.core/isa?).
Checks whether currency `c` has the given trait `tag` (directly or via `clojure.core/isa?`).
(official? c)(official? c registry)Alias for iso-strict?
Alias for iso-strict?
(peg? c)(peg? c registry)Returns true if the given currency is a kind of PEG currency.
Returns `true` if the given currency is a kind of PEG currency.
(possible? currency)(possible? currency registry)Returns true if the given value is a possible currency representation.
Returns `true` if the given value is a possible currency representation.
(present? currency)(present? currency registry)Returns true if a currency can be resolved and is present in a registry.
Returns `true` if a currency can be resolved and is present in a registry.
(real? c)(real? c registry)Returns true if the given currency is a kind of real currency (has its :kind set
to :currency or its descendants.
Returns `true` if the given currency is a kind of real currency (has its `:kind` set to `:currency` or its descendants.
(referenced? c)(referenced? c registry)Returns true if the given currency is a kind of referenced currency.
Returns `true` if the given currency is a kind of referenced currency.
(register registry currency)(register registry currency country-ids)(register registry currency update-mode?)(register registry currency country-ids update-mode?)(register registry currency country-ids localized-properties)(register registry currency country-ids localized-properties update-mode?)Adds a currency and optional, associated country mappings and/or localized properties to the given registry. Returns updated registry.
The optional country-ids argument should be a sequence of keywords (however, if a single keyword is given it will be converted to a single-element sequence) with country codes which should be associated with the given currency.
The optional localized-properties argument should be a map of localized properties of the given currency. See the Data Structures documentation section for more information.
If the update mode is enabled then all of the existing countries associated with the currency are removed and replaced with the provided ones. To simply add new countries, use add-countries. Also note that update mode removes localized properties so new one must be provided.
Adds a currency and optional, associated country mappings and/or localized properties to the given registry. Returns updated registry. The optional country-ids argument should be a sequence of keywords (however, if a single keyword is given it will be converted to a single-element sequence) with country codes which should be associated with the given currency. The optional localized-properties argument should be a map of localized properties of the given currency. See the Data Structures documentation section for more information. If the update mode is enabled then all of the existing countries associated with the currency are removed and replaced with the provided ones. To simply add new countries, use add-countries. Also note that update mode removes localized properties so new one must be provided.
(register! currency)(register! currency country-id-or-update?)(register! currency country-id localized-properties update?)Adds currency and (optional) country to the global registry. Returns updated registry. When the currency is nil, returns current state of the global, shared registry (but not a dynamic registry, even if it is set).
Adds currency and (optional) country to the global registry. Returns updated registry. When the currency is nil, returns current state of the global, shared registry (but not a dynamic registry, even if it is set).
(registry-or-default registry)Resolves true or nil into the current default registry, otherwise returns the
given value.
Resolves `true` or `nil` into the current default registry, otherwise returns the given value.
(remove-countries registry country-ids)Removes countries from the given registry. Also unlinks constrained currencies in proper locations. Returns updated registry.
Removes countries from the given registry. Also unlinks constrained currencies in proper locations. Returns updated registry.
(remove-countries! country-ids)Removes country (a keyword) or countries (seqable collection of keywords) from the global registry. Automatically removes currency constraints when necessary. Returns updated registry.
If the country-ids is nil, returns current state of a global registry (but not a dynamic registry, even if it is set).
Removes country (a keyword) or countries (seqable collection of keywords) from the global registry. Automatically removes currency constraints when necessary. Returns updated registry. If the country-ids is nil, returns current state of a global registry (but not a dynamic registry, even if it is set).
(remove-localized-properties registry currency-id)Removes localized properties assigned to a currency in a registry. Returns updated registry. Expects currency ID (or equivalent) to be passed as the second argument.
Removes localized properties assigned to a currency in a registry. Returns updated registry. Expects currency ID (or equivalent) to be passed as the second argument.
(remove-localized-props! currency)Removes localized properties of the given currency from the global registry.
If the currency is nil, returns current state of a global registry (but not a dynamic registry, even if it is set).
Removes localized properties of the given currency from the global registry. If the currency is nil, returns current state of a global registry (but not a dynamic registry, even if it is set).
(remove-traits registry currency-id traits)Removes traits for the given currency in the registry.
Passing nil or an empty collection is a no-op. Removes the registry entry if it
becomes empty.
Throws when the currency cannot be resolved in the registry.
Removes traits for the given currency in the registry. Passing `nil` or an empty collection is a no-op. Removes the registry entry if it becomes empty. Throws when the currency cannot be resolved in the registry.
(remove-traits! currency-id traits)Removes traits for the given currency in the global registry. See remove-traits.
Removes traits for the given currency in the global registry. See `remove-traits`.
(resolve)(resolve currency)(resolve currency registry)Strict currency coercion (throwing).
Delegates to io.randomseed.bankster.currency/unit.
Arity:
() uses io.randomseed.bankster.currency/*default*.([currency]) resolves the given currency representation.([currency registry]) resolves using the given registry (nil -> default).Accepts currency identifiers (keyword/symbol/string/number), Currency values, and
currency maps (treated as registry lookup specs).
When a registry is consulted and no match is found, it throws. Returns nil for
nil input.
When the input is already a Currency and registry is nil, or omitted, it is
returned as-is.
When the input is a Currency but registry is explicitly given and not nil, the
given currency will be used to perform a registry lookup (and its properties will
be used as a mask).
Setting registry to true will cause a default registry to be used and lookup
enforced.
Strict currency coercion (throwing). Delegates to `io.randomseed.bankster.currency/unit`. Arity: - `()` uses `io.randomseed.bankster.currency/*default*`. - `([currency])` resolves the given currency representation. - `([currency registry])` resolves using the given registry (`nil` -> default). Accepts currency identifiers (keyword/symbol/string/number), `Currency` values, and currency maps (treated as registry lookup specs). When a registry is consulted and no match is found, it throws. Returns `nil` for `nil` input. When the input is already a `Currency` and `registry` is `nil`, or omitted, it is returned as-is. When the input is a `Currency` but registry is explicitly given and not `nil`, the given currency will be used to perform a registry lookup (and its properties will be used as a mask). Setting registry to `true` will cause a default registry to be used and lookup enforced.
(resolve-all currency)(resolve-all currency registry)Returns all currencies matching the given hint in a registry.
Delegates to io.randomseed.bankster.currency/resolve-all (soft; returns nil on
no match).
registry may be true to force the default registry.
Returns all currencies matching the given hint in a registry. Delegates to `io.randomseed.bankster.currency/resolve-all` (soft; returns `nil` on no match). `registry` may be `true` to force the default registry.
(resolve-try)(resolve-try currency)(resolve-try currency registry)Non-throwing currency resolution (soft).
Delegates to io.randomseed.bankster.currency/unit-try and returns a registered
Currency or nil when it cannot be resolved.
Arity:
() uses currency/*default*.([currency]) resolves the given representation using the default registry.([currency registry]) resolves using the given registry (nil -> default).Accepts currency identifiers (keyword/symbol/string/number), Currency values, and
currency maps (treated as registry lookup specs).
When a registry is consulted and no match is found, it returns nil.
When the input is already a Currency and registry is nil or omitted, it is
returned as-is.
When the input is a Currency but registry is explicitly given and not nil, the
given currency will be used to perform a registry lookup (and its properties will
be used as a mask).
Setting registry to true will cause a default registry to be used and lookup
enforced.
Non-throwing currency resolution (soft). Delegates to `io.randomseed.bankster.currency/unit-try` and returns a registered `Currency` or `nil` when it cannot be resolved. Arity: - `()` uses `currency/*default*`. - `([currency])` resolves the given representation using the default registry. - `([currency registry])` resolves using the given registry (`nil` -> default). Accepts currency identifiers (keyword/symbol/string/number), `Currency` values, and currency maps (treated as registry lookup specs). When a registry is consulted and no match is found, it returns `nil`. When the input is already a `Currency` and `registry` is `nil` or omitted, it is returned as-is. When the input is a `Currency` but registry is explicitly given and not `nil`, the given currency will be used to perform a registry lookup (and its properties will be used as a mask). Setting registry to `true` will cause a default registry to be used and lookup enforced.
(same-ids? a b)(same-ids? a b registry)Returns true when two currency representations refer to the same currency ID.
Contract:
false when IDs cannot be established),registry set to nil means: use the default registry,Currency values are never treated as registry references.Returns `true` when two currency representations refer to the same currency ID. Contract: - symmetric (argument order does not matter), - non-throwing (returns `false` when IDs cannot be established), - `registry` set to `nil` means: use the default registry, - `Currency` values are never treated as registry references.
(sc c)(sc c registry)(sc c _locale registry)Returns currency scale (decimal places) as a number. For currencies without the
assigned decimal places it will return auto-scaled (i.e. -1). Locale argument
is ignored.
Returns currency scale (decimal places) as a number. For currencies without the assigned decimal places it will return `auto-scaled` (i.e. `-1`). Locale argument is ignored.
(scale c)(scale c registry)(scale c locale registry)Alias for sc.
Alias for sc.
(set-default! c)Sets default currency by altering io.randomseed.bankster.currency/*default*
dynamic variable.
Sets default currency by altering `io.randomseed.bankster.currency/*default*` dynamic variable.
(set-default-registry!)(set-default-registry! resource-path)(set-default-registry! resource-path & more)Sets default, global registry using a global configuration file and optional user's configuration file. The highlighted version of a registry will be sourced from the last configuration used.
Sets default, global registry using a global configuration file and optional user's configuration file. The highlighted version of a registry will be sourced from the last configuration used.
(set-traits registry currency-id traits)Sets traits for the given currency in the registry.
Traits are stored as a registry attribute under Registry/:cur-id->traits
(currency ID -> set of keywords). Passing nil or an empty collection removes the
traits entry.
Throws when the currency cannot be resolved in the registry.
Sets traits for the given currency in the registry. Traits are stored as a registry attribute under `Registry/:cur-id->traits` (currency ID -> set of keywords). Passing `nil` or an empty collection removes the traits entry. Throws when the currency cannot be resolved in the registry.
(set-traits! currency-id traits)Sets traits for the given currency in the global registry. See set-traits.
Sets traits for the given currency in the global registry. See `set-traits`.
(set-weight registry currency-id weight)Sets currency weight in the given registry and updates all weight-dependent indexes.
Weight is stored as a registry attribute under Registry/:cur-id->weight (currency
ID -> int weight). Setting weight to 0 keeps an explicit 0 entry (presence in the
map is meaningful). Use clear-weight to remove the explicit entry (default 0).
Throws when the currency cannot be resolved in the registry.
Sets currency weight in the given registry and updates all weight-dependent indexes. Weight is stored as a registry attribute under `Registry/:cur-id->weight` (currency ID -> int weight). Setting weight to 0 keeps an explicit 0 entry (presence in the map is meaningful). Use `clear-weight` to remove the explicit entry (default 0). Throws when the currency cannot be resolved in the registry.
(set-weight! currency-id weight)Sets currency weight in the global registry. See set-weight.
Sets currency weight in the global registry. See `set-weight`.
(special? c)(special? c registry)Returns true if the given currency is a kind of special currency.
Returns `true` if the given currency is a kind of special currency.
(stable? currency)(stable? currency registry)Returns true if the given currency is a kind of stable currency.
Delegates to io.randomseed.bankster.currency/stable?.
Returns `true` if the given currency is a kind of stable currency. Delegates to `io.randomseed.bankster.currency/stable?`.
(staked? c)(staked? c registry)Returns true if the given currency is a kind of staked currency.
Returns `true` if the given currency is a kind of staked currency.
(standard? c)(standard? c registry)Alias for iso-strict?
Alias for iso-strict?
(symbol currency)(symbol currency locale)(symbol currency locale registry)Returns a currency symbol for the given currency and locale.
Delegates to io.randomseed.bankster.currency/symbol.
Returns a currency symbol for the given currency and locale. Delegates to `io.randomseed.bankster.currency/symbol`.
(symbol-native currency)(symbol-native currency registry)Like symbol but for ISO-standardized currencies uses locale assigned to the first country where a currency is the default. When locale is given it is ignored.
Like symbol but for ISO-standardized currencies uses locale assigned to the first country where a currency is the default. When locale is given it is ignored.
(test? c)(test? c registry)Returns true if the given currency is a kind of test currency.
Returns `true` if the given currency is a kind of test currency.
(to-code this)Coerces a currency representation to a currency code (unqualified keyword).
Registry-free. May return nil if the code cannot be derived.
Coerces a currency representation to a currency code (unqualified keyword). Registry-free. May return `nil` if the code cannot be derived.
(to-code-str this)Coerces a currency representation to a currency code string.
Registry-free. Must not intern keywords. Typically the upper-cased name part
without a namespace (e.g. "USDT").
Coerces a currency representation to a currency code string. Registry-free. Must not intern keywords. Typically the upper-cased name part without a namespace (e.g. `"USDT"`).
(to-currency this)Coerces a currency representation to a Currency object without consulting a
registry.
Returns a Currency instance or nil when it cannot be constructed.
Coerces a currency representation to a `Currency` object without consulting a registry. Returns a `Currency` instance or `nil` when it cannot be constructed.
(to-edn-map currency)(to-edn-map currency opts)Serializes a currency to an EDN-friendly map.
Options:
:code-only? - when truthy, namespace is omitted: :crypto/ETH → :ETHSerializes a currency to an EDN-friendly map. Options: - `:code-only?` - when truthy, namespace is omitted: `:crypto/ETH` → `:ETH`
(to-edn-string currency)(to-edn-string currency opts)Serializes a currency to an EDN tagged literal string.
Options:
:code-only? - when truthy, namespace is omitted: :crypto/ETH → :ETHSerializes a currency to an EDN tagged literal string. Options: - `:code-only?` - when truthy, namespace is omitted: `:crypto/ETH` → `:ETH`
(to-id this)Coerces a currency representation to a currency identifier (keyword).
Registry-free. May return nil if the identifier cannot be derived.
Coerces a currency representation to a currency identifier (keyword). Registry-free. May return `nil` if the identifier cannot be derived.
(to-id-str this)Coerces a currency representation to a currency identifier string.
Registry-free. Must not intern keywords. Intended for security-sensitive code paths where the input may be untrusted.
Suggested canonical form:
"PLN"),/ + upper-case name
(e.g. "crypto/USDT" or "CrYpTo/USDT").Coerces a currency representation to a currency identifier string. Registry-free. Must not intern keywords. Intended for security-sensitive code paths where the input may be untrusted. Suggested canonical form: - unqualified IDs: upper-case name (e.g. `"PLN"`), - qualified IDs: original namespace + `/` + upper-case name (e.g. `"crypto/USDT"` or `"CrYpTo/USDT"`).
(to-json-map currency)(to-json-map currency opts)Serializes a currency to a JSON-friendly map.
Options:
:code-only? - when truthy, namespace is omitted: :crypto/ETH → "ETH"Serializes a currency to a JSON-friendly map. Options: - `:code-only?` - when truthy, namespace is omitted: `:crypto/ETH` → `"ETH"`
(to-json-string currency)(to-json-string currency opts)Serializes a currency to a JSON string identifier.
Options:
:code-only? - when truthy, namespace is omitted: :crypto/ETH → "ETH"Serializes a currency to a JSON string identifier. Options: - `:code-only?` - when truthy, namespace is omitted: `:crypto/ETH` → `"ETH"`
(to-map this)Coerces a currency representation to a map of currency fields.
Registry-free. Returns a map (possibly partial) or nil.
Coerces a currency representation to a map of currency fields. Registry-free. Returns a map (possibly partial) or `nil`.
(to-numeric-id this)Coerces a currency representation to its numeric identifier (ISO 4217 numeric code, when available).
Registry-free. Implementations should return a number when it can be derived,
otherwise they may return nil or a sentinel numeric value.
Coerces a currency representation to its numeric identifier (ISO 4217 numeric code, when available). Registry-free. Implementations should return a number when it can be derived, otherwise they may return `nil` or a sentinel numeric value.
(traits c)(traits c registry)(traits c _locale registry)Returns currency traits as a set of keywords. The function may return nil if the
currency has no traits. Locale argument is ignored. To list all known kinds use
kinds.
Returns currency traits as a set of keywords. The function may return `nil` if the currency has no traits. Locale argument is ignored. To list all known kinds use `kinds`.
(traits-expanded c)(traits-expanded c registry)(traits-expanded c _locale registry)Returns currency traits as a set of keywords and expands them with all ancestors
from the registry :traits hierarchy. The function may return nil if the currency
has no traits. Locale argument is ignored.
Returns currency traits as a set of keywords and expands them with all ancestors from the registry :traits hierarchy. The function may return `nil` if the currency has no traits. Locale argument is ignored.
(unit id)(unit id registry)Returns a Currency object for the given ID, currency code, numeric ID, or
a currency-like object.
If a Currency record is passed and registry:
nil,then the registry will NOT be consulted and the Currency object will be returned
as-is.
If a non-nil registry is passed, it will be consulted to find the exact match.
For currency identifiers (keywords, strings, numbers) it will resolve them from
the registry.
For currency maps, unit treats the map as a registry lookup specification: it
will query the registry using meaningful keys present in the map (a mask-like
match). If more than one currency matches, the best match is selected by weight
(smallest weight wins). If no currency matches, an exception will be thrown. Use
resolve-all to obtain all matches.
For Currency objects all fields must be exact except :domain and :kind which
may be nil to act as wildcards. Only if the currency exists in the registry, the
Currency record will be returned.
If the registry is consulted and the currency does not exist in a registry, an exception will be thrown.
Returns a `Currency` object for the given ID, currency code, numeric ID, or a currency-like object. If a `Currency` record is passed and `registry`: - is not given (unary arity), or - is explicitly set to `nil`, then the registry will NOT be consulted and the `Currency` object will be returned as-is. If a non-`nil` `registry` is passed, it will be consulted to find the exact match. For currency identifiers (keywords, strings, numbers) it will resolve them from the registry. For currency maps, `unit` treats the map as a *registry lookup specification*: it will query the registry using meaningful keys present in the map (a mask-like match). If more than one currency matches, the best match is selected by weight (smallest weight wins). If no currency matches, an exception will be thrown. Use `resolve-all` to obtain all matches. For `Currency` objects all fields must be exact except `:domain` and `:kind` which may be `nil` to act as wildcards. Only if the currency exists in the registry, the `Currency` record will be returned. If the registry is consulted and the currency does not exist in a registry, an exception will be thrown.
(unit-try id)(unit-try id registry)Soft variant of unit.
Returns a Currency or nil instead of throwing when the currency cannot be
resolved. When the input is already a Currency and registry is nil, it is
returned as-is (matching unit semantics). When registry is non-nil, the
registry is consulted and Currency inputs are matched strictly by fields (same
as unit), but failures return nil.
Delegates to resolve for non-Currency inputs.
Soft variant of `unit`. Returns a `Currency` or `nil` instead of throwing when the currency cannot be resolved. When the input is already a `Currency` and `registry` is `nil`, it is returned as-is (matching `unit` semantics). When `registry` is non-`nil`, the registry is consulted and `Currency` inputs are matched strictly by fields (same as `unit`), but failures return `nil`. Delegates to `resolve` for non-`Currency` inputs.
(unregister registry currency)Removes a currency from the given registry. Also removes country mappings and all localized properties associated with a currency. Returns updated registry.
Numeric-ID indexes:
:cur-nr->curs (shared numeric IDs bucket):cur-nr->cur to the canonical currency (first in bucket), or removes the
numeric entry if bucket becomes empty.Removes a currency from the given registry. Also removes country mappings and all localized properties associated with a currency. Returns updated registry. Numeric-ID indexes: - removes the currency from `:cur-nr->curs` (shared numeric IDs bucket) - updates `:cur-nr->cur` to the canonical currency (first in bucket), or removes the numeric entry if bucket becomes empty.
(unregister! currency)Removes currency from the global registry. Automatically removes country constraints when necessary and localized properties associated with a currency. Returns updated registry.
If the currency is nil, returns current state of a global registry (but not a dynamic registry, even if it is set).
Removes currency from the global registry. Automatically removes country constraints when necessary and localized properties associated with a currency. Returns updated registry. If the currency is nil, returns current state of a global registry (but not a dynamic registry, even if it is set).
(unset-default!)Sets default currency to nil by altering io.randomseed.bankster.currency/*default*
dynamic variable.
Sets default currency to nil by altering `io.randomseed.bankster.currency/*default*` dynamic variable.
(update registry currency)(update registry currency country-ids)(update registry currency country-ids localized-properties-map)Replaces a currency in the given registry by a new one, preserving localized properties, relation to countries and code if not explicitly given. Returns updated registry. If the currency does not exist in a registry yet, it will be registered.
Replaces a currency in the given registry by a new one, preserving localized properties, relation to countries and code if not explicitly given. Returns updated registry. If the currency does not exist in a registry yet, it will be registered.
(update! currency)(update! currency country-ids)(update! currency country-ids localized-properties-map)Replaces a currency in the global, shared registry by a new one, preserving localized properties, relation to countries and code if not explicitly given. Returns updated registry. If the currency does not exist in a registry yet, it will be registered.
Replaces a currency in the global, shared registry by a new one, preserving localized properties, relation to countries and code if not explicitly given. Returns updated registry. If the currency does not exist in a registry yet, it will be registered.
(val-auto-scaled*? scale)Returns true if the given scale is equal to auto-scaled.
Note: This delegates to scale/auto-scaled*?.
Returns `true` if the given scale is equal to auto-scaled. Note: This delegates to `scale/auto-scaled*?`.
Returns true if the given scale is equal to auto-scaled.
Note: This is an alias for scale/auto-scaled?.
Returns `true` if the given scale is equal to auto-scaled. Note: This is an alias for `scale/auto-scaled?`.
(virtual? c)(virtual? c registry)Returns true if the given currency is a kind of virtual currency.
Returns `true` if the given currency is a kind of virtual currency.
(weight c)(weight c registry)(weight c _locale registry)Returns weight of the given currency (used to resolve conflicts when getting currencies having conflicting currency codes).
Returns weight of the given currency (used to resolve conflicts when getting currencies having conflicting currency codes).
(with currency & body)Sets a default currency in a lexical context of the body.
Sets a default currency in a lexical context of the body.
(with-attempt c registry binding & body)Evaluates c and tries to coerce it to a Currency.
If coercion succeeds, binds the resulting currency to the given symbol and
evaluates body, returning its result. If coercion fails, returns false.
Uses attempt* for coercion (non-throwing).
The binding name can be given either as a symbol or as a single-element vector
(mirroring if-some style):
(with-attempt x registry c (.id c)) (with-attempt x registry [c] (.id c))
Evaluates `c` and tries to coerce it to a `Currency`. If coercion succeeds, binds the resulting currency to the given symbol and evaluates `body`, returning its result. If coercion fails, returns `false`. Uses `attempt*` for coercion (non-throwing). The binding name can be given either as a symbol or as a single-element vector (mirroring `if-some` style): (with-attempt x registry c (.id c)) (with-attempt x registry [c] (.id c))
(with-default currency & body)Sets the dynamic binding of io.randomseed.bankster.currency/*default* to
currency and evaluates body in an implicit do.
Sets the dynamic binding of `io.randomseed.bankster.currency/*default*` to `currency` and evaluates body in an implicit `do`.
(with-registry registry & body)Sets a registry in a lexical context of the body to be used instead of a global one in functions which require the registry and it was not passed as an argument.
Sets a registry in a lexical context of the body to be used instead of a global one in functions which require the registry and it was not passed as an argument.
(with-weight c weight)Returns a currency with weight set.
Weight is stored in currency metadata and does not participate in = / hash
semantics of Currency.
NOTE: Unlike currency constructors (which treat weight as an optional hint),
with-weight is an explicit setter: it records the weight even when it is 0.
Returns a currency with `weight` set. Weight is stored in currency metadata and does not participate in `=` / `hash` semantics of `Currency`. NOTE: Unlike currency constructors (which treat weight as an optional hint), `with-weight` is an explicit setter: it records the weight even when it is 0.
(wrapped? c)(wrapped? c registry)Returns true if the given currency is a kind of wrapped currency.
Returns `true` if the given currency is a kind of wrapped currency.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |