Module life.expert

Package life.expert.value.numeric.amount

Interface Quantity

All Superinterfaces:

java.lang.Comparable<Quantity>

All Known Implementing Classes:

Amount, BigAmount, ForwardingQuantity, RoundedAmount

public interface Quantity
extends java.lang.Comparable<Quantity>

Interface defining an amount. The effective format representation of an amount may vary depending on the implementation used. Reason behind is that the requirements to an implementation heavily vary for different usage scenarios.

• Arithmetic operations should throw an 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 format rounding, as required by the format numeric representation of an amount.
• Quantitys should allow numbers as argument for arithmetic operations like division and multiplication. Adding or subtracting of amounts must only be possible by passing instances of Quantity.
• Nevertheless numeric truncation is also explicitly supported when calling NumberValue.numberValue(Class), whereas the exact counterpart, NumberValue.numberValueExact(Class), works similar to BigDecimal.longValueExact().
• Since implementations are recommended to be immutable, an operation should never change any format state of an instance. Given an instance, all operations are required to be fully reproducible.

Method Summary

Modifier and Type	Method	Description
Quantity	abs()	Returns a Quantity whose value is the absolute value of this Quantity, and whose scale is this.scale().
Quantity	add(Quantity amount)	Returns a Quantity whose value is
Quantity	divide(double divisor)	Returns a Quantity whose value is
Quantity	divide(long divisor)	Returns a Quantity whose value is
Quantity	divide(java.lang.Number divisor)	Returns a Quantity whose value is
Quantity[]	divideAndRemainder(double divisor)	Returns a two-element Quantity array containing the result of divideToIntegralValue followed by the result of remainder on the two operands.
Quantity[]	divideAndRemainder(long divisor)	Returns a two-element Quantity array containing the result of divideToIntegralValue followed by the result of remainder on the two operands.
Quantity[]	divideAndRemainder(java.lang.Number divisor)	Returns a two-element Quantity array containing the result of divideToIntegralValue followed by the result of remainder on the two operands.
Quantity	divideToIntegralValue(double divisor)	Returns a Quantity whose value is the integer part of the quotient
Quantity	divideToIntegralValue(long divisor)	Returns a Quantity whose value is the integer part of the quotient
Quantity	divideToIntegralValue(java.lang.Number divisor)	Returns a Quantity whose value is the integer part of the quotient
Context	getContext()	Returns the Context of this Quantity.
NumberValue	getNumber()	Gets the corresponding NumberValue.
Unit	getUnit()	Gets the corresponding Unit.
boolean	isEqualTo(Quantity amount)	Compares two instances of Quantity, hereby ignoring non significant trailing zeroes and different numeric capabilities.
boolean	isGreaterThan(Quantity amount)	Compares two instances of Quantity, hereby ignoring non significant trailing zeroes and different numeric capabilities.
boolean	isGreaterThanOrEqualTo(Quantity amount)	Compares two instances of Quantity, hereby ignoring non significant trailing zeroes and different numeric capabilities.
boolean	isLessThan(Quantity amount)	Compares two instances of Quantity, hereby ignoring non significant trailing zeroes and different numeric capabilities.
boolean	isLessThanOrEqualTo(Quantity amount)	Compares two instances of Quantity, hereby ignoring non significant trailing zeroes and different numeric capabilities.
default boolean	isNegative()	Checks if a Quantity is negative.
default boolean	isNegativeOrZero()	Checks if a Quantity is negative or zero.
default boolean	isPositive()	Checks if a Quantity is positive.
default boolean	isPositiveOrZero()	Checks if a Quantity is positive or zero.
default boolean	isZero()	Checks if an Quantity is zero.
Quantity	multiply(double multiplicand)	Returns a Quantity whose value is (this × multiplicand), and whose scale is
Quantity	multiply(long multiplicand)	Returns a Quantity whose value is (this × multiplicand), and whose scale is
Quantity	multiply(java.lang.Number multiplicand)	Returns a Quantity whose value is (this × multiplicand) , and whose scale is
Quantity	negate()	Returns a Quantity whose value is
Quantity	plus()	Returns a Quantity whose value is
Quantity	remainder(double divisor)	Returns a Quantity whose value is
Quantity	remainder(long divisor)	Returns a Quantity whose value is
Quantity	remainder(java.lang.Number divisor)	Returns a Quantity whose value is
Quantity	scaleByPowerOfTen(int power)	Returns a Quantity whose numerical value is equal to ( this * 10n).
int	signum()	Returns the signum function of this Quantity.
Quantity	stripTrailingZeros()	Returns a Quantity which is numerically equal to this one but with any trailing zeros removed from the representation.
Quantity	subtract(Quantity amount)	Returns a Quantity whose value is
default Quantity	with(Operator operator)	Returns an operated object of the same type as this object with the operation made.

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

getContext

Context getContext()

Returns the Context of this Quantity. The Context provides additional information about the numeric representation and the numeric capabilities. This information can be used by code to determine situations where Qunatity instances must be converted to avoid implicit truncation, which can lead to invalid results.

Returns:

the Context of this Quantity, never null .

getUnit

Unit getUnit()

Gets the corresponding Unit.

Returns:

the corresponding Unit, not null.

getNumber

NumberValue getNumber()

Gets the corresponding NumberValue.

Returns:

the corresponding NumberValue, not null.

with

default Quantity with(Operator operator)

Returns an operated object of the same type as this object with the operation made. Hereby returning an instannce of the same type is very important to prevent uncontrolled mixup of implementations. This converts this amount according to the rules of the specified operator. A typical operator will change the amount and leave the unit unchanged. A more complex operator might also change the unit. Some example code indicating how and why this method is used:

 Quantity pieces = pieces.with(amountMultipliedBy(2));
 pieces = pieces.with(amountRoundedToNearestWholeUnit());
 

Hereby also the method signature on the implementation type must return the concrete type, to enable a fluent API, e.g.

 public final class MyAmount implements Quantity{
   ...
   public MyAmount with(Operator operator){
     ...
   }

   ...
 }
 

Parameters:

operator - the operator to use, not null

Returns:

an object of the same type with the specified conversion made, not null

isGreaterThan

boolean isGreaterThan(Quantity amount)

Compares two instances of Quantity, hereby ignoring non significant trailing zeroes and different numeric capabilities.

Parameters:

amount - the Quantity to be compared with this instance.

Returns:

true if amount > this.

Throws:

ValueException - if the amount's unit is not equals to the unit of this instance.

isGreaterThanOrEqualTo

boolean isGreaterThanOrEqualTo(Quantity amount)

Compares two instances of Quantity, hereby ignoring non significant trailing zeroes and different numeric capabilities.

Parameters:

amount - the Quantity to be compared with this instance.

Returns:

true if amount >= this.

Throws:

ValueException - if the amount's unit is not equals to the unit of this instance.

isLessThan

boolean isLessThan(Quantity amount)

Compares two instances of Quantity, hereby ignoring non significant trailing zeroes and different numeric capabilities.

Parameters:

amount - the Quantity to be compared with this instance.

Returns:

true if amount < this.

Throws:

ValueException - if the amount's unit is not equals to the unit of this instance.

isLessThanOrEqualTo

boolean isLessThanOrEqualTo(Quantity amount)

Compares two instances of Quantity, hereby ignoring non significant trailing zeroes and different numeric capabilities.

Parameters:

amount - the amount

Returns:

true if amount <= this.

Throws:

ValueException - if the amount's unit is not equals to the unit of this instance.

isEqualTo

boolean isEqualTo(Quantity amount)

Compares two instances of Quantity, hereby ignoring non significant trailing zeroes and different numeric capabilities.

Parameters:

amount - the Quantity to be compared with this instance.

Returns:

true if amount == this.

Throws:

ValueException - if the amount's unit is not equals to the unit of this instance.

isNegative

default boolean isNegative()

Checks if a Quantity is negative.

Returns:

true if signum() <0

isNegativeOrZero

default boolean isNegativeOrZero()

Checks if a Quantity is negative or zero.

Returns:

true if signum() <= 0.

isPositive

default boolean isPositive()

Checks if a Quantity is positive.

Returns:

true if signum() > 0.

isPositiveOrZero

default boolean isPositiveOrZero()

Checks if a Quantity is positive or zero.

Returns:

true if signum() >= 0

isZero

default boolean isZero()

Checks if an Quantity is zero.

Returns:

true if signum() == 0.

signum

int signum()

Returns the signum function of this Quantity.

Returns:

-1, 0, or 1 as the value of this Quantity is negative, zero, or positive.

add

Quantity add(Quantity amount)

Returns a Quantity whose value is

this + amount

, and whose scale is

max(this.scale(),
 amount.scale()

.

Parameters:

amount - value to be added to this Quantity.

Returns:

this + amount

Throws:

java.lang.ArithmeticException - if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

subtract

Quantity subtract(Quantity amount)

Returns a Quantity whose value is

this -
 amount

, and whose scale is

max(this.scale(),
 subtrahend.scale()

.

Parameters:

amount - value to be subtracted from this Quantity.

Returns:

this - amount

Throws:

java.lang.ArithmeticException - if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

multiply

Quantity multiply(long multiplicand)

Returns a Quantity whose value is (this × multiplicand), and whose scale is

this.scale() +
 multiplicand.scale()

.

Parameters:

multiplicand - value to be multiplied by this Quantity.

Returns:

this * multiplicand

Throws:

java.lang.ArithmeticException - if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

multiply

Quantity multiply(double multiplicand)

Returns a Quantity whose value is (this × multiplicand), and whose scale is

this.scale() +
 multiplicand.scale()

. By default the input value's scale will be rounded to accommodate the format capabilities, and no ArithmeticException is thrown if the input number's scale exceeds the capabilities.

Parameters:

multiplicand - value to be multiplied by this Quantity. If the multiplicand's scale exceeds the capabilities of the implementation, it may be rounded implicitly.

Returns:

this * multiplicand

Throws:

java.lang.ArithmeticException - if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

multiply

Quantity multiply(java.lang.Number multiplicand)

Returns a Quantity whose value is (this × multiplicand) , and whose scale is

this.scale() +
 multiplicand.scale()

.

Parameters:

multiplicand - value to be multiplied by this Quantity. If the multiplicand's scale exceeds the capabilities of the implementation, it may be rounded implicitly.

Returns:

this * multiplicand

Throws:

java.lang.ArithmeticException - if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

divide

Quantity divide(long divisor)

Returns a Quantity 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.

Parameters:

divisor - value by which this Quantity is to be divided.

Returns:

this / divisor

Throws:

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 PieceContext cannot be adapted as required.

divide

Quantity divide(double divisor)

Returns a Quantity 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.

Parameters:

divisor - value by which this Quantity is to be divided.

Returns:

this / divisor

Throws:

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 PieceContext cannot be adapted as required.

divide

Quantity divide(java.lang.Number divisor)

Returns a Quantity 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.

Parameters:

divisor - value by which this Quantity is to be divided.

Returns:

this / divisor

Throws:

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 PieceContext cannot be adapted as required.

remainder

Quantity remainder(long divisor)

Returns a Quantity 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).

Parameters:

divisor - value by which this Quantity is to be divided.

Returns:

this % divisor.

Throws:

java.lang.ArithmeticException - if divisor==0, or if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

remainder

Quantity remainder(double divisor)

Returns a Quantity 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).

Parameters:

divisor - value by which this Quantity is to be divided.

Returns:

this % divisor.

Throws:

java.lang.ArithmeticException - if divisor==0, or if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

remainder

Quantity remainder(java.lang.Number divisor)

Returns a Quantity 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).

Parameters:

divisor - value by which this Quantity is to be divided.

Returns:

this % divisor.

Throws:

java.lang.ArithmeticException - if divisor==0, or if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

divideAndRemainder

Quantity[] divideAndRemainder(long divisor)

Returns a two-element Quantity 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.

Parameters:

divisor - value by which this Quantity is to be divided, and the remainder computed.

Returns:

a two element Quantity array: the quotient (the result of divideToIntegralValue) is the initial element and the remainder is the final element.

Throws:

java.lang.ArithmeticException - if divisor==0, or if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

See Also:

#divideToIntegralValue(long)#divideToIntegralValue(long)#divideToIntegralValue(long)#divideToIntegralValue(long)#divideToIntegralValue(long), #remainder(long)#remainder(long)#remainder(long)#remainder(long)#remainder(long)

divideAndRemainder

Quantity[] divideAndRemainder(double divisor)

Returns a two-element Quantity 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.

Parameters:

divisor - value by which this Quantity is to be divided, and the remainder computed.

Returns:

a two element Quantity array: the quotient (the result of divideToIntegralValue) is the initial element and the remainder is the final element.

Throws:

java.lang.ArithmeticException - if divisor==0, or if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

See Also:

#divideToIntegralValue(double)#divideToIntegralValue(double)#divideToIntegralValue(double)#divideToIntegralValue(double)#divideToIntegralValue(double), #remainder(double)#remainder(double)#remainder(double)#remainder(double)#remainder(double)

divideAndRemainder

Quantity[] divideAndRemainder(java.lang.Number divisor)

Returns a two-element Quantity 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.

Parameters:

divisor - value by which this Quantity is to be divided, and the remainder computed.

Returns:

a two element Quantity array: the quotient (the result of divideToIntegralValue) is the initial element and the remainder is the final element.

Throws:

java.lang.ArithmeticException - if divisor==0, or if the result exceeds the numeric capabilities of this implementation class, i.e. the PieceContext cannot be adapted as required.

See Also:

#divideToIntegralValue(Number)#divideToIntegralValue(Number)#divideToIntegralValue(Number)#divideToIntegralValue(Number)#divideToIntegralValue(Number), #remainder(Number)#remainder(Number)#remainder(Number)#remainder(Number)#remainder(Number)

divideToIntegralValue

Quantity divideToIntegralValue(long divisor)

Returns a Quantity whose value is the integer part of the quotient

this / divisor

rounded down. The preferred scale of the result is

this.scale() -
 divisor.scale()

.

Parameters:

divisor - value by which this BigDecimal is to be divided.

Returns:

The integer part of this / divisor.

Throws:

java.lang.ArithmeticException - if divisor==0

See Also:

java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)

divideToIntegralValue

Quantity divideToIntegralValue(double divisor)

Returns a Quantity whose value is the integer part of the quotient

this / divisor

rounded down. The preferred scale of the result is

this.scale() - divisor.scale()

.

Parameters:

divisor - value by which this BigDecimal is to be divided.

Returns:

The integer part of this / divisor.

Throws:

java.lang.ArithmeticException - if divisor==0

See Also:

java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)

divideToIntegralValue

Quantity divideToIntegralValue(java.lang.Number divisor)

Returns a Quantity whose value is the integer part of the quotient

this / divisor

rounded down. The preferred scale of the result is

this.scale() -
 divisor.scale()

.

Parameters:

divisor - value by which this BigDecimal is to be divided.

Returns:

The integer part of this / divisor.

Throws:

java.lang.ArithmeticException - if divisor==0

See Also:

java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)

scaleByPowerOfTen

Quantity scaleByPowerOfTen(int power)

Returns a Quantity whose numerical value is equal to ( this * 10ⁿ). The scale of the result is

this.scale() - n

.

Parameters:

power - the power.

Returns:

the calculated amount value.

Throws:

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 PieceContext cannot be adapted as required.

abs

Quantity abs()

Returns a Quantity whose value is the absolute value of this Quantity, and whose scale is this.scale().

Returns:

abs(this

negate

Quantity negate()

Returns a Quantity whose value is

-this

, and whose scale is this.scale().

Returns:

-this.

plus

Quantity plus()

Returns a Quantity whose value is

+this

, with rounding according to the context settings.

Returns:

this, rounded as necessary. A zero result will have a scale of 0.

Throws:

java.lang.ArithmeticException - if rounding fails.

See Also:

java.math.BigDecimal#plus()java.math.BigDecimal#plus()java.math.BigDecimal#plus()java.math.BigDecimal#plus()java.math.BigDecimal#plus()

stripTrailingZeros

Quantity stripTrailingZeros()

Returns a Quantity which is numerically equal to this one but with any trailing zeros removed from the representation. For example, stripping the trailing zeros from the Quantity value UNIT 600.0, which has [BigInteger, scale] components equals to [6000, 1], yields 6E2 with [ BigInteger, scale] components equals to [6, -2]

Returns:

a numerically equal Quantity with any trailing zeros removed.