io.randomseed.bankster.currency — io.randomseed/bankster 1.2.13

*default* clj

Default currency unit to be applied when creating Money objects without the currency specified.

add-countries clj

(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.

add-countries! clj

(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).

add-localized-properties clj

(add-localized-properties registry currency-id properties)

Adds localized properties of a currency to the given registry. Overwrites existing properties.

add-localized-props! clj

(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).

add-weighted-code clj

(add-weighted-code registry currency-id)

Associates the existing currency code with the currency object in the given registry using the value of the .weight field. 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.

auto-scaled clj

Expresses the scale of a currency which is automatic and not limited to certain decimal places.

auto-scaled? clj

(auto-scaled? c)

(auto-scaled? c registry)

Alias for big?.

big? clj

(big? c)

(big? c registry)

Returns true if the given currency has an automatic scale (decimal places).

code clj

(code c)

(code c registry)

(code c locale registry)

Returns a currency code as a string for the given currency object. If the currency identifier is namespaced only the base code (without a namespace) will be returned. Locale argument is ignored.

code-literal clj

(code-literal arg)

Tagged literal handler for Clojure code. Emits compound forms that are going to be evaluated.

combank? clj

(combank? c)

(combank? c registry)

Returns true if the given currency is a kind of :COMBANK.

commodity? clj

(commodity? c)

(commodity? c registry)

Returns true if the given currency is a kind of :COMMODITY.

config->registry clj

(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.

countries clj

(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.

crypto? clj

(crypto? c)

(crypto? c registry)

Returns true if the given currency is a cryptocurrency. It is just a helper that check if the domain of a currency equals to :CRYPTO.

currency? clj

(currency? c)

(currency? c registry)

Returns true if the given value is represented by a valid currency object. Registry argument is ignored.

data-literal clj

(data-literal arg)

Tagged literal handler for EDN data files. Emits Currency objects or nil values.

decentralised? clj

(decentralised? c)

(decentralised? c registry)

Alias for decentralized?

decentralized? clj

(decentralized? c)

(decentralized? c registry)

Returns true if the given currency is a kind of :DECENTRALIZED.

display-name clj

(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.

display-name-native clj

(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.

domain clj

(domain c)

(domain c registry)

(domain c locale registry)

Returns currency domain as a keyword. For currencies with simple identifiers it will be :ISO-4217. For currencies with namespace-qualified identifiers it will be the upper-cased namespace name (e.g. :CRYPTO) set during creation a currency object. Locale argument is ignored.

experimental? clj

(experimental? c)

(experimental? c registry)

Returns true if the given currency is a kind of :EXPERIMENTAL.

fiat? clj

(fiat? c)

(fiat? c registry)

Returns true if the given currency is a kind of :FIAT.

fiduciary? clj

(fiduciary? c)

(fiduciary? c registry)

Returns true if the given currency is a kind of :FIDUCIARY.

formatter clj

(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.

formatter-extended clj

(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.

has-country? clj

(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.

has-kind? clj

(has-kind? c)

(has-kind? c registry)

Returns true if the given currency has its kind defined.

has-numeric-id? clj

(has-numeric-id? c)

(has-numeric-id? c registry)

Returns true if the given currency has a numeric ID.

in-domain? clj

(in-domain? ns c)

(in-domain? ns c registry)

Returns true if the given currency has a domain set to the first given argument.

iso? clj

(iso? c)

(iso? c registry)

Returns true if the given currency is an official currency and its identifier is compliant with ISO standard. It is just a helper which checks if the :domain field of a currency equals :ISO-4217.

java clj

(java currency)

(java currency registry)

For ISO-standardized currency, returns corresponding java.util.Currency object.

kind clj

(kind c)

(kind c registry)

(kind c locale registry)

Returns currency kind. It is a keyword which describes origin of its value. Currently known kinds are:

• :FIAT – legal tender issued by government or other authority
• :FIDUCIARY - accepted medium of exchange issued by a fiduciary or fiduciaries
• :DECENTRALIZED - accepted medium of exchange issued by a distributed ledger
• :COMBANK - commercial bank money
• :COMMODITY - accepted medium of exchange based on commodities
• :EXPERIMENTAL - pseudo-currency used for testing purposes.

The function may return nil if the currency is a no-currency. Locale argument is ignored.

kind-of? clj

(kind-of? c kind)

(kind-of? c kind registry)

Returns a kind of the given currency equals to the one given as a second argument.

localized-properties clj

(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.

localized-property clj

(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).

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

• 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 clj

(map->new m)

Creates new currency record from a map.

Monetary clj protocol

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.).

defined? clj

(defined? id)

(defined? id registry)

Returns true if the given currency (identified by its ID) exists in a registry. If the registry is not given, the global one will be used, trying a dynamic registry bound to the registry/default first.

id clj

(id id)

(id id registry)

Returns a unique identifier of the given currency as a keyword. The currency can be expressed as a Currency object, a keyword, a string or any other type which is recognized by the unit protocol method.

The role of the default registry is advisory. If the registry argument is not given (or it is nil) and the dynamic variable io.randomseed.bankster.registry/*default* does not refer to a truthy value then the ID will be returned regardless of whether the currency exists in a registry, by simply converting it to a keyword or getting a field from a Currency object. Still, the default registry will be consulted to resolve possible currency code. For instance: if BTC is a currency code of a registered currency identified as :crypto/BTC then the resulting value for :BTC will be :crypto/BTC; but for :BLABLA (which does not exist in a registry) the resulting value will be :BLABLA.

If a registry is given (or a dynamic registry is set) then trying to use a non-existing currency will cause an exception to be thrown.

of-id clj

(of-id id)

(of-id id registry)

Returns a currency object for the given ID and a registry. If the registry is not given, it will use the global one, but will first try a registry bound to the io.randomseed.bankster.registry/*default* dynamic variable (if it's set).

The currency is always taken from a registry (on a basis of its ID) even if a Currency object was given, with one exception: if a currency is passed and the second argument is explicitly set to nil then the object will be returned as is, without consulting the registry.

present? clj

(present? id)

(present? id registry)

Returns true if a currency of the given currency code or ID exists in a registry. If the registry is not given, the global one will be used, trying a dynamic registry bound to the registry/default first.

same-ids? clj

(same-ids? a b)

(same-ids? a b registry)

Returns true if two currencies have the same ID. If the registry is not given, it will use the global one, but will first try a dynamic registry bound to the io.randomseed.bankster.registry/*default* dynamic variable.

unit clj

(unit id)

(unit id registry)

Returns a currency object for the given ID or currency code. If the registry is not given, it will try a registry bound to the io.randomseed.bankster.registry/*default* dynamic variable and if it is not set (or is falsy value) it will use the global registry.

If a Currency object is passed, it will be returned as is without consulting the registry, unless the registry is given (and not nil) or the dynamic registry is set. In this case the currency will be obtained from a registry on a basis of its ID extracted from the given object.

If the registry is given (or dynamic registry is set) and the currency does not exist in a registry an exception will be thrown, regardless of whether a Currency object was passed or not.

Explicitly passing nil as a second argument when a Currency object is given can speed things up a bit in certain scenarios by bypassing dynamic variable check.

name clj

(name currency)

(name currency locale)

(name currency locale registry)

Alias for display-name.

name-native clj

(name-native currency)

(name-native currency registry)

Alias for display-name-native.

new clj

(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)

Alias for new-currency.

new-currency clj

(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.

no-numeric-id clj

Expresses the value of currency's numeric ID which does not exist.

nr clj

(nr c)

(nr c registry)

(nr c locale registry)

Returns currency numeric ID as a long number. For currencies without the assigned number it will return nil. Locale argument is ignored.

ns clj

(ns c)

(ns c registry)

(ns c locale registry)

Alias for domain.

ns-code clj

(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.

numeric clj

(numeric c)

(numeric c registry)

(numeric c locale registry)

Alias for nr.

numeric-id clj

(numeric-id c)

(numeric-id c registry)

(numeric-id c locale registry)

Alias for nr.

of clj macro

(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 registry/default (see registry/with or with-registry).

of-country clj

(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.

official? clj

(official? c)

(official? c registry)

Alias for iso?

possible? clj

(possible? c)

(possible? c registry)

Returns true if the given value is a possible currency representation. If the registry is not given, the global one is used. By possible representation we mean that it is a currency with a keyword identifier or any other data type which can be successfully converted into such using the registry provided.

register clj

(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 current 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 removed localized properties so new one must be provided.

register! clj

(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).

remove-countries clj

(remove-countries registry country-ids)

Removes countries from the given registry. Also unlinks constrained currencies in proper locations. Returns updated registry.

remove-countries! clj

(remove-countries! country-ids)

Removes country (a keyword) or countries (seqable collection of keywords) from the global registry. Automatically removes currency constrains 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 clj

(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 a second argument.

remove-localized-props! clj

(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).

sc clj

(sc c)

(sc c registry)

(sc c locale registry)

Returns currency scale (decimal places) as an integer number. For currencies without the assigned decimal places it will return nil (the value of auto-scaled). Locale argument is ignored.

scale clj

(scale c)

(scale c registry)

(scale c locale registry)

Alias for sc.

set-default! clj

(set-default! c)

Sets default currency by altering *default* dynamic variable.

set-default-registry! clj

(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.

standard? clj

(standard? c)

(standard? c registry)

Alias for iso?

symbol clj

(symbol currency)

(symbol currency locale)

(symbol currency locale registry)

Returns a currency symbol 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.

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.

symbol-native clj

(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.

unregister clj

(unregister registry currency)

Removes a currency from the given registry. Also removes country and numeric ID constrains when necessary and all localized properties associated with a currency. Returns updated registry.

Please note that removal of a currency which identifier and numeric identifier are the same as already registered currencies, will not only remove the existing currency identified by the ID but will also remove numeric ID from within all currency objects present in a registry.

unregister! clj

(unregister! currency)

Removes currency from the global registry. Automatically removes country constrains 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! clj

(unset-default!)

Sets default currency to nil by altering *default* dynamic variable.

update clj

(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.

update! clj

(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.

val-auto-scaled? clj

(val-auto-scaled? scale)

Returns true if the given scale is equal to auto-scaled.

weight clj

(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).

with clj macro

(with currency & body)

Sets a default currency in a lexical context of the body.

with-registry clj macro

(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. Has the same effect as registry/with.