io.randomseed.bankster.api

added in 2.2.0

Bankster library, front API.

amount

added in 2.2.0

(amount x)(amount x sc)(amount x sc rounding)

Returns the amount of a scalable as a BigDecimal.

Delegates to io.randomseed.bankster.scale/amount.

auto-scaled?

added in 2.2.0

(auto-scaled? x)

Returns true if a scalable’s derived scale is auto-scaled.

Delegates to io.randomseed.bankster.scale/auto?.

currency

added in 2.2.0

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

currency-try

added in 2.2.0

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

default-registry

added in 2.2.0

(default-registry)

Returns the default registry (honors registry/*default*).

info

added in 2.2.0

(info x)(info x registry)(info x locale registry)

Returns info map for currency or money.

  • For Money values, delegates to io.randomseed.bankster.money/info.
  • Otherwise delegates to io.randomseed.bankster.currency/info.

Registry arguments are ignored for Money. When registry is true, the default registry is used.

iso-currency?

added in 2.2.0

(iso-currency? currency)(iso-currency? currency registry)

Returns true when the given currency is a kind of ISO currency.

money

added in 2.2.0

(money)(money amount)(money amount currency)(money amount currency rounding)(money amount currency registry)(money amount currency rounding registry)

First-class Money constructor with amount-first argument order.

Delegates to io.randomseed.bankster.money/value and resolves currency via io.randomseed.bankster.currency/unit when a currency argument is provided.

Arity:

  • [] creates zero in the default currency.
  • [amount] delegates to unary money/value.
  • [amount currency] uses amount + currency.
  • [amount currency rounding] uses amount + currency + rounding.
  • [amount currency registry] uses amount + currency (resolved using registry).
  • [amount currency rounding registry] explicit rounding + registry for resolution.

currency may be a Currency, an identifier (keyword/symbol/string/number), or a currency map (lookup spec).

When a registry is consulted and the currency cannot be resolved, it throws.

When registry is true, the default registry (global or dynamically bound) is used.

rounding may be a java.math.RoundingMode or a keyword/symbol/string like “HALF_UP” (see scale/post-parse-rounding). If no default currency is configured and the amount does not encode one, money/value will throw.

money-try

added in 2.2.0

(money-try)(money-try amount)(money-try amount currency)(money-try amount currency rounding)(money-try amount currency registry)(money-try amount currency rounding registry)

Non-throwing variant of resolve for currency resolution.

Uses io.randomseed.bankster.currency/unit-try and returns nil when the currency cannot be resolved in the given (or default) registry. Accepts the same argument shapes as resolve. Rounding is parsed.

When registry is true, the default registry (global or dynamically bound) is used.

registry-or-default

added in 2.2.0

(registry-or-default registry)

Resolves true or nil into the current default registry, otherwise returns the given value.

rounding-mode

added in 2.2.0

(rounding-mode)(rounding-mode default)

Returns the current rounding mode.

Delegates to io.randomseed.bankster.scale/rounding-mode.

scale

added in 2.2.0

(scale x)

Returns scale for Money and Currency values.

  • For Money: returns the amount scale (may differ from currency nominal scale).
  • For Currency: returns the nominal scale (or -1 for auto-scaled).
  • For other values: calls io.randomseed.bankster.scale/of to return its scale.

scale-apply

added in 2.2.0

(scale-apply x)(scale-apply x sc)(scale-apply x sc rounding)

Applies scaling to a value.

Delegates to io.randomseed.bankster.scale/apply.

with-rescaling

macro

added in 2.2.0

(with-rescaling rounding-mode & body)

Alias for io.randomseed.bankster.scale/with-rescaling.

Enables re-scaling on some consecutive operations which support it and sets the rounding mode for operations on scaled values. Internally sets scale/*each* to true and scale/*rounding-mode* to the given value.

The first argument should be a valid rounding (from io.randomseed.bankster.scale or java.math.RoundingMode) or one of the following:

  • CEILING - rounds towards positive infinity.
  • DOWN - rounds towards zero.
  • FLOOR - rounds towards negative infinity.
  • HALF_DOWN - rounds towards nearest neighbor unless both neighbors are equidistant, in which case rounds down.
  • HALF_EVEN - rounds towards the nearest neighbor unless both neighbors are equidistant, and if so, rounds towards the even.
  • HALF_UP - rounds towards the nearest neighbor unless both neighbors are equidistant, and if so, rounds up.
  • UP - rounds away from zero
  • UNNECESSARY - asserts that the requested operation has an exact result, hence no rounding is necessary.

with-rounding

macro

added in 2.2.0

(with-rounding rounding-mode & body)

Alias for io.randomseed.bankster.scale/with-rounding.

Sets the rounding mode for operations on scaled values.

The first argument should be a valid rounding (from io.randomseed.bankster.scale or java.math.RoundingMode) or one of the following:

  • CEILING - rounds towards positive infinity.
  • DOWN - rounds towards zero.
  • FLOOR - rounds towards negative infinity.
  • HALF_DOWN - rounds towards nearest neighbor unless both neighbors are equidistant, in which case rounds down.
  • HALF_EVEN - rounds towards the nearest neighbor unless both neighbors are equidistant, and if so, rounds towards the even.
  • HALF_UP - rounds towards the nearest neighbor unless both neighbors are equidistant, and if so, rounds up.
  • UP - rounds away from zero
  • UNNECESSARY - asserts that the requested operation has an exact result, hence no rounding is necessary.