public interface MonetaryAmount extends CurrencySupplier, NumberSupplier
Each instance of an amount provides additional meta-data in form of a MonetaryContext
.
This context contains detailed information on the numeric capabilities, e.g. the supported
precision and maximal scale, as well as the common implementation flavor.
Also a MonetaryAmount
provides a NumberValue
, which allows easily to extract the
numeric value, of the amount. And finally getFactory()
provides a
MonetaryAmountFactory
, which allows to create instances of MonetaryAmount
based
on the same numeric implementation.
This JSR additionally recommends to consider the following aspects:
ArithmeticException
, if performing arithmetic
operations between amounts exceeds the capabilities of the numeric representation type used. Any
implicit truncating, that would lead to complete invalid and useless results, should be avoided.
This recommendation does not affect internal rounding, as required by the internal numeric
representation of a monetary amount.
MonetaryAmount
.NumberValue.numberValue(Class)
, whereas the exact counterpart,
NumberValue.numberValueExact(Class)
, works similar to
java.math.BigDecimal#longValueExact()
.
with(MonetaryOperator)
must be of the same type as
type on which with
was called. The with
method also defines additional
interoperability requirements that are important to enable this invariant.from(MonetaryAmount)
is
recommended to be implemented on each implementation class, that allows conversion of a
MonetaryAmount
to a concrete instance. E.g.a class MyMoney extends MonetaryAmount
would contain the following method:public final class MyMoney implements MonetaryAmount{ ... public static MyMoney from(MonetaryAmount amount)(...) }
MonetaryContext
and a serialized
CurrencyUnit
.equals/hashCode
, hereby considering
with(MonetaryOperator)
Modifier and Type | Method and Description |
---|---|
MonetaryAmount |
abs()
Returns a
MonetaryAmount whose value is the absolute value of this
MonetaryAmount , and whose scale is this.scale() . |
MonetaryAmount |
add(MonetaryAmount amount)
Returns a
MonetaryAmount whose value is (this +
amount) , and whose scale is max(this.scale(),
amount.scale()) . |
MonetaryAmount |
divide(double divisor)
Returns a
MonetaryAmount whose value is (this /
divisor) , and whose preferred scale is (this.scale() -
divisor.scale()) ; if the exact quotient cannot be represented an ArithmeticException
is thrown. |
MonetaryAmount |
divide(long divisor)
Returns a
MonetaryAmount whose value is (this /
divisor) , and whose preferred scale is (this.scale() -
divisor.scale()) ; if the exact quotient cannot be represented an ArithmeticException
is thrown. |
MonetaryAmount |
divide(java.lang.Number divisor)
Returns a
MonetaryAmount whose value is (this /
divisor) , and whose preferred scale is (this.scale() -
divisor.scale()) ; if the exact quotient cannot be represented an ArithmeticException
is thrown. |
MonetaryAmount[] |
divideAndRemainder(double divisor)
Returns a two-element
MonetaryAmount array containing the result of
divideToIntegralValue followed by the result of remainder on the two
operands. |
MonetaryAmount[] |
divideAndRemainder(long divisor)
Returns a two-element
MonetaryAmount array containing the result of
divideToIntegralValue followed by the result of remainder on the two
operands. |
MonetaryAmount[] |
divideAndRemainder(java.lang.Number divisor)
Returns a two-element
MonetaryAmount array containing the result of
divideToIntegralValue followed by the result of remainder on the two
operands. |
MonetaryAmount |
divideToIntegralValue(double divisor)
Returns a
MonetaryAmount whose value is the integer part of the quotient
(this / divisor) rounded down. |
MonetaryAmount |
divideToIntegralValue(long divisor)
Returns a
MonetaryAmount whose value is the integer part of the quotient
(this / divisor) rounded down. |
MonetaryAmount |
divideToIntegralValue(java.lang.Number divisor)
Returns a
MonetaryAmount whose value is the integer part of the quotient
(this / divisor) rounded down. |
CurrencyUnit |
getCurrency()
Returns the amount’s currency, modeled as
CurrencyUnit . |
MonetaryAmountFactory<? extends MonetaryAmount> |
getFactory()
Creates a new
MonetaryAmountFactory , returning the same implementation type Hereby
this given amount is used as a template, so reusing the CurrencyUnit , its numeric
value, the algorithmic implementation as well as the current MonetaryContext . |
MonetaryContext |
getMonetaryContext()
Returns the
MonetaryContext of this MonetaryAmount . |
NumberValue |
getNumber()
Simple accessor for the numeric part of a
MonetaryAmount . |
boolean |
isEqualTo(MonetaryAmount amount)
Compares two instances of
MonetaryAmount , hereby ignoring non significant trailing
zeroes and different numeric capabilities. |
boolean |
isGreaterThan(MonetaryAmount amount)
Compares two instances of
MonetaryAmount , hereby ignoring non significant trailing
zeroes and different numeric capabilities. |
boolean |
isGreaterThanOrEqualTo(MonetaryAmount amount)
Compares two instances of
MonetaryAmount , hereby ignoring non significant trailing
zeroes and different numeric capabilities. |
boolean |
isLessThan(MonetaryAmount amount)
Compares two instances of
MonetaryAmount , hereby ignoring non significant trailing
zeroes and different numeric capabilities. |
boolean |
isLessThanOrEqualTo(MonetaryAmount amt)
Compares two instances of
MonetaryAmount , hereby ignoring non significant trailing
zeroes and different numeric capabilities. |
boolean |
isNegative()
Checks if a
MonetaryAmount is negative. |
boolean |
isNegativeOrZero()
Checks if a
MonetaryAmount is negative or zero. |
boolean |
isPositive()
Checks if a
MonetaryAmount is positive. |
boolean |
isPositiveOrZero()
Checks if a
MonetaryAmount is positive or zero. |
boolean |
isZero()
Checks if an
MonetaryAmount is zero. |
MonetaryAmount |
multiply(double multiplicand)
Returns a
MonetaryAmount whose value is (this ×
multiplicand), and whose scale is (this.scale() +
multiplicand.scale()) . |
MonetaryAmount |
multiply(long multiplicand)
Returns a
MonetaryAmount whose value is (this ×
multiplicand), and whose scale is (this.scale() +
multiplicand.scale()) . |
MonetaryAmount |
multiply(java.lang.Number multiplicand)
Returns a
MonetaryAmount whose value is (this ×
multiplicand), and whose scale is (this.scale() +
multiplicand.scale()) . |
MonetaryAmount |
negate()
Returns a
MonetaryAmount whose value is (-this) , and whose scale is
this.scale() . |
MonetaryAmount |
plus()
Returns a
MonetaryAmount whose value is (+this) , with rounding according to
the context settings. |
<R> R |
query(MonetaryQuery<R> query)
Queries this monetary amount for a value.
|
MonetaryAmount |
remainder(double divisor)
Returns a
MonetaryAmount whose value is (this % divisor) . |
MonetaryAmount |
remainder(long divisor)
Returns a
MonetaryAmount whose value is (this % divisor) . |
MonetaryAmount |
remainder(java.lang.Number divisor)
Returns a
MonetaryAmount whose value is (this % divisor) . |
MonetaryAmount |
scaleByPowerOfTen(int power)
Returns a
MonetaryAmount whose numerical value is equal to ( this *
10n). |
int |
signum()
Returns the signum function of this
MonetaryAmount . |
MonetaryAmount |
stripTrailingZeros()
Returns a
MonetaryAmount which is numerically equal to this one but with any trailing
zeros removed from the representation. |
MonetaryAmount |
subtract(MonetaryAmount amount)
Returns a
MonetaryAmount whose value is (this -
amount) , and whose scale is max(this.scale(),
subtrahend.scale()) . |
MonetaryAmount |
with(MonetaryOperator operator)
Returns an operated object of the same type as this object with the operation made.
|
MonetaryAmount abs()
MonetaryAmount
whose value is the absolute value of this
MonetaryAmount
, and whose scale is this.scale()
.abs(this)
MonetaryAmount add(MonetaryAmount amount)
MonetaryAmount
whose value is (this +
amount)
, and whose scale is max(this.scale(),
amount.scale())
.amount
- value to be added to this MonetaryAmount
.this + amount
java.lang.ArithmeticException
- if the result exceeds the numeric capabilities of this implementation class, i.e.
the MonetaryContext
cannot be adapted as required.MonetaryAmount divide(double divisor)
MonetaryAmount
whose value is (this /
divisor)
, and whose preferred scale is (this.scale() -
divisor.scale())
; if the exact quotient cannot be represented an ArithmeticException
is thrown.divisor
- value by which this MonetaryAmount
is to be divided.this / divisor
java.lang.ArithmeticException
- if the exact quotient does not have a terminating decimal expansion, or if the
result exceeds the numeric capabilities of this implementation class, i.e. the
MonetaryContext
cannot be adapted as required.MonetaryAmount divide(long divisor)
MonetaryAmount
whose value is (this /
divisor)
, and whose preferred scale is (this.scale() -
divisor.scale())
; if the exact quotient cannot be represented an ArithmeticException
is thrown.divisor
- value by which this MonetaryAmount
is to be divided.this / divisor
java.lang.ArithmeticException
- if the exact quotient does not have a terminating decimal expansion, or if the
result exceeds the numeric capabilities of this implementation class, i.e. the
MonetaryContext
cannot be adapted as required.MonetaryAmount divide(java.lang.Number divisor)
MonetaryAmount
whose value is (this /
divisor)
, and whose preferred scale is (this.scale() -
divisor.scale())
; if the exact quotient cannot be represented an ArithmeticException
is thrown.divisor
- value by which this MonetaryAmount
is to be divided.this / divisor
java.lang.ArithmeticException
- if the exact quotient does not have a terminating decimal expansion, or if the
result exceeds the numeric capabilities of this implementation class, i.e. the
MonetaryContext
cannot be adapted as required.MonetaryAmount[] divideAndRemainder(double divisor)
MonetaryAmount
array containing the result of
divideToIntegralValue
followed by the result of remainder
on the two
operands.
Note that if both the integer quotient and remainder are needed, this method is faster than
using the divideToIntegralValue
and remainder
methods separately because the
division need only be carried out once.
divisor
- value by which this MonetaryAmount
is to be divided, and the remainder
computed.MonetaryAmount
array: the quotient (the result of
divideToIntegralValue
) is the initial element and the remainder is the final
element.java.lang.ArithmeticException
- if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.divideToIntegralValue(double)
,
remainder(double)
MonetaryAmount[] divideAndRemainder(long divisor)
MonetaryAmount
array containing the result of
divideToIntegralValue
followed by the result of remainder
on the two
operands.
Note that if both the integer quotient and remainder are needed, this method is faster than
using the divideToIntegralValue
and remainder
methods separately because the
division need only be carried out once.
divisor
- value by which this MonetaryAmount
is to be divided, and the remainder
computed.MonetaryAmount
array: the quotient (the result of
divideToIntegralValue
) is the initial element and the remainder is the final
element.java.lang.ArithmeticException
- if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.divideToIntegralValue(long)
,
remainder(long)
MonetaryAmount[] divideAndRemainder(java.lang.Number divisor)
MonetaryAmount
array containing the result of
divideToIntegralValue
followed by the result of remainder
on the two
operands.
Note that if both the integer quotient and remainder are needed, this method is faster than
using the divideToIntegralValue
and remainder
methods separately because the
division need only be carried out once.
divisor
- value by which this MonetaryAmount
is to be divided, and the remainder
computed.MonetaryAmount
array: the quotient (the result of
divideToIntegralValue
) is the initial element and the remainder is the final
element.java.lang.ArithmeticException
- if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.divideToIntegralValue(Number)
,
remainder(Number)
MonetaryAmount divideToIntegralValue(double divisor)
MonetaryAmount
whose value is the integer part of the quotient
(this / divisor)
rounded down. The preferred scale of the result is
(this.scale() -
divisor.scale())
.divisor
- value by which this BigDecimal
is to be divided.this / divisor
.java.lang.ArithmeticException
- if divisor==0
java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)
MonetaryAmount divideToIntegralValue(long divisor)
MonetaryAmount
whose value is the integer part of the quotient
(this / divisor)
rounded down. The preferred scale of the result is
(this.scale() -
divisor.scale())
.divisor
- value by which this BigDecimal
is to be divided.this / divisor
.java.lang.ArithmeticException
- if divisor==0
java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)
MonetaryAmount divideToIntegralValue(java.lang.Number divisor)
MonetaryAmount
whose value is the integer part of the quotient
(this / divisor)
rounded down. The preferred scale of the result is
(this.scale() -
divisor.scale())
.divisor
- value by which this BigDecimal
is to be divided.this / divisor
.java.lang.ArithmeticException
- if divisor==0
java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)
CurrencyUnit getCurrency()
CurrencyUnit
. Implementations may
co-variantly change the return type to a more specific implementation of CurrencyUnit
if desired.getCurrency
in interface CurrencySupplier
null
MonetaryAmountFactory<? extends MonetaryAmount> getFactory()
MonetaryAmountFactory
, returning the same implementation type Hereby
this given amount is used as a template, so reusing the CurrencyUnit
, its numeric
value, the algorithmic implementation as well as the current MonetaryContext
.
This method is used for creating a new amount result after having done calculations that are not directly mappable to the default monetary arithmetics, e.g. currency conversion.
MonetaryAmountFactory
with the given MonetaryAmount
as its
default values.MonetaryContext getMonetaryContext()
MonetaryContext
of this MonetaryAmount
. The
MonetaryContext
provides additional information about the numeric representation and
the numeric capabilities. This information can be used by code to determine situations where
MonetaryAmount
instances must be converted to avoid implicit truncation, which can
lead to invalid results.MonetaryContext
of this MonetaryAmount
, never null
.NumberValue getNumber()
MonetaryAmount
. The representation type
returned should be the best matching according to the internal representation. In all cases
never any truncation should occur, so this method must be exact regarding the numeric value
externalized.getNumber
in interface NumberSupplier
MonetaryAmount
, never null
.boolean isEqualTo(MonetaryAmount amount)
MonetaryAmount
, hereby ignoring non significant trailing
zeroes and different numeric capabilities.amount
- the MonetaryAmount
to be compared with this instance.true
if amount == this
.MonetaryException
- if the amount's currency is not equals to the currency of this instance.boolean isGreaterThan(MonetaryAmount amount)
MonetaryAmount
, hereby ignoring non significant trailing
zeroes and different numeric capabilities.amount
- the MonetaryAmount
to be compared with this instance.true
if amount > this
.MonetaryException
- if the amount's currency is not equals to the currency of this instance.boolean isGreaterThanOrEqualTo(MonetaryAmount amount)
MonetaryAmount
, hereby ignoring non significant trailing
zeroes and different numeric capabilities.amount
- the MonetaryAmount
to be compared with this instance.true
if amount >= this
.MonetaryException
- if the amount's currency is not equals to the currency of this instance.boolean isLessThan(MonetaryAmount amount)
MonetaryAmount
, hereby ignoring non significant trailing
zeroes and different numeric capabilities.amount
- the MonetaryAmount
to be compared with this instance.true
if amount < this
.MonetaryException
- if the amount's currency is not equals to the currency of this instance.boolean isLessThanOrEqualTo(MonetaryAmount amt)
MonetaryAmount
, hereby ignoring non significant trailing
zeroes and different numeric capabilities.amt
- the MonetaryAmount
to be compared with this instance.true
if amount <= this
.MonetaryException
- if the amount's currency is not equals to the currency of this instance.boolean isNegative()
MonetaryAmount
is negative.true
if signum()
< 0.boolean isNegativeOrZero()
MonetaryAmount
is negative or zero.true
if signum()
<= 0.boolean isPositive()
MonetaryAmount
is positive.true
if signum()
> 0.boolean isPositiveOrZero()
MonetaryAmount
is positive or zero.true
if signum()
>= 0.boolean isZero()
MonetaryAmount
is zero.true
if signum()
== 0.MonetaryAmount multiply(double multiplicand)
MonetaryAmount
whose value is (this ×
multiplicand), and whose scale is (this.scale() +
multiplicand.scale())
.multiplicand
- value to be multiplied by this MonetaryAmount
.this * multiplicand
java.lang.ArithmeticException
- if the result exceeds the numeric capabilities of this implementation class, i.e.
the MonetaryContext
cannot be adapted as required.MonetaryAmount multiply(long multiplicand)
MonetaryAmount
whose value is (this ×
multiplicand), and whose scale is (this.scale() +
multiplicand.scale())
.multiplicand
- value to be multiplied by this MonetaryAmount
.this * multiplicand
java.lang.ArithmeticException
- if the result exceeds the numeric capabilities of this implementation class, i.e.
the MonetaryContext
cannot be adapted as required.MonetaryAmount multiply(java.lang.Number multiplicand)
MonetaryAmount
whose value is (this ×
multiplicand), and whose scale is (this.scale() +
multiplicand.scale())
.multiplicand
- value to be multiplied by this MonetaryAmount
.this * multiplicand
java.lang.ArithmeticException
- if the result exceeds the numeric capabilities of this implementation class, i.e.
the MonetaryContext
cannot be adapted as required.MonetaryAmount negate()
MonetaryAmount
whose value is (-this)
, and whose scale is
this.scale()
.-this
.MonetaryAmount plus()
MonetaryAmount
whose value is (+this)
, with rounding according to
the context settings.this
, rounded as necessary. A zero result will have a scale of 0.java.lang.ArithmeticException
- if rounding fails.java.math.BigDecimal#plus()
<R> R query(MonetaryQuery<R> query)
This queries this amount using the specified query strategy object.
Implementations must ensure that no observable state is altered when this read-only method is invoked.
R
- the type of the resultquery
- the query to invoke, not nullMonetaryAmount remainder(double divisor)
MonetaryAmount
whose value is (this % divisor)
.
The remainder is given by
this.subtract(this.divideToIntegralValue(divisor).multiply(divisor))
. Note that this
is not the modulo operation (the result can be negative).
divisor
- value by which this MonetaryAmount
is to be divided.this % divisor
.java.lang.ArithmeticException
- if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.MonetaryAmount remainder(long divisor)
MonetaryAmount
whose value is (this % divisor)
.
The remainder is given by
this.subtract(this.divideToIntegralValue(divisor).multiply(divisor))
. Note that this
is not the modulo operation (the result can be negative).
divisor
- value by which this MonetaryAmount
is to be divided.this % divisor
.java.lang.ArithmeticException
- if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.MonetaryAmount remainder(java.lang.Number divisor)
MonetaryAmount
whose value is (this % divisor)
.
The remainder is given by
this.subtract(this.divideToIntegralValue(divisor).multiply(divisor))
. Note that this
is not the modulo operation (the result can be negative).
divisor
- value by which this MonetaryAmount
is to be divided.this % divisor
.java.lang.ArithmeticException
- if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.MonetaryAmount scaleByPowerOfTen(int power)
MonetaryAmount
whose numerical value is equal to ( this
*
10n). The scale of the result is (this.scale() - n)
.power
- the power.java.lang.ArithmeticException
- if the scale would be outside the range of a 32-bit integer, or if the result
exceeds the numeric capabilities of this implementation class, i.e. the
MonetaryContext
cannot be adapted as required.int signum()
MonetaryAmount
.MonetaryAmount
is negative, zero, or
positive.MonetaryAmount stripTrailingZeros()
MonetaryAmount
which is numerically equal to this one but with any trailing
zeros removed from the representation. For example, stripping the trailing zeros from the
MonetaryAmount
value CHF 600.0
, which has [BigInteger
, scale
]
components equals to [6000, 1], yields 6E2
with [ BigInteger
, scale
]
components equals to [6, -2]MonetaryAmount
with any trailing zeros removed.MonetaryAmount subtract(MonetaryAmount amount)
MonetaryAmount
whose value is (this -
amount)
, and whose scale is max(this.scale(),
subtrahend.scale())
.amount
- value to be subtracted from this MonetaryAmount
.this - amount
java.lang.ArithmeticException
- if the result exceeds the numeric capabilities of this implementation class, i.e.
the MonetaryContext
cannot be adapted as required.MonetaryAmount with(MonetaryOperator operator)
MonetaryAmountFactory
instances: // converting from Money to MyMoney Money m = ...; MonetartyAmountFactoryf = MonetaryAmounts.getAmountFactory(MyMoney.class); MyMoney myMoney = f.setAmount(m).create();
This converts this monetary amount according to the rules of the specified operator. A typical operator will change the amount and leave the currency unchanged. A more complex operator might also change the currency.
Some example code indicating how and why this method is used:
Hereby also the method signature on the implementation type must return the concrete type, to enable a fluent API, e.g.MonetaryAmount money = money.with(amountMultipliedBy(2)); money = money.with(amountRoundedToNearestWholeUnit());
public final class MyMoney implements MonetaryAmount{ ... public MyMoney with(MonetaryOperator operator){ ... } ... }
operator
- the operator to use, not null