@Immutable public class Amount extends Object implements Comparable<Amount>
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.
NumberFormat
,
BigDecimal
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
|
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.
|
public static final Amount NOTHING
public static final Amount ONE_HUNDRED
public static final Amount ZERO
public static final Amount ONE
public static final Amount TEN
public static final Amount MINUS_ONE
public static final int SCALE
@Nonnull public static Amount ofMachineString(@Nullable String value)
value
- the string value which should be converted into a numeric value.@Nonnull public static Amount ofUserString(@Nullable String value)
value
- the string value which should be converted into a numeric value.Amount
representing the given input. NOTHING
if the input was empty.NLS
@Nonnull public static Amount of(@Nullable BigDecimal amount)
amount
- the value which should be converted into an Amount@Nonnull public static Amount of(int amount)
amount
- the value which should be converted into an Amount@Nonnull public static Amount of(long amount)
amount
- the value which should be converted into an Amount@Nonnull public static Amount of(double amount)
amount
- the value which should be converted into an Amount@Nonnull public static Amount of(@Nullable Integer amount)
amount
- the value which should be converted into an Amount@Nonnull public static Amount of(@Nullable Long amount)
amount
- the value which should be converted into an Amount@Nonnull public static Amount of(@Nullable Double amount)
amount
- the value which should be converted into an Amount@Nullable public BigDecimal getAmount()
public boolean isEmpty()
public boolean isFilled()
@Nonnull public Amount fill(@Nonnull Amount valueIfNothing)
valueIfNothing
- the value which is used if there is no internal value@Nonnull public Amount computeIfNull(Supplier<Amount> supplier)
supplier
- the supplier which is used to compute a value if there is no internal value@Nonnull @CheckReturnValue public Amount increasePercent(@Nonnull Amount increase)
increase
- the percent value by which the value of this will be increasedthis * (1 + increase / 100)
otherwise@Nonnull @CheckReturnValue public Amount decreasePercent(@Nonnull Amount decrease)
decrease
- the percent value by which the value of this will be decreasedthis * (1 - increase / 100)
otherwise@Nonnull @CheckReturnValue public Amount multiplyPercent(@Nonnull Amount percent)
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 %
percent
- the second percent value which would be applied after this percent value.@Nonnull @CheckReturnValue public Amount add(@Nullable Amount other)
other
- the operand to add to this.@Nonnull @CheckReturnValue public Amount subtract(@Nullable Amount other)
other
- the operand to subtract from this.@Nonnull @CheckReturnValue public Amount times(@Nonnull Amount other)
other
- the operand to multiply with this.@Nonnull @CheckReturnValue public Amount divideBy(@Nullable Amount other)
MathContext.DECIMAL128
other
- the operand to divide this by.@Nonnull @CheckReturnValue public Amount percentageOf(@Nullable Amount other)
this / other * 100
other
- the base to compute the percentage from.@Nonnull @CheckReturnValue public Amount percentageDifferenceOf(@Nonnull Amount other)
((this / other) - 1) * 100
other
- the base to compute the increase from.public boolean isZero()
public boolean isNonZero()
public boolean isPositive()
public boolean isNegative()
public boolean isZeroOrNull()
@Nonnull @CheckReturnValue public Amount toPercent()
this * 100
@Nonnull @CheckReturnValue public Amount asDecimal()
this / 100
public int compareTo(Amount o)
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.
compareTo
in interface Comparable<Amount>
o
- the amount to compare topublic boolean isGreaterThan(Amount o)
See compareTo(Amount)
for an explanation of how empty amounts are handled.
o
- the other amount to compare againstpublic boolean isGreaterThanOrEqual(Amount o)
See compareTo(Amount)
for an explanation of how empty amounts are handled.
o
- the other amount to compare againstpublic boolean isLessThan(Amount o)
See compareTo(Amount)
for an explanation of how empty amounts are handled.
o
- the other amount to compare againstpublic boolean isLessThanOrEqual(Amount o)
See compareTo(Amount)
for an explanation of how empty amounts are handled.
o
- the other amount to compare against@Nonnull public Amount min(@Nullable Amount other)
If either of the amounts is empty, the filled one is returned. If both are empty, an empty amount is returned.
other
- the amount to compare against@Nonnull public Amount max(@Nullable Amount other)
If either of the amounts is empty, the filled one is returned. If both are empty, an empty amount is returned.
other
- the amount to compare againstpublic Amount negate()
public Amount remainder(Amount other)
Amount
whose value is (this % other)
.other
- the divisor value by which this Amount
is to be divided.Amount
representing the remainder of the two amountsBigDecimal.remainder(BigDecimal)
public String toPercentString()
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
.
NumberFormat#PERCENT
or "" if the value is empty.public String toRomanNumeralString()
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.public String toRoundedString()
NumberFormat.NO_DECIMAL_PLACES
.NumberFormat#NO_DECIMAL_PLACES
or "" is the value is empty.@Nonnull @CheckReturnValue public Amount round(@Nonnull NumberFormat format)
The number of decimal places and the rounding mode is obtained from format (NumberFormat
).
format
- the format used to determine the precision of the rounding operationNumberFormat
or NOTHING if the value is empty.@Nonnull @CheckReturnValue public Amount round(int scale, @Nonnull RoundingMode roundingMode)
scale
- the precisionroundingMode
- the rounding operationRoundingMode
or NOTHING if the value is empty.@Nonnull public Value toString(@Nonnull NumberFormat format)
Value
provides
helpful methods to pre- or append texts like units or currency symbols while gracefully handling empty values.format
- the NumberFormat
used to obtain the number of decimal places,
the decimal format symbols and rounding modeValue.append(String, Object)
,
Value.prepend(String, Object)
@Nonnull public Value toSmartRoundedString(@Nonnull NumberFormat format)
toString(NumberFormat)
. However, if the number has no
decimal places, a rounded value (without .00) will be returned.format
- the NumberFormat
used to obtain the number of decimal places,
the decimal format symbols and rounding modetoString()
@Nonnull public String toScientificString(int digits, String unit)
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:
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.
digits
- the number of decimal digits to displayunit
- the unit to be appended to the generated stringpublic long getDigits()
Copyright © 2018. All rights reserved.