Represent an amount of money in any currency.
This class assumes decimal currency, without funky divisions like 1/5 and so on. Money objects are immutable. Like {@link BigDecimal}, many operations return new Money objects. In addition, most operations involving more than one Money object will throw a MismatchedCurrencyException if the currencies don't match.
The number of decimal places or style of units is referred to as the scale by {@link java.math.BigDecimal}. This class's constructors take a BigDecimal, so you need to understand it use of the idea of scale.
The scale can be negative. Using the above examples:
| Number | Scale |
|---|---|
| 123456.78 | 2 |
| 123456 | 0 |
| 123 (thousands) | -3 |
Note that scale and rounding are two separate issues. In addition, rounding is only necessary for multiplication and division operations. It doesn't apply to addition and subtraction.
Operations can be performed on items having different scale. For example, these operations are valid (using an ad hoc symbolic notation):
10.plus(1.23) => 11.23 10.minus(1.23) => 8.77 10.gt(1.23) => true 10.eq(10.00) => trueThis corresponds to typical user expectations. An important exception to this rule is that {@link #equals(Object)} is sensitive to scale (while{@link #eq(Money)} is not) . That is,
10.equals(10.00) => false
Operations involving multiplication and division are different, since the result can have a scale which exceeds that expected for the given currency. For example
($10.00).times(0.1256) => $1.256which has more than two decimals. In such cases, this class will always round to the expected number of decimal places for that currency. This is the simplest policy, and likely conforms to the expectations of most end users.
This class takes either an int or a {@link BigDecimal} for itsmultiplication and division methods. It doesn't take float or double for those methods, since those types don't interact well with BigDecimal. Instead, the BigDecimal class must be used when the factor or divisor is a non-integer.
The {@link #init(Currency,RoundingMode)} method must be called at least once before using the other members of this class. It establishes your desired defaults. Typically, it will be called once (and only once) upon startup.
Various methods in this class have unusually terse names, such as {@link #lt}and {@link #gt}. The intent is that such names will improve the legibility of mathematical expressions. Example :
if (amount.lt(hundred)) { cost = amount.times(price); }
| |
| |
| |
| |
| |
| |