java.math
Class BigDecimal

java.lang.Object
  java.lang.Number
      java.math.BigDecimal

All Implemented Interfaces:

Serializable, Comparable

public class BigDecimal
extends Number
implements Comparable

BigDecimal objects represent an arbitrary precisioned decimal Number. They contain values that cannot be changed. Thus, most operations on the BigDecimal object yield new instances of BigDecimal.

BigDecimal is respresented by an unscaled BigInteger value and an integer representing the scale of the object. The scale of the BigDecimal is the number of digits after the decimal point. Eg. 1.234 would have a scale of 3 and an unscaled value of 1234. Therefore, decimal representation of a BigDecimal is BigIntegerValue/10^scale.

See Also:

BigInteger, Serialized Form

Field Summary

static int	ROUND_CEILING Round to positive infinity constant.
static int	ROUND_DOWN Round down constant.
static int	ROUND_FLOOR Round to negative infinity constant.
static int	ROUND_HALF_DOWN Round constant for round to nearest neighbor unless both neighbors are equidistant, then round down.
static int	ROUND_HALF_EVEN Round constant for round to nearest neighbor unless both neighbors are equidistant, then round to the even neighbor.
static int	ROUND_HALF_UP Round constant for round to nearest neighbor unless both neighbors are equidistant, then round up.
static int	ROUND_UNNECESSARY Round constant that will cause an ArithmeticException if rounding is required.
static int	ROUND_UP Round up constant.

Constructor Summary

BigDecimal(BigInteger bval)
Constructs a BigDecimal with unscaled value initialized from a BigInteger.

BigDecimal(BigInteger bval, int sc)
Constructs a BigDecimal initialized from a BigInteger with the specified scale.

BigDecimal(double bval)
Constructs a BigDecimal with a double value as an arugment.

BigDecimal(String val)
Constructs a BigDecimal from a string, which can only contain digits of 0-9, a decimal point and a negative sign.

Method Summary

BigDecimal	abs() Answers the absolute value of this BigDecimal.
BigDecimal	add(BigDecimal bval) Answers the sum of the receiver and argument.
int	compareTo(BigDecimal bval) Compares the receiver BigDecimal and argument BigDecimal e.x 1.00 & 1.0 will return 0 in compareTo.
int	compareTo(Object o) Compares an receiver to the argument Object.
BigDecimal	divide(BigDecimal bval, int roundingMode) Answers the result of (this / bval).
BigDecimal	divide(BigDecimal bval, int bscale, int roundingMode) Answers the result of (this / bval) and whose scale is specified.
double	doubleValue() Converts this BigDecimal to a double.
boolean	equals(Object obj) Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
float	floatValue() Converts this BigDecimal to a float.If magnitude of the BigDecimal value is larger than what can be represented by a float, either Infinity or -Infinity is returned.
int	hashCode() Answers an integer hash code for the receiver.
int	intValue() Converts this BigDecimal to an int.
long	longValue() Converts this BigDecimal to a long.
BigDecimal	max(BigDecimal bval) Answers the max value between the receiver and this BigDecimal.
BigDecimal	min(BigDecimal bval) Answers the min value between the receiver and argument.
BigDecimal	movePointLeft(int n) Moves the decimal point of this BigDecimal n places to the left.
BigDecimal	movePointRight(int n) Moves the decimal point of this BigDecimal n places to the right.
BigDecimal	multiply(BigDecimal bval) Answers the multiplication result of the receiver and argument.
BigDecimal	negate() Negates this BigDecimal value.
int	scale() Returns the scale of this BigDecimal.
BigDecimal	setScale(int newScale) Sets the scale of this BigDecimal.
BigDecimal	setScale(int newScale, int roundingMode) Sets the scale of this BigDecimal.
int	signum() Answers the signum function of this instance.
BigDecimal	subtract(BigDecimal bval) Answers the subtract result of the receiver and argument.
BigInteger	toBigInteger() Converts this to a BigInteger.
String	toString() Answers a string containing a concise, human-readable description of the receiver.
BigInteger	unscaledValue() Returns an unscaled value of this BigDecimal.
static BigDecimal	valueOf(long bval) Translate long value into a BigDecimal with scale of zero.
static BigDecimal	valueOf(long bval, int scale) Translate a long value into a BigDecimal specified by the scale.

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ROUND_UP

public static final int ROUND_UP

Round up constant.

See Also:

Constant Field Values

ROUND_DOWN

public static final int ROUND_DOWN

Round down constant.

See Also:

Constant Field Values

ROUND_CEILING

public static final int ROUND_CEILING

Round to positive infinity constant.

See Also:

Constant Field Values

ROUND_FLOOR

public static final int ROUND_FLOOR

Round to negative infinity constant.

See Also:

Constant Field Values

ROUND_HALF_UP

public static final int ROUND_HALF_UP

Round constant for round to nearest neighbor unless both neighbors are equidistant, then round up.

See Also:

Constant Field Values

ROUND_HALF_DOWN

public static final int ROUND_HALF_DOWN

Round constant for round to nearest neighbor unless both neighbors are equidistant, then round down.

See Also:

Constant Field Values

ROUND_HALF_EVEN

public static final int ROUND_HALF_EVEN

Round constant for round to nearest neighbor unless both neighbors are equidistant, then round to the even neighbor.

See Also:

Constant Field Values

ROUND_UNNECESSARY

public static final int ROUND_UNNECESSARY

Round constant that will cause an ArithmeticException if rounding is required.

See Also:

Constant Field Values

Constructor Detail

BigDecimal

public BigDecimal(BigInteger bval)

Constructs a BigDecimal with unscaled value initialized from a BigInteger.

Parameters:

bval - the BigInteger value to convert to a BigDecimal

BigDecimal

public BigDecimal(BigInteger bval,
                  int sc)

Constructs a BigDecimal initialized from a BigInteger with the specified scale.

Parameters:

bval - the BigInteger value to convert to a BigDecimal

sc - the scale used for the result

BigDecimal

public BigDecimal(double bval)

Constructs a BigDecimal with a double value as an arugment.

Parameters:

bval - the double value to convert to a BigDecimal

Throws:

NumberFormatException - If the is Infinity, Negative Infinity or NaN.

BigDecimal

public BigDecimal(String val)

Constructs a BigDecimal from a string, which can only contain digits of 0-9, a decimal point and a negative sign.

Parameters:

val - the String value to convert to a BigDecimal

Throws:

NumberFormatException - If the argument contained characters other than digits.

Method Detail

abs

public BigDecimal abs()

Answers the absolute value of this BigDecimal.

Returns:

BigDecimal absolute value of the receiver.

add

public BigDecimal add(BigDecimal bval)

Answers the sum of the receiver and argument.

Parameters:

bval - the BigDecimal to add

Returns:

BigDecimal The sum of adding two BigDecimal.

compareTo

public int compareTo(Object o)

Compares an receiver to the argument Object.

Specified by:

compareTo in interface Comparable

Parameters:

o - the Object to compare

Returns:

int 0 if equal; positive if this > o; negative if this < o

Throws:

ClassCastException - if the argument is not of type BigDecimal

compareTo

public int compareTo(BigDecimal bval)

Compares the receiver BigDecimal and argument BigDecimal e.x 1.00 & 1.0 will return 0 in compareTo.

Parameters:

bval - the BigDecimal to compare

Returns:

int 0 if equal; positive if this > o; negative if this < o

divide

public BigDecimal divide(BigDecimal bval,
                         int roundingMode)

Answers the result of (this / bval).

Parameters:

bval - the value used to divide the receiver

roundingMode - the rounding constant

Returns:

BigDecimal result of this/val.

divide

public BigDecimal divide(BigDecimal bval,
                         int bscale,
                         int roundingMode)

Answers the result of (this / bval) and whose scale is specified.

Parameters:

bval - the value used to divide the receiver

bscale - the scale used for the result

roundingMode - the rounding constant

Returns:

BigDecimal result of this/val.

Throws:

ArithmeticException - division by zero.

IllegalArgumentException - roundingMode is not valid.

doubleValue

public double doubleValue()

Converts this BigDecimal to a double. If magnitude of the BigDecimal value is larger than what can be represented by a double, either Infinity or -Infinity is returned.

Specified by:

doubleValue in class Number

Returns:

double the value of the receiver.

equals

public boolean equals(Object obj)

Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison. The implementation in Object answers true only if the argument is the exact same object as the receiver (==).

Overrides:

equals in class Object

Parameters:

o - Object the object to compare with this object.

Returns:

boolean true if the object is the same as this object false if it is different from this object.

See Also:

hashCode

floatValue

public float floatValue()

Converts this BigDecimal to a float.If magnitude of the BigDecimal value is larger than what can be represented by a float, either Infinity or -Infinity is returned.

Specified by:

floatValue in class Number

Returns:

float the value of the receiver.

hashCode

public int hashCode()

Answers an integer hash code for the receiver. Any two objects which answer true when passed to .equals must answer the same value for this method.

Overrides:

hashCode in class Object

Returns:

int the receiver's hash.

See Also:

equals(Object)

intValue

public int intValue()

Converts this BigDecimal to an int.

Specified by:

intValue in class Number

Returns:

int the value of the receiver.

longValue

public long longValue()

Converts this BigDecimal to a long.

Specified by:

longValue in class Number

Returns:

long long representation of the receiver.

max

public BigDecimal max(BigDecimal bval)

Answers the max value between the receiver and this BigDecimal.

Parameters:

bval - the value used to compare

Returns:

BigDecimal max BigDecimal.

min

public BigDecimal min(BigDecimal bval)

Answers the min value between the receiver and argument.

Parameters:

bval - the value used to compare

Returns:

BigDecimal max BigDecimal.

movePointLeft

public BigDecimal movePointLeft(int n)

Moves the decimal point of this BigDecimal n places to the left.

Parameters:

n - the number of places to move the decimal point

Returns:

BigDecimal new BigDecimal with decimal moved n places to the left.

movePointRight

public BigDecimal movePointRight(int n)

Moves the decimal point of this BigDecimal n places to the right.

Parameters:

n - the number of places to move the decimal point

Returns:

BigDecimal new BigDecimal with decimal moved n places to the right.

multiply

public BigDecimal multiply(BigDecimal bval)

Answers the multiplication result of the receiver and argument.

Parameters:

bval - the value to multiply with the receiver

Returns:

BigDecimal result of multiplying two bigDecimals.

negate

public BigDecimal negate()

Negates this BigDecimal value.

Returns:

BigDecimal new BigDecimal with value negated.

scale

public int scale()

Returns the scale of this BigDecimal.

Returns:

int scale value.

setScale

public BigDecimal setScale(int newScale)

Sets the scale of this BigDecimal.

Parameters:

newScale - the scale used for the result

Returns:

BigDecimal a BigDecimal with the same value, but specified scale.

setScale

public BigDecimal setScale(int newScale,
                           int roundingMode)

Sets the scale of this BigDecimal. The unscaled value is determined by the rounding Mode

Parameters:

newScale - the scale used for the result

roundingMode - the rounding constant

Returns:

BigDecimal a BigDecimal with the same value, but specified cale.

Throws:

ArithmeticException - rounding mode must be specified if lose of precision due to setting scale.

IllegalArgumentException - invalid rounding mode

signum

public int signum()

Answers the signum function of this instance.

Returns:

int -1, 0, or 1 if the receiver is negative, zero, or positive.

subtract

public BigDecimal subtract(BigDecimal bval)

Answers the subtract result of the receiver and argument.

Parameters:

bval - the value to subtract from the receiver

Returns:

BigDecimal The result of adding two BigDecimal.

toBigInteger

public BigInteger toBigInteger()

Converts this to a BigInteger.

Returns:

BigInteger BigDecimal equivalent of bigInteger.

toString

public String toString()

Answers a string containing a concise, human-readable description of the receiver.

Overrides:

toString in class Object

Returns:

String a printable representation for the receiver.

unscaledValue

public BigInteger unscaledValue()

Returns an unscaled value of this BigDecimal.

Returns:

BigInteger The unscaled value.

valueOf

public static BigDecimal valueOf(long bval)

Translate long value into a BigDecimal with scale of zero.

Parameters:

bval - the long value to convert to a BigDecimal

Returns:

BigDecimal BigDecimal equivalence of a long value.

valueOf

public static BigDecimal valueOf(long bval,
                                 int scale)

Translate a long value into a BigDecimal specified by the scale.

Parameters:

bval - the long value to convert to a BigDecimal

scale - the scale of the result

Returns:

BigDecimal BigDecimal equivalence of a long value.

Throws:

NumberFormatException - the scale value is < 0;