Version 4.10.0

hirondelle.web4j.model
Class Decimal

Object
  extended by Number
      extended by hirondelle.web4j.model.Decimal
All Implemented Interfaces:
Serializable, Comparable<Decimal>

public final class Decimal
extends Number
implements Comparable<Decimal>, Serializable

Represent an immutable number, using a natural, compact syntax. The number may have a decimal portion, or it may not.

Decimal amounts are typically used to represent two kinds of items :

Your applications are not obliged to use this class to represent decimal amounts. You may choose to use BigDecimal instead (perhaps along with an Id to store a currency, if needed).

This class exists for these reasons:

Decimal objects are immutable. Many operations return new Decimal objects.

Currency Is Unspecified

This class can be used to model amounts of money.

Many will be surprised that this class does not make any reference to currency. The reason for this is adding currency would render this class a poor building block. Building block objects such as Date, Integer, and so on, are atomic, in the sense of representing a single piece of data. They correspond to a single column in a table, or a single form control. If the currency were included in this class, then it would no longer be atomic, and it could not be treated by WEB4J as any other building block class. However, allowing this class to be treated like any other building block class is highly advantageous.

If a feature needs to explicitly distinguish between multiple currencies such as US Dollars and Japanese Yen, then a Decimal object will need to be paired by the caller with a second item representing the underlying currency (perhaps modeled as an Id). See the Currency class for more information.

Number of Decimal Places

To validate the number of decimals in your Model Objects, call the Check.numDecimalsAlways(int) or Check.numDecimalsMax(int) methods.

Different Numbers of Decimals

As usual, operations can be performed on two items having a different number of decimal places. For example, these operations are valid (using an informal, ad hoc notation) :

10 + 1.23 = 11.23
10.00 + 1.23 = 11.23
10 - 1.23 = 8.77
(10 > 1.23) => true 
This corresponds to typical user expectations.

The eq(Decimal) is usually to be preferred over the equals(Object) method. The equals(Object) is unusual, in that it's the only method sensitive to the exact number of decimal places, while eq(Decimal) is not. That is,

10.equals(10.00) => false
10.eq(10.00) => true

Terse Method Names

Various methods in this class have unusually terse names, such as lt for 'less than', and gt for 'greater than', and so on. The intent of such names is to improve the legibility of mathematical expressions.

Example:

if (amount.lt(hundred)) {
  cost = amount.times(price); 
}

Prefer Decimal forms

Many methods in this class are overloaded to perform the same operation with various types:

Usually, you should prefer the Decimal form. The long and double forms are usually convenience methods, which simply call the Decimal version as part of their implementations; they're intended for cases when you simply wish to specify a hard-coded constant value.

Extends Number

This class extends Number. This allows other parts of the JDK to treat a Decimal just like any other Number.

See Also:
Serialized Form

Field Summary
static Decimal E
          An approximation to Euler's number, to 15 decimal places.
static Decimal MINUS_ONE
          Convenience constant.
static Decimal ONE
          Convenience constant.
static Decimal PI
          An approximation to the number pi, to 15 decimal places.
static RoundingMode ROUNDING
          The default rounding mode used by this class (HALF_EVEN).
static Decimal ZERO
          Zero Decimal amount, a simple convenience constant.
 
Constructor Summary
Decimal(BigDecimal aAmount)
          Constructor.
 
Method Summary
 Decimal abs()
          Return the absolute value of the amount.
 int compareTo(Decimal aThat)
          Implements the Comparable interface.
 Decimal div(Decimal aDivisor)
          Divide this Decimal by a divisor.
 Decimal div(double aDivisor)
           
 Decimal div(long aDivisor)
           
 double doubleValue()
          Required by Number.
 boolean eq(Decimal aThat)
          Equals (insensitive to number of decimals).
 boolean eq(double aThat)
           
 boolean eq(long aThat)
           
 boolean equals(Object aThat)
          Equals, sensitive to scale of the underlying BigDecimal.
 float floatValue()
          Required by Number.
static Decimal from(double aAmount)
          Convenience factory method.
static Decimal from(long aAmount)
          Convenience factory method.
static Decimal from(String aAmount)
          Convenience factory method.
 BigDecimal getAmount()
          Return the amount as a BigDecimal.
 int getNumDecimals()
          Return the number of decimals in this value.
 boolean gt(Decimal aThat)
          Greater than.
 boolean gt(double aThat)
           
 boolean gt(long aThat)
           
 boolean gteq(Decimal aThat)
          Greater than or equal to.
 boolean gteq(double aThat)
           
 boolean gteq(long aThat)
           
 int hashCode()
           
 int intValue()
          Required by Number.
 boolean isInteger()
          Return true only if this Decimal is an integer.
 boolean isMinus()
          Return true only if the amount is negative.
 boolean isPlus()
          Return true only if the amount is positive.
 boolean isZero()
          Return true only if the amount is zero.
 long longValue()
          Required by Number.
 boolean lt(Decimal aThat)
          Less than.
 boolean lt(double aThat)
           
 boolean lt(long aThat)
           
 boolean lteq(Decimal aThat)
          Less than or equal to.
 boolean lteq(double aThat)
           
 boolean lteq(long aThat)
           
 Decimal minus(Decimal aThat)
          Subtract aThat Decimal from this Decimal.
 Decimal minus(double aThat)
           
 Decimal minus(long aThat)
           
 Decimal negate()
          Return this amount x (-1).
 Decimal plus(Decimal aThat)
          Add aThat Decimal to this Decimal.
 Decimal plus(double aThat)
           
 Decimal plus(long aThat)
           
 Decimal pow(Decimal aPower)
          Raise this Decimal to a Decimal power.
 Decimal pow(double aPower)
          This implementation uses Math.pow(double, double).
 Decimal pow(int aPower)
          Raise this number to an integral power; the power can be of either sign.
 Decimal round()
          Round to an integer value, using the default ROUNDING style.
 Decimal round(int aNumberOfDecimals)
          Round to 0 or more decimal places, using the default ROUNDING style.
 Decimal round(int aNumberOfDecimals, RoundingMode aRoundingMode)
          Round to 0 or more decimal places, using the given rounding style.
 Decimal round2(Decimal aInterval)
          Round a number to the nearest multiple of the given interval.
 Decimal round2(double aInterval)
           
 Decimal round2(long aInterval)
           
static Decimal sum(Collection<Decimal> aDecimals)
          Sum a collection of Decimal objects.
 Decimal times(Decimal aFactor)
          Multiply this Decimal by a factor.
 Decimal times(double aFactor)
           
 Decimal times(long aFactor)
           
 String toString()
          Renders this Decimal in a style suitable for debugging.
 
Methods inherited from class Number
byteValue, shortValue
 
Methods inherited from class Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ROUNDING

public static final RoundingMode ROUNDING
The default rounding mode used by this class (HALF_EVEN). This rounding style results in the least bias.


ZERO

public static final Decimal ZERO
Zero Decimal amount, a simple convenience constant.

Like BigDecimal.ZERO, this item has no explicit decimal. In most cases that will not matter, since only the equals(Object) method is sensitive to exact decimals. All other methods, including eq(Decimal), are not sensitive to exact decimals.


ONE

public static final Decimal ONE
Convenience constant.


MINUS_ONE

public static final Decimal MINUS_ONE
Convenience constant.


PI

public static final Decimal PI
An approximation to the number pi, to 15 decimal places. Pi is the ratio of the circumference of a circle to its radius. It's also rumoured to taste good as well.


E

public static final Decimal E
An approximation to Euler's number, to 15 decimal places. Euler's number is the base of the natural logarithms.

Constructor Detail

Decimal

public Decimal(BigDecimal aAmount)
Constructor.

Parameters:
aAmount - required, any number of decimals.
Method Detail

from

public static Decimal from(String aAmount)
Convenience factory method. Leading zeroes are allowed.

Instead of :

Decimal decimal = new Decimal(new BigDecimal("100"));
one may instead use this more compact form:
Decimal decimal = Decimal.from("100");
which is a bit more legible.


from

public static Decimal from(long aAmount)
Convenience factory method.


from

public static Decimal from(double aAmount)
Convenience factory method.


toString

public String toString()
Renders this Decimal in a style suitable for debugging. Intended for debugging only.

Returns the amount in the format defined by BigDecimal.toPlainString().

Overrides:
toString in class Object

equals

public boolean equals(Object aThat)
Equals, sensitive to scale of the underlying BigDecimal.

That is, 10 and 10.00 are not considered equal by this method. Such behavior is often undesired; in most practical cases, it's likely best to use the eq(Decimal) method instead., which has no such monkey business.

This implementation imitates BigDecimal.equals(java.lang.Object), which is also sensitive to the number of decimals (or 'scale').

Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

compareTo

public int compareTo(Decimal aThat)
Implements the Comparable interface.

It's possible to use this method as a general replacement for a large number of methods which compare numbers: lt, eq, lteq, and so on. However, it's recommended that you use those other methods, since they have greater clarity and concision.

Specified by:
compareTo in interface Comparable<Decimal>

getAmount

public BigDecimal getAmount()
Return the amount as a BigDecimal.


getNumDecimals

public int getNumDecimals()
Return the number of decimals in this value. More accurately, this returns the 'scale' of the underlying BigDecimal. Negative scales are possible; they represent the number of zeros to be adding on to the end of an integer.


isInteger

public boolean isInteger()
Return true only if this Decimal is an integer. For example, 2 and 2.00 are integers, but 2.01 is not.


isPlus

public boolean isPlus()
Return true only if the amount is positive.


isMinus

public boolean isMinus()
Return true only if the amount is negative.


isZero

public boolean isZero()
Return true only if the amount is zero.


eq

public boolean eq(Decimal aThat)
Equals (insensitive to number of decimals). That is, 10 and 10.00 are considered equal by this method.

Return true only if the amounts are equal. This method is not synonymous with the equals method, since the equals(Object) method is sensitive to the exact number of decimal places (or, more precisely, the scale of the underlying BigDecimal.)


eq

public boolean eq(long aThat)

eq

public boolean eq(double aThat)

gt

public boolean gt(Decimal aThat)
Greater than.

Return true only if 'this' amount is greater than 'that' amount.


gt

public boolean gt(long aThat)

gt

public boolean gt(double aThat)

gteq

public boolean gteq(Decimal aThat)
Greater than or equal to.

Return true only if 'this' amount is greater than or equal to 'that' amount.


gteq

public boolean gteq(long aThat)

gteq

public boolean gteq(double aThat)

lt

public boolean lt(Decimal aThat)
Less than.

Return true only if 'this' amount is less than 'that' amount.


lt

public boolean lt(long aThat)

lt

public boolean lt(double aThat)

lteq

public boolean lteq(Decimal aThat)
Less than or equal to.

Return true only if 'this' amount is less than or equal to 'that' amount.


lteq

public boolean lteq(long aThat)

lteq

public boolean lteq(double aThat)

plus

public Decimal plus(Decimal aThat)
Add aThat Decimal to this Decimal.


plus

public Decimal plus(long aThat)

plus

public Decimal plus(double aThat)

minus

public Decimal minus(Decimal aThat)
Subtract aThat Decimal from this Decimal.


minus

public Decimal minus(long aThat)

minus

public Decimal minus(double aThat)

sum

public static Decimal sum(Collection<Decimal> aDecimals)
Sum a collection of Decimal objects.

Parameters:
aDecimals - collection of Decimal objects. If the collection is empty, then a zero value is returned.

times

public Decimal times(Decimal aFactor)
Multiply this Decimal by a factor.


times

public Decimal times(long aFactor)

times

public Decimal times(double aFactor)

div

public Decimal div(Decimal aDivisor)
Divide this Decimal by a divisor.

If the division results in a number which will never terminate, then this method will round the result to 20 decimal places, using the default ROUNDING.


div

public Decimal div(long aDivisor)

div

public Decimal div(double aDivisor)

abs

public Decimal abs()
Return the absolute value of the amount.


negate

public Decimal negate()
Return this amount x (-1).


round

public Decimal round()
Round to an integer value, using the default ROUNDING style.


round

public Decimal round(int aNumberOfDecimals)
Round to 0 or more decimal places, using the default ROUNDING style.

Parameters:
aNumberOfDecimals - must 0 or more.

round

public Decimal round(int aNumberOfDecimals,
                     RoundingMode aRoundingMode)
Round to 0 or more decimal places, using the given rounding style.

Parameters:
aNumberOfDecimals - must 0 or more.

round2

public Decimal round2(Decimal aInterval)
Round a number to the nearest multiple of the given interval. For example: Decimal amount = Decimal.from("1710.12"); amount.round2(0.05); // 1710.10 amount.round2(100); // 1700

Parameters:
aInterval - must be greater than zero

round2

public Decimal round2(long aInterval)

round2

public Decimal round2(double aInterval)

pow

public Decimal pow(int aPower)
Raise this number to an integral power; the power can be of either sign.

Special cases regarding 0:

Parameters:
aPower - is in the range -999,999,999..999,999,999, inclusive. (This reflects a restriction on the underlying BigDecimal.pow(int) method.

pow

public Decimal pow(double aPower)
This implementation uses Math.pow(double, double).


pow

public Decimal pow(Decimal aPower)
Raise this Decimal to a Decimal power.

This method calls either pow(int) or pow(double), according to the return value of isInteger().


doubleValue

public double doubleValue()
Required by Number.

Use of floating point data is highly discouraged. This method is provided only because it's required by Number.

Specified by:
doubleValue in class Number

floatValue

public float floatValue()
Required by Number.

Use of floating point data is highly discouraged. This method is provided only because it's required by Number.

Specified by:
floatValue in class Number

intValue

public int intValue()
Required by Number.

Specified by:
intValue in class Number

longValue

public long longValue()
Required by Number.

Specified by:
longValue in class Number

Version 4.10.0

Copyright Hirondelle Systems. Published October 19, 2013 - User Guide - All Docs.