Amount (SIRIUS kernel 12.0-rc9 API)

java.lang.Object
- sirius.kernel.commons.Amount

All Implemented Interfaces:

Comparable<Amount>
```
@Immutable
public class Amount
extends Object
implements Comparable<Amount>
```
Provides a wrapper around BigDecimal to perform "exact" computations on numeric values.
Adds some extended computations as well as locale aware formatting options to perform "exact" computations on numeric value. The internal representation is BigDecimal and uses MathContext.DECIMAL128 for numerical operations. Also the scale of each value is fixed to 5 decimal places after the comma, since this is enough for most business applications and rounds away any rounding errors introduced by doubles.
A textual representation can be created by calling one of the toString methods or by supplying a NumberFormat.
Being able to be empty, this class handles null values gracefully, which simplifies many operations.

See Also:

NumberFormat, BigDecimal

Field Summary

Fields
Modifier and Type	Field and Description
`static Amount`	`MINUS_ONE` Representation of -1.00
`static Amount`	`NOTHING` Represents an missing number.
`static Amount`	`ONE` Representation of 1.00
`static Amount`	`ONE_HUNDRED` Representation of 100.00
`static int`	`SCALE` Defines the internal precision used for all computations.
`static Amount`	`TEN` Representation of 10.00
`static Amount`	`ZERO` Representation of 0.00

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Amount`	`add(Amount other)` Adds the given number to `this`, if `other` is not empty.
`Amount`	`asDecimal()` Converts a percent value into a decimal fraction i.e. 34 % to 0.34 Effectively this is `this / 100`
`int`	`compareTo(Amount o)` Compares this amount against the given one.
`Amount`	`computeIfNull(Supplier<Amount> supplier)` If this actual number if empty, the given supplier is used to compute one.
`Amount`	`decreasePercent(Amount decrease)` Decreases this number by the given amount in percent.
`Amount`	`divideBy(Amount other)` Divides `this` by the given number.
`boolean`	`equals(Object o)`
`Amount`	`fill(Amount valueIfNothing)` If this actual number if empty, the given value will be returned.
`BigDecimal`	`getAmount()` Unwraps the internally used `BigDecimal`.
`long`	`getDigits()` Returns the number of decimal digits (ignoring decimal places after the decimal separator).
`int`	`hashCode()`
`Amount`	`increasePercent(Amount increase)` Increases this number by the given amount in percent.
`boolean`	`isEmpty()` Checks if this contains no value.
`boolean`	`isFilled()` Checks if this actual number contains a value or not
`boolean`	`isGreaterThan(Amount o)` Determines if this amount is greater than the given one.
`boolean`	`isGreaterThanOrEqual(Amount o)` Determines if this amount is greater than or equal to the given one.
`boolean`	`isLessThan(Amount o)` Determines if this amount is less than the given one.
`boolean`	`isLessThanOrEqual(Amount o)` Determines if this amount is less than or equal to the given one.
`boolean`	`isNegative()` Determines if the value is filled and less than 0.00
`boolean`	`isNonZero()` Determines if the value is filled and not equal to 0.00.
`boolean`	`isPositive()` Determines if the value is filled and greater than 0.00
`boolean`	`isZero()` Determines if the value is filled and equal to 0.00.
`boolean`	`isZeroOrNull()` Determines if the value is empty or equal to 0.00
`Amount`	`max(Amount other)` Compares this amount against the given amount and returns the one with the higher value.
`Amount`	`min(Amount other)` Compares this amount against the given amount and returns the one with the lower value.
`Amount`	`multiplyPercent(Amount percent)` Used to multiply two percentages, like two discounts as if they where applied after each other.
`Amount`	`negate()` Negates `this` amount and returns the new amount.
`static Amount`	`of(BigDecimal amount)` Converts the given value into a number.
`static Amount`	`of(double amount)` Converts the given value into a number.
`static Amount`	`of(Double amount)` Converts the given value into a number.
`static Amount`	`of(int amount)` Converts the given value into a number.
`static Amount`	`of(Integer amount)` Converts the given value into a number.
`static Amount`	`of(long amount)` Converts the given value into a number.
`static Amount`	`of(Long amount)` Converts the given value into a number.
`static Amount`	`ofMachineString(String value)` Converts the given string into a number.
`static Amount`	`ofUserString(String value)` Converts the given string into a number which is formatted according the decimal symbols for the current locale.
`Amount`	`percentageDifferenceOf(Amount other)` Returns the increase in percent of `this` over `other`.
`Amount`	`percentageOf(Amount other)` Returns the ratio in percent from `this` to `other`.
`Amount`	`remainder(Amount other)` Returns a `Amount` whose value is `(this % other)`.
`Amount`	`round(int scale, RoundingMode roundingMode)` Rounds the number according to the given format.
`Amount`	`round(NumberFormat format)` Rounds the number according to the given format.
`Amount`	`subtract(Amount other)` Subtracts the given number from `this`, if `other` is not empty.
`Amount`	`times(Amount other)` Multiplies the given number with `this`.
`Amount`	`toPercent()` Converts a given decimal fraction into a percent value i.e. 0.34 to 34 %.
`String`	`toPercentString()` Formats the represented value as percentage.
`String`	`toRomanNumeralString()` Tries to convert the wrapped value to a roman numeral representation.
`String`	`toRoundedString()` Formats the represented value by rounding to zero decimal places.
`String`	`toScientificString(int digits, String unit)` Creates a "scientific" representation of the amount.
`Value`	`toSmartRoundedString(NumberFormat format)` Converts the number into a string just like `toString(NumberFormat)`.
`String`	`toString()`
`Value`	`toString(NumberFormat format)` Converts the number into a string according to the given `format`.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - NOTHING
```
public static final Amount NOTHING
```
    Represents an missing number. This is also the result of division by 0 and other forbidden operations.
  - ONE_HUNDRED
```
public static final Amount ONE_HUNDRED
```
    Representation of 100.00
  - ZERO
```
public static final Amount ZERO
```
    Representation of 0.00
  - ONE
```
public static final Amount ONE
```
    Representation of 1.00
  - TEN
```
public static final Amount TEN
```
    Representation of 10.00
  - MINUS_ONE
```
public static final Amount MINUS_ONE
```
    Representation of -1.00
  - SCALE
```
public static final int SCALE
```
    Defines the internal precision used for all computations.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - ofMachineString
```
@Nonnull
public static Amount ofMachineString(@Nullable
                                              String value)
```
    Converts the given string into a number. If the string is empty, NOTHING is returned. If the string is malformed an exception will be thrown.
    
    Parameters:
    
    value - the string value which should be converted into a numeric value.
    
    Returns:
    
    an Amount representing the given input. NOTHING if the input was empty.
  - ofUserString
```
@Nonnull
public static Amount ofUserString(@Nullable
                                           String value)
```
    Converts the given string into a number which is formatted according the decimal symbols for the current locale.
    
    Parameters:
    
    value - the string value which should be converted into a numeric value.
    
    Returns:
    
    an Amount representing the given input. NOTHING if the input was empty.
    
    See Also:
    
    NLS
  - of
```
@Nonnull
public static Amount of(@Nullable
                                 BigDecimal amount)
```
    Converts the given value into a number.
    
    Parameters:
    
    amount - the value which should be converted into an Amount
    
    Returns:
    
    an Amount representing the given input. NOTHING if the input was empty.
  - of
```
@Nonnull
public static Amount of(int amount)
```
    Converts the given value into a number.
    
    Parameters:
    
    amount - the value which should be converted into an Amount
    
    Returns:
    
    an Amount representing the given input
  - of
```
@Nonnull
public static Amount of(long amount)
```
    Converts the given value into a number.
    
    Parameters:
    
    amount - the value which should be converted into an Amount
    
    Returns:
    
    an Amount representing the given input
  - of
```
@Nonnull
public static Amount of(double amount)
```
    Converts the given value into a number.
    
    Parameters:
    
    amount - the value which should be converted into an Amount
    
    Returns:
    
    an Amount representing the given input
  - of
```
@Nonnull
public static Amount of(@Nullable
                                 Integer amount)
```
    Converts the given value into a number.
    
    Parameters:
    
    amount - the value which should be converted into an Amount
    
    Returns:
    
    an Amount representing the given input. NOTHING if the input was empty.
  - of
```
@Nonnull
public static Amount of(@Nullable
                                 Long amount)
```
    Converts the given value into a number.
    
    Parameters:
    
    amount - the value which should be converted into an Amount
    
    Returns:
    
    an Amount representing the given input. NOTHING if the input was empty.
  - of
```
@Nonnull
public static Amount of(@Nullable
                                 Double amount)
```
    Converts the given value into a number.
    
    Parameters:
    
    amount - the value which should be converted into an Amount
    
    Returns:
    
    an Amount representing the given input. NOTHING if the input was empty.
  - getAmount
```
@Nullable
public BigDecimal getAmount()
```
    Unwraps the internally used BigDecimal. May be null if this Amount is NOTHING.
    
    Returns:
    
    the internally used BigDecimal
  - isEmpty
```
public boolean isEmpty()
```
    Checks if this contains no value.
    
    Returns:
    
    true if the internal value is null, false otherwise
  - isFilled
```
public boolean isFilled()
```
    Checks if this actual number contains a value or not
    
    Returns:
    
    true if the internal value is a number, false otherwise
  - fill
```
@Nonnull
public Amount fill(@Nonnull
                            Amount valueIfNothing)
```
    If this actual number if empty, the given value will be returned. Otherwise this will be returned.
    
    Parameters:
    
    valueIfNothing - the value which is used if there is no internal value
    
    Returns:
    
    this if there is an internal value, valueIfNothing otherwise
  - computeIfNull
```
@Nonnull
public Amount computeIfNull(Supplier<Amount> supplier)
```
    If this actual number if empty, the given supplier is used to compute one. Otherwise this will be returned.
    
    Parameters:
    
    supplier - the supplier which is used to compute a value if there is no internal value
    
    Returns:
    
    this if there is an internal value, the computed value of supplier otherwise
  - increasePercent
```
@Nonnull
 @CheckReturnValue
public Amount increasePercent(@Nonnull
                                                          Amount increase)
```
    Increases this number by the given amount in percent. If increase is 18 and the value of this is 100, the result would by 118.
    
    Parameters:
    
    increase - the percent value by which the value of this will be increased
    
    Returns:
    
    NOTHING if this is empty, this * (1 + increase / 100) otherwise
  - decreasePercent
```
@Nonnull
 @CheckReturnValue
public Amount decreasePercent(@Nonnull
                                                          Amount decrease)
```
    Decreases this number by the given amount in percent. If decrease is 10 and the value of this is 100, the result would by 90.
    
    Parameters:
    
    decrease - the percent value by which the value of this will be decreased
    
    Returns:
    
    NOTHING if this is empty, this * (1 - increase / 100) otherwise
  - multiplyPercent
```
@Nonnull
 @CheckReturnValue
public Amount multiplyPercent(@Nonnull
                                                          Amount percent)
```
    Used to multiply two percentages, like two discounts as if they where applied after each other.
    This can be used to compute the effective discount if two discounts like 15% and 5% are applied after each other. The result would be (15 + 5) - (15 * 5 / 100) which is 19,25 %
    
    Parameters:
    
    percent - the second percent value which would be applied after this percent value.
    
    Returns:
    
    the effective percent value after both percentages would have been applied or NOTHING if this is empty.
  - add
```
@Nonnull
 @CheckReturnValue
public Amount add(@Nullable
                                              Amount other)
```
    Adds the given number to this, if other is not empty. Otherwise this will be returned.
    
    Parameters:
    
    other - the operand to add to this.
    
    Returns:
    
    an Amount representing the sum of this and other if both values were filled. If other is empty, this is returned. If this is empty, NOTHING is returned.
  - subtract
```
@Nonnull
 @CheckReturnValue
public Amount subtract(@Nullable
                                                   Amount other)
```
    Subtracts the given number from this, if other is not empty. Otherwise this will be returned.
    
    Parameters:
    
    other - the operand to subtract from this.
    
    Returns:
    
    an Amount representing the difference of this and other if both values were filled. If other is empty, this is returned. If this is empty, NOTHING is returned.
  - times
```
@Nonnull
 @CheckReturnValue
public Amount times(@Nonnull
                                                Amount other)
```
    Multiplies the given number with this. If either of both is empty, NOTHING will be returned.
    
    Parameters:
    
    other - the operand to multiply with this.
    
    Returns:
    
    an Amount representing the product of this and other if both values were filled. If other is empty or if this is empty, NOTHING is returned.
  - divideBy
```
@Nonnull
 @CheckReturnValue
public Amount divideBy(@Nullable
                                                   Amount other)
```
    Divides this by the given number. If either of both is empty, or the given number is zero, NOTHING will be returned. The division uses MathContext.DECIMAL128
    
    Parameters:
    
    other - the operand to divide this by.
    
    Returns:
    
    an Amount representing the division of this by other or NOTHING if either of both is empty.
  - percentageOf
```
@Nonnull
 @CheckReturnValue
public Amount percentageOf(@Nullable
                                                       Amount other)
```
    Returns the ratio in percent from this to other. This is equivalent to this / other * 100
    
    Parameters:
    
    other - the base to compute the percentage from.
    
    Returns:
    
    an Amount representing the ratio between this and other or NOTHING if either of both is empty.
  - percentageDifferenceOf
```
@Nonnull
 @CheckReturnValue
public Amount percentageDifferenceOf(@Nonnull
                                                                 Amount other)
```
    Returns the increase in percent of this over other. This is equivalent to ((this / other) - 1) * 100
    
    Parameters:
    
    other - the base to compute the increase from.
    
    Returns:
    
    an Amount representing the percentage increase between this and other or NOTHING if either of both is empty.
  - isZero
```
public boolean isZero()
```
    Determines if the value is filled and equal to 0.00.
    
    Returns:
    
    true if this value is filled and equal to 0.00, false otherwise.
  - isNonZero
```
public boolean isNonZero()
```
    Determines if the value is filled and not equal to 0.00.
    
    Returns:
    
    true if this value is filled and not equal to 0.00, false otherwise.
  - isPositive
```
public boolean isPositive()
```
    Determines if the value is filled and greater than 0.00
    
    Returns:
    
    true if this value is filled and greater than 0.00, false otherwise.
  - isNegative
```
public boolean isNegative()
```
    Determines if the value is filled and less than 0.00
    
    Returns:
    
    true if this value is filled and less than 0.00, false otherwise.
  - isZeroOrNull
```
public boolean isZeroOrNull()
```
    Determines if the value is empty or equal to 0.00
    
    Returns:
    
    true if this value is empty, or equal to 0.00, false otherwise.
  - toPercent
```
@Nonnull
 @CheckReturnValue
public Amount toPercent()
```
    Converts a given decimal fraction into a percent value i.e. 0.34 to 34 %. Effectively this is this * 100
    
    Returns:
    
    a percentage representation of the given decimal value.
  - asDecimal
```
@Nonnull
 @CheckReturnValue
public Amount asDecimal()
```
    Converts a percent value into a decimal fraction i.e. 34 % to 0.34 Effectively this is this / 100
    
    Returns:
    
    a decimal representation fo the given percent value.
  - compareTo
```
public int compareTo(Amount o)
```
    Compares this amount against the given one.
    If both amounts are empty, they are considered equal, otherwise, if the given amount is empty, we consider this amount to be larger. Likewise, if this amount is empty, we consider the given one to be larger.
    
    Specified by:
    
    compareTo in interface Comparable<Amount>
    
    Parameters:
    
    o - the amount to compare to
    
    Returns:
    
    0 if both amounts are equal, -1 of this amount is less than the given one or 1 if this amount is greater than the given one
  - isGreaterThan
```
public boolean isGreaterThan(Amount o)
```
    Determines if this amount is greater than the given one.
    See compareTo(Amount) for an explanation of how empty amounts are handled.
    
    Parameters:
    
    o - the other amount to compare against
    
    Returns:
    
    true if this amount is greater than the given one
  - isGreaterThanOrEqual
```
public boolean isGreaterThanOrEqual(Amount o)
```
    Determines if this amount is greater than or equal to the given one.
    See compareTo(Amount) for an explanation of how empty amounts are handled.
    
    Parameters:
    
    o - the other amount to compare against
    
    Returns:
    
    true if this amount is greater than or equals to the given one
  - isLessThan
```
public boolean isLessThan(Amount o)
```
    Determines if this amount is less than the given one.
    See compareTo(Amount) for an explanation of how empty amounts are handled.
    
    Parameters:
    
    o - the other amount to compare against
    
    Returns:
    
    true if this amount is less than the given one
  - isLessThanOrEqual
```
public boolean isLessThanOrEqual(Amount o)
```
    Determines if this amount is less than or equal to the given one.
    See compareTo(Amount) for an explanation of how empty amounts are handled.
    
    Parameters:
    
    o - the other amount to compare against
    
    Returns:
    
    true if this amount is less than or equals to the given one
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - min
```
@Nonnull
public Amount min(@Nullable
                           Amount other)
```
    Compares this amount against the given amount and returns the one with the lower value.
    If either of the amounts is empty, the filled one is returned. If both are empty, an empty amount is returned.
    
    Parameters:
    
    other - the amount to compare against
    
    Returns:
    
    the amount with the lower value or an empty amount, if both amounts are empty
  - max
```
@Nonnull
public Amount max(@Nullable
                           Amount other)
```
    Compares this amount against the given amount and returns the one with the higher value.
    If either of the amounts is empty, the filled one is returned. If both are empty, an empty amount is returned.
    
    Parameters:
    
    other - the amount to compare against
    
    Returns:
    
    the amount with the higher value or an empty amount, if both amounts are empty
  - negate
```
public Amount negate()
```
    Negates this amount and returns the new amount.
    
    Returns:
    
    an Amount representing the negated Amount. If this is empty, NOTHING is returned.
  - remainder
```
public Amount remainder(Amount other)
```
    Returns a Amount whose value is (this % other).
    
    Parameters:
    
    other - the divisor value by which this Amount is to be divided.
    
    Returns:
    
    an Amount representing the remainder of the two amounts
    
    See Also:
    
    BigDecimal.remainder(BigDecimal)
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - toPercentString
```
public String toPercentString()
```
    Formats the represented value as percentage. Up to two digits will be shown if non zero. Therefore 12.34 will be rendered as 12.34 % but 5.00 will be rendered as 5 %. If the value is empty, "" will be returned.
    A custom NumberFormat can be used by directly calling toSmartRoundedString(NumberFormat) or to disable smart rounding (to also show .00) toString(NumberFormat) can be called using NumberFormat.PERCENT.
    
    Returns:
    
    a string representation of this number using NumberFormat#PERCENT or "" if the value is empty.
  - toRomanNumeralString
```
public String toRomanNumeralString()
```
    Tries to convert the wrapped value to a roman numeral representation. Any fractional part of this BigDecimal will be discarded, and if the resulting "BigInteger" is too big to fit in an int, only the low-order 32 bits are returned.
    
    Returns:
    
    a string representation of this number as roman numeral or "" for values <= 0 and >= 4000.
  - toRoundedString
```
public String toRoundedString()
```
    Formats the represented value by rounding to zero decimal places. The rounding mode is obtained from NumberFormat.NO_DECIMAL_PLACES.
    
    Returns:
    
    a rounded representation of this number using NumberFormat#NO_DECIMAL_PLACES or "" is the value is empty.
  - round
```
@Nonnull
 @CheckReturnValue
public Amount round(@Nonnull
                                                NumberFormat format)
```
    Rounds the number according to the given format. In contrast to only round values when displaying them as string, this method returns a modified Amount which as potentially lost some precision. Depending on the next computation this might return significantly different values in contrast to first performing all computations and round at the end when rendering the values as string.
    The number of decimal places and the rounding mode is obtained from format (NumberFormat).
    
    Parameters:
    
    format - the format used to determine the precision of the rounding operation
    
    Returns:
    
    returns an Amount which is rounded using the given NumberFormat or NOTHING if the value is empty.
  - round
```
@Nonnull
 @CheckReturnValue
public Amount round(int scale,
                                                @Nonnull
                                                RoundingMode roundingMode)
```
    Rounds the number according to the given format. In contrast to only round values when displaying them as string, this method returns a modified Amount which as potentially lost some precision. Depending on the next computation this might return significantly different values in contrast to first performing all computations and round at the end when rendering the values as string.
    
    Parameters:
    
    scale - the precision
    
    roundingMode - the rounding operation
    
    Returns:
    
    returns an Amount which is rounded using the given RoundingMode or NOTHING if the value is empty.
  - toString
```
@Nonnull
public Value toString(@Nonnull
                               NumberFormat format)
```
    Converts the number into a string according to the given format. The returned Value provides helpful methods to pre- or append texts like units or currency symbols while gracefully handling empty values.
    
    Parameters:
    
    format - the NumberFormat used to obtain the number of decimal places, the decimal format symbols and rounding mode
    
    Returns:
    
    a Value containing the string representation according to the given format or an empty Value if this is empty.
    
    See Also:
    
    Value.append(String, Object), Value.prepend(String, Object)
  - toSmartRoundedString
```
@Nonnull
public Value toSmartRoundedString(@Nonnull
                                           NumberFormat format)
```
    Converts the number into a string just like toString(NumberFormat). However, if the number has no decimal places, a rounded value (without .00) will be returned.
    
    Parameters:
    
    format - the NumberFormat used to obtain the number of decimal places, the decimal format symbols and rounding mode
    
    Returns:
    
    a Value containing the string representation according to the given format or an empty Value if this is empty. Omits 0 as decimal places.
    
    See Also:
    
    toString()
  - toScientificString
```
@Nonnull
public String toScientificString(int digits,
                                          String unit)
```
    Creates a "scientific" representation of the amount.
    This representation will shift the value in the range 0..999 and represent the decimal shift by a well known unit prefix. The following prefixes will be used:
    - f - femto
    - n - nano
    - u - micro
    - m - milli
    - K - kilo
    - M - mega
    - G - giga
    An input of 0.0341 V will be represented as 34.1 mV if digits was 4 or 34 mV is digits was 2 or less.
    Parameters:
    
    digits - the number of decimal digits to display
    
    unit - the unit to be appended to the generated string
    
    Returns:
    
    a scientific string representation of the amount.
  - getDigits
```
public long getDigits()
```
    Returns the number of decimal digits (ignoring decimal places after the decimal separator).
    
    Returns:
    
    the number of digits required to represent this number. Returns 0 if the value is empty.

Class Amount

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NOTHING

ONE_HUNDRED

ZERO

ONE

TEN

MINUS_ONE

SCALE

Method Detail

ofMachineString

ofUserString

of

of

of

of

of

of

of

getAmount

isEmpty

isFilled

fill

computeIfNull

increasePercent

decreasePercent

multiplyPercent

add

subtract

times

divideBy

percentageOf

percentageDifferenceOf

isZero

isNonZero

isPositive

isNegative

isZeroOrNull

toPercent

asDecimal

compareTo

isGreaterThan

isGreaterThanOrEqual

isLessThan

isLessThanOrEqual

equals

hashCode

min

max

negate

remainder

toString

toPercentString

toRomanNumeralString

toRoundedString

round

round

toString

toSmartRoundedString

toScientificString

getDigits