Overview  Package   Class  Deprecated  Index  Help 
ArciMath BigDecimal v2.05
now with BigDecimalFormat
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

be.arci.math
Class BigDecimal

java.lang.Object
  |
  +--java.lang.Number
        |
        +--be.arci.math.BigDecimal
All Implemented Interfaces:
java.lang.Comparable, java.io.Serializable
public class BigDecimal
extends java.lang.Number
implements java.io.Serializable, java.lang.Comparable

The ArciMath BigDecimal class contains immutable arbitrary-precision signed decimal numbers supporting operations for both fixed and floating point arithmetic, comparison, scale manipulation, comparison, hashing, and format conversion. Different forms of notation are provided, to know plain notation (without exponent), and scientific (where one digit is shown before the decimal point) and engineering (where the power of ten is a multiple of three) exponential notations.

The floating point arithmetic provided by this class is defined by the ANSI X3.274-1996 standard (American National Standard for Information Technology – Programming Language REXX, X3.274-1996, American National Standards Institute, New York, 1996.), and is also documented by IBM in a document called decimal.pdf that can be found at http://www2.hursley.ibm.com/decimal (This URL may change!). In this implementation, the maximum precision of a number is 'limited' to 999.999.999 (10E+9 - 1) digits (this gigantic range is the reason why we have not included MAX_VALUE and MIN_VALUE fields), and the exponent of a number must fall within the range -1.000.000.000 (-10E+9) < exponent < +1.000.000.000 (+10E+9). Out-of-range results are detected and throw exceptions.

Integers and fixed-scale numbers are a proper subset of all numbers. Conversions to and from a different class are not necessary in order to carry out integer and currency calculations.

The ArciMath BigDecimal class gives it's user complete control over rounding behavior, forcing the user to explicitly specify a rounding mode for operations capable of discarding precision (such as divide and pow), and allowing to specify a rounding mode elsewhere. Eight rounding modes are provided for this purpose.

Two types of operations are provided for manipulating the scale of an ArciMath BigDecimal: scaling/rounding operations and decimal point motion operations. Scaling/rounding operations (SetScale and plus) return an ArciMath BigDecimal whose value is approximately (or exactly) equal to that of the ArciMath BigDecimal operated on operand, but whose scale is the specified value; that is, they increase or decrease the precision of the number with minimal effect on its value.
Decimal point motion operations (movePointLeft and movePointRight) return an ArciMath BigDecimal created from the operand by moving the decimal point a specified distance in the specified direction; that is, they change a number's value without affecting its precision. As an example you might express a ArciMath BigDecimal number bd in millions with the operation bd.movePointLeft(6).

As the numbers are decimal, there is an exact correspondence between an instance of a BigDecimal object and its String representation in decimal digits; the BigDecimal class provides direct conversions to and from String and character array (char[]) objects and from ASCII byte arrays (byte[]), as well as conversions to and from the Java primitive types, java.math.BigInteger, and java.math.BigDecimal. As conversion to integer types is inherently inexact, ArciMath BigDecimal has exact variants of the conversion function, that throw an exception if either the ArciMath BigDecimal number has a non-zero decimal scale, or is too large (in absolute value) to express in the desired integer type (the latter case of course applying to primitive integer types only, not to conversion to BigInteger). Exactness of conversion from the decimal floating point type ArciMath BigDecimal to the binary floating point types double and float can however not be enforced by any means, as most decimal numbers cannot be expressed as binary numbers.

For the sake of brevity and clarity, pseudo-code is used throughout the descriptions of ArciMath BigDecimal methods. The pseudo-code expression (f + g) is shorthand for "an ArciMath BigDecimal whose value is that of the ArciMath BigDecimal f plus that of the ArciMath BigDecimal g." The pseudo-code expression (f == g) is shorthand for "true if and only if the ArciMath BigDecimal f represents the same value as the the ArciMath BigDecimal g." Other pseudo-code expressions are interpreted similarly. In the descriptions of constructors and methods in this documentation, the value of a BigDecimal number object is shown as the result of invoking the toString() method on that object.

The internal representation of a decimal number is neither defined nor exposed, and is not permitted to affect the result of any operation. For the interested however we can give away that ArciMath BigDecimal internally uses a modified BCD (Binary Coded Decimal) scheme, that codes 2 decimal digits per byte, with 4 BCD limbs packed in an int[] for moving around fast. The evaluation version uses one BCD limb less per int, so as to offer exactly the same functionality, value range and precision as the production version, but at a higher memory consumption and a reduced speed (depending on the operator method and the length of the number, the speed difference can vary from 10% to 70%).

It may also interest you that, as this class is meant to be a plugin replacement for java.math.BigDecimal, in no place the code of this class delegates to methods of either java.math.BigDecimal or java.math.BigInteger, except in the constructors from either one of the java.math classes and the methods converting to them.

Serialization

Because numbers can be highly sensitive to even a single changed bit, ArciMath BigDecimal offers protection of your data during persistent storage or transmission through Java's serialization mechanism. When serializing, ArciMath BigDecimal stores a double CRC checking code into the serialized object. When de-serializing, this CRC coding is checked, and other validity checks are performed. For higher datastream integrity you might however still want to implement a more complete CRC or other integrity check on top of Java's serialization mechanism. Also note that BigDecimal objects stored by the evaluation version of ArciMath BigDecimal cannot be de-serialized by the production version, and vice-versa.

Operator methods

Operations on BigDecimal numbers are performed within a context represented by a MathContext object. MathContext properties are the precision in digits, the form of notation of the numbers, the rounding mode, and, because as a general rule operands are rounded before operating on them, protection against loss of digits during this rounding. Methods that implement the standard arithmetic operators for BigDecimal objects can take a MathContext parameter and are known as operator methods. Default settings are provided by the constant MathContext.DEFAULT (digits=9, form=SCIENTIFIC, lostDigits=false, roundingMode=ROUND_HALF_UP), and allow to perform general-purpose floating point arithmetic to nine digits of precision. The MathContext parameter must not be null, but each operator method also has a version with signature that does not take a MathContext parameter. For this version of each method, the context settings used are digits=0, form=PLAIN, lostDigits=false, roundingMode=ROUND_HALF_UP; these settings perform fixed point arithmetic with unlimited precision, as defined for the original java.math.BigDecimal class in Java 1.1 and Java 1.2.

For monadic operators, only the optional MathContext parameter is present; the operation acts upon the current ArciMath BigDecimal object.

For dyadic operators, a BigDecimal parameter is always present, which must not be null. The operation acts with the current ArciMath BigDecimal object as left-hand operand and the BigDecimal parameter as right-hand operand.

For example, dividing two BigDecimal objects referred to by the names bdDividend and bdDivisor could be written as any of: 

 bdDividend.divide(bdDivisor)
 bdDividend.divide(bdDivisor, MathContext.DEFAULT)
 bdDividend.divide(bdDivisor, myContext)
(where myContext is a MathContext object), which would return a BigDecimal object whose value is the quotient bdDividend / bdDivisor performed within the appropriate context.

When a BigDecimal operator method is used, a set of rules define what the result will be (and, by implication, how the result would be represented as a character string). These rules are defined in IBM's BigDecimal arithmetic documentation (see the URL above), but in summary:

The names of methods in this class follow the conventions established by java.math.BigDecimal, java.math.BigInteger, and java.lang.Number in Java 1.1 and Java 1.2.

Note: care should be exercised if ArciMath BigDecimals are to be used as keys in a SortedMap or elements in a SortedSet, as ArciMath BigDecimal's natural ordering is inconsistent with equals; this behaviour is compatible with java.math.BigDecimal behavoir, whose natural ordering equates BigDecimals with equal values and different precisions (such as "4.0" and "4.00"). See Comparable, SortedMap or SortedSet for more information.

See Also:
MathContext, Serialized Form

Field Summary
static java.lang.String copy
          Copyright notice for ArciMath BigDecimal; this String also can serve to distinguish the evaluation version and the producion version of ArciMath BigDecimal.
protected static int iRADIX
          The radix of our BCD coding after AAD (ASCII adjust for division); this value is 100.
static BigDecimal ONE
          The BigDecimal constant "1".
static int ROUND_CEILING
          Rounding mode to round towards positive infinity.
static int ROUND_DOWN
          Rounding mode to round towards zero.
static int ROUND_FLOOR
          Rounding mode to round towards negative infinity.
static int ROUND_HALF_DOWN
          Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
static int ROUND_HALF_EVEN
          Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.
static int ROUND_HALF_UP
          Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
static int ROUND_UNNECESSARY
          Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary.
static int ROUND_UP
          Rounding mode to round away from zero.
static BigDecimal TEN
          The BigDecimal constant "10".
static BigDecimal TWO
          The BigDecimal constant "2".
static BigDecimal ZERO
          The BigDecimal constant "0".
 
Constructor Summary
BigDecimal(BigDecimal bd)
          Construct a copy of the BigDecimal argument.
BigDecimal(java.math.BigDecimal bd)
          Constructs a be.arci.math.BigDecimal object from a java.math.BigDecimal as though the parameter had been represented as a String (using its toString() method) and the be.arci.math.BigDecimal(java.lang.String) constructor had then been used.
BigDecimal(java.math.BigInteger bi)
          Constructs a BigDecimal which is the exact decimal representation of the java.math.BigInteger, with a scale of zero.
BigDecimal(java.math.BigInteger bi, int iScale)
          Translates a java.math.BigInteger unscaled value and an int scale into a BigDecimal.
BigDecimal(byte[] abAsciiDigits)
          Convenience constructor for locales where the decimal separator is the '.' character.
BigDecimal(byte[] abAsciiDigits, char cDecimalSeparator)
          Constructs a BigDecimal object from an array of bytes.
BigDecimal(byte[] abAsciiDigits, int iStart, int iLength)
          Convenience constructor for locales where the decimal separator is the '.' character.
BigDecimal(byte[] abAsciiDigits, int iStart, int iLength, char cDecimalSeparator)
          Constructs a BigDecimal object from a subarray of bytes.
BigDecimal(char[] ac)
          Convenience constructor for locales where the decimal separator is the '.' character.
BigDecimal(char[] ac, char cDecimalSeparator)
          Constructs a BigDecimal object from an array of characters.
BigDecimal(char[] ac, int iStart, int iLength)
          Convenience constructor for locales where the decimal separator is the '.' character.
BigDecimal(char[] ac, int iStart, int iLength, char cDecimalSeparator)
          Constructs a BigDecimal object from a subarray of characters.
BigDecimal(double d)
          Deprecated.  
BigDecimal(int i)
          Fast constructor for wrapping an int value into a BigDecimal object.
BigDecimal(long l)
          Fast constructor for wrapping a long value into a BigDecimal object.
BigDecimal(java.lang.String s)
          Convenience constructor for locales where the decimal separator is the '.' character.
BigDecimal(java.lang.String s, char cDecimalSeparator)
          Constructs a BigDecimal object from a String, which must represent a valid number, as described formally in IBM's specification referred to above.
 
Method Summary
 BigDecimal abs()
          Implements the absolute value operator, and returns a positive BigDecimal value equal in magnitude to this value.
 BigDecimal abs(MathContext mc)
          Implements the absolute value operator, performed within the mathematical context mc, and returns a positive BigDecimal value equal in magnitude to this value (apart from rounding specified by the MathContext).
 BigDecimal add(BigDecimal bd)
          Implements the addition operator (+), using fixed point arithmetic, and returns a BigDecimal whose scale is max(this.scale(), bd.scale()).
 BigDecimal add(BigDecimal bd, MathContext mc)
          Implements the addition operator (+), within the context specified by mc.
 byte byteValueExact()
          Converts this BigDecimal to a Java byte value (an 8-bit signed integer); if the BigDecimal has a non-zero decimal part or is out of range for a Java byte value then an ArithmeticException is thrown.
 int compareTo(BigDecimal bd)
          Performs numerical comparison of this BigDecimal with the specified BigDecimal, using unlimited precision.
 int compareTo(BigDecimal bd, MathContext mc)
          Performs numerical comparison of this BigDecimal with the specified BigDecimal, within the context specified by mc.
 int compareTo(java.lang.Object o)
          Performs numerical comparison of this BigDecimal with the specified Object.
 BigDecimal divide(BigDecimal bd)
          Implements the division (/) operator, using fixed point arithmetic, and returns a BigDecimal quotient whose scale will be the same as the scale of this BigDecimal (the dividend) if this were formatted without exponential notation.
 BigDecimal divide(BigDecimal bd, int roundingMode)
          Implements the division (/) operator, using fixed point arithmetic and a rounding mode, and returns a BigDecimal quotient whose scale will be the same as the scale of this BigDecimal (the dividend) if this were formatted without exponential notation.
 BigDecimal divide(BigDecimal bd, int iScale, int roundingMode)
          Implements the division (/) operator, using fixed point arithmetic and a rounding mode, and returns a BigDecimal quotient whose scale is as specified.
 BigDecimal divide(BigDecimal bd, MathContext mc)
          Implements the division (/) operator, within the context specified by mc.
 BigDecimal[] divideAndRemainder(BigDecimal bd)
          Implements the integer division (/) and remainder (%) operators, using fixed point arithmetic.
 BigDecimal[] divideAndRemainder(BigDecimal bd, MathContext mc)
          Implements the integer division (/) and remainder (%) operators, within the context specified by mc.
 BigDecimal divideInteger(BigDecimal bd)
          Implements the integer division (/) operator, using fixed point arithmetic.
 BigDecimal divideInteger(BigDecimal bd, MathContext mc)
          Implements the integer division (/) operator, within the context specified by mc.
 double doubleValue()
          Converts this BigDecimal to a Java double value.
 boolean equals(java.lang.Object o)
          Compares this BigDecimal with the specified Object for equality.
 float floatValue()
          Converts this BigDecimal to a Java float value.
 java.lang.String format(int iIntDigits, int iDecDigits)
          Modifies the String representation of this BigDecimal according to a set of formatting parameters, without using exponential notation.
 java.lang.String format(int iIntDigits, int iDecDigits, int iExpDigits, int iMaxIntDigits, int iNot, int roundingMode)
          Modifies the String representation of this BigDecimal according to a set of layout parameters, and allowing exponential notation.
 int getDigits()
          Returns the count of decimal digits in the significand, with a minimum of 1 digit for the BigDecimal ZERO.
 int getExponent()
          Returns the exponent of this number if it would be expressed in scientific notation (0 <= base number < 1).
 int hashCode()
          Returns the hashcode for this BigDecimal.
 int intValue()
          Converts this BigDecimal to a Java int value.
 int intValueExact()
          Converts this BigDecimal to a Java int value; if the BigDecimal has a non-zero decimal part or is out of the possible range for a Java int (32-bit signed integer) result then an ArithmeticException is thrown.
 boolean isByteValue()
          Returns true if a call to byteValueExact() will return succesfully (without throwing an ArithmeticException).
 boolean isIntValue()
          Returns true if a call to intValueExact() will return succesfully (without throwing an ArithmeticException).
 boolean isLongValue()
          Returns true if a call to longValueExact() will return succesfully (without throwing an ArithmeticException).
 boolean isShortValue()
          Returns true if a call to shortValueExact() will return succesfully (without throwing an ArithmeticException).
 long longValue()
          Converts this BigDecimal to a Java long value.
 long longValueExact()
          Converts this BigDecimal to a Java long value; if the BigDecimal has a non-zero decimal part or is out of the possible range for a Java long (64-bit signed integer) then an ArithmeticException is thrown.
 BigDecimal max(BigDecimal bd)
          Returns the maximum of this BigDecimal and bd.
 BigDecimal max(BigDecimal bd, MathContext mc)
          Returns a BigDecimal whose value is the maximum of this and bd, within the context specified by mc.
 BigDecimal min(BigDecimal bd)
          Returns the minimum of this BigDecimal and bd.
 BigDecimal min(BigDecimal bd, MathContext mc)
          Returns a BigDecimal whose value is the minimum of this and bd, within the context specified by mc.
 BigDecimal movePointLeft(int n)
          Returns a BigDecimal which is equivalent to this one with the decimal point moved n places to the left.
 BigDecimal movePointRight(int n)
          Returns a BigDecimal which is equivalent to this one with the decimal point moved n places to the right.
 BigDecimal multiply(BigDecimal bd)
          Implements the multiplication (*) operator, using fixed point arithmetic, and returns a BigDecimal product with scale equal to the sum of the scales of the operands, if they were formatted without exponential notation.
 BigDecimal multiply(BigDecimal bd, MathContext mc)
          Implements the multiplication (*) operator, within the context specified by mc.
 BigDecimal negate()
          Implements the negation operator (unary -), using fixed point arithmetic, and returns a BigDecimal whose value is (-this), and whose scale is this.scale().
 BigDecimal negate(MathContext mc)
          Implements the negation operator (unary -), within the context specified by mc.
 BigDecimal normalize()
          Normalizes this BigDecimal number by removing all trailing zero digits from it's magnitude and adjusting it's exponent accordingly.
 BigDecimal plus()
          Implements the plus operator (unary +), using fixed point arithmetic, and returns a BigDecimal whose value is (+this), and whose scale is this.scale().
 BigDecimal plus(MathContext mc)
          Implements the plus operator (unary +), within the context specified by mc; this method is useful for rounding or otherwise applying a context to a decimal value.
 BigDecimal pow(BigDecimal bd)
          Implements the exponentiation operator, using fixed point arithmetic.
 BigDecimal pow(BigDecimal bd, MathContext mc)
          Implements the exponentiation operator, within the context specified by mc.
 BigDecimal pow(int iPower)
          Implements the exponentiation operator, using fixed point arithmetic.
 BigDecimal pow(int iPower, MathContext mc)
          Implements the exponentiation operator, within the context specified by mc.
 BigDecimal remainder(BigDecimal bd)
          Implements the remainder (%) operator, using integer division and fixed point arithmetic.
 BigDecimal remainder(BigDecimal bd, MathContext mc)
          Implements the remainder (%) operator, using integer division and within the context specified by mc.
 BigDecimal round(MathContext mc)
          Rounds a BigDecimal value according to the MathContext argument.
 int scale()
          Returns the scale of this BigDecimal.
 BigDecimal setScale(int iScale)
          Returns a BigDecimal whose scale is the specified value, and whose value is numerically equal to this BigDecimal's.
 BigDecimal setScale(int iScale, int roundingMode)
          Returns a BigDecimal whose scale is the specified value, and whose unscaled value is determined by multiplying or dividing this BigDecimal's unscaled value by the appropriate power of ten to maintain its overall value.
 short shortValueExact()
          Converts this BigDecimal to a Java short value; if the BigDecimal has a non-zero decimal part or is out of the possible range for a Java short (16-bit signed integer) result then an ArithmeticException is thrown.
 int signum()
          Returns the sign of this BigDecimal as an int.
 BigDecimal subtract(BigDecimal bd)
          Implements the subtraction (-) operator, using fixed point arithmetic, and returns a BigDecimal difference whose scale is max(this.scale(), val.scale()).
 BigDecimal subtract(BigDecimal bd, MathContext mc)
          Implements the subtraction (-) operator, within the context specified by mc.
 java.math.BigDecimal toBigDecimal()
          Converts this BigDecimal to a java.math.BigDecimal object.
 java.math.BigInteger toBigInteger()
          Converts this BigDecimal to a java.math.BigInteger object.
 java.math.BigInteger toBigIntegerExact()
          Converts this BigDecimal to a java.math.BigInteger object; an exception is thrown if this BigDecimal has a non-zero decimal part.
 char[] toCharArray()
          Convenience method for locales using the '.' character as decimal separator.
 char[] toCharArray(char cDecimalSeparator)
          Returns the BigDecimal as a character array.
 java.lang.String toString()
          Convenience method for locales using the '.' character as decimal separator.
 java.lang.String toString(char cDecimalSeparator)
          Returns the string representation of this BigDecimal.
 java.math.BigInteger unscaledValue()
          Returns a java.math.BigInteger whose value is the unscaled value of this BigDecimal; that is, the number is expressed as a plain number, any decimal point is then removed (retaining the digits of any decimal part), and the result is then converted to a java.math.BigInteger.
static BigDecimal valueOf(double d)
          Translates a double to a BigDecimal.
static BigDecimal valueOf(long l)
          Translates a long value into a BigDecimal with a scale of zero.
static BigDecimal valueOf(long l, int iScale)
          Translates a long unscaled value and an int scale into a BigDecimal.
 
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

iRADIX

protected static final int iRADIX
The radix of our BCD coding after AAD (ASCII adjust for division); this value is 100.

copy

public static final java.lang.String copy
Copyright notice for ArciMath BigDecimal; this String also can serve to distinguish the evaluation version and the producion version of ArciMath BigDecimal. The String value for the production version starts with " PRODUCTION VERSION ", that for the evaluation version with " EVALUATION VERSION ".

ZERO

public static final BigDecimal ZERO
The BigDecimal constant "0".

ONE

public static final BigDecimal ONE
The BigDecimal constant "1".

TWO

public static final BigDecimal TWO
The BigDecimal constant "2".

Note: This constant is not in com.ibm.math.BigDecimal.

TEN

public static final BigDecimal TEN
The BigDecimal constant "10".

ROUND_UP

public static final int ROUND_UP
Rounding mode to round away from zero. Always increments the digit prior to a non-zero discarded fraction. Note that this rounding mode never decreases the magnitude of the calculated value. This and the other rounding mode constants are supplied in this class for backward compatibility with java.lang.BigDecimal, but they are more at home in the MathContext class.
See Also:
MathContext.ROUND_UP

ROUND_DOWN

public static final int ROUND_DOWN
Rounding mode to round towards zero. Never increments the digit prior to a discarded fraction (i.e., truncates). Note that this rounding mode never increases the magnitude of the calculated value.
See Also:
MathContext.ROUND_DOWN

ROUND_CEILING

public static final int ROUND_CEILING
Rounding mode to round towards positive infinity. If the BigDecimal is positive, behaves as for ROUND_UP; if negative, behaves as for ROUND_DOWN. Note that this rounding mode never decreases the calculated value.
See Also:
MathContext.ROUND_CEILING

ROUND_FLOOR

public static final int ROUND_FLOOR
Rounding mode to round towards negative infinity. If the BigDecimal is positive, behave as for ROUND_DOWN; if negative, behave as for ROUND_UP. Note that this rounding mode never increases the calculated value.
See Also:
MathContext.ROUND_FLOOR

ROUND_HALF_UP

public static final int ROUND_HALF_UP
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up. Behaves as for ROUND_UP if the discarded fraction is >= .5; otherwise, behaves as for ROUND_DOWN. Note that this is the rounding mode that most of us were taught in grade school.
See Also:
MathContext.ROUND_HALF_UP

ROUND_HALF_DOWN

public static final int ROUND_HALF_DOWN
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down. Behaves as for ROUND_UP if the discarded fraction is > .5; otherwise, behaves as for ROUND_DOWN.
See Also:
MathContext.ROUND_HALF_DOWN

ROUND_HALF_EVEN

public static final int ROUND_HALF_EVEN
Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor. Behaves as for ROUND_HALF_UP if the digit to the left of the discarded fraction is odd; behaves as for ROUND_HALF_DOWN if it's even. Note that this is the rounding mode that minimizes cumulative error when applied repeatedly over a sequence of calculations.
See Also:
MathContext.ROUND_HALF_EVEN

ROUND_UNNECESSARY

public static final int ROUND_UNNECESSARY
Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary. If this rounding mode is specified on an operation that yields an inexact result, an ArithmeticException is thrown.
See Also:
MathContext.ROUND_UNNECESSARY
Constructor Detail

BigDecimal

public BigDecimal(BigDecimal bd)
Construct a copy of the BigDecimal argument. When subclassing BigDecimal, this constructor is usefull to construct a new instance of the subclass based on the result of a BigDecimal operation.
Parameters:
bd - The number to be copied; must not be null

BigDecimal

public BigDecimal(int i)
Fast constructor for wrapping an int value into a BigDecimal object.

Constructs a BigDecimal which is the exact decimal representation of the 32-bit signed binary integer parameter. The BigDecimal will contain only decimal digits, prefixed with a leading minus sign if the parameter is negative. A leading zero will be present only if the parameter is zero.

Parameters:
i - The int value to be converted.

BigDecimal

public BigDecimal(long l)
Fast constructor for wrapping a long value into a BigDecimal object.

Constructs a BigDecimal which is the exact decimal representation of the 64-bit signed binary integer parameter. The BigDecimal will contain only decimal digits, prefixed with a leading minus sign if the parameter is negative. A leading zero will be present only if the parameter is zero.

Parameters:
l - The long value to be converted.

BigDecimal

public BigDecimal(double d)
Deprecated.  

Constructor for wrapping a double into a BigDecimal object. Constructs a BigDecimal which is an exact decimal representation of the 64-bit signed binary floating point parameter. The scale of the BigDecimal is the smallest value such that (val * 10scale) is an integer. If the parameter is infinite, or is not a number (NaN), a NumberFormatException is thrown. Also the sign of a double zero is not retained; BigDecimal zero has no sign ("0".signum == 0). Any other double value can be represented exactly as a BigDecimal value.

This constructor does not give the same result as converting the double value to a String using the Double.toString() method and then using the BigDecimal(java.lang.String) constructor; because the arithmetic in ArciMath is completely defined with the String representation of numbers, this constructor is deprecated, even though it is more accurate.

Recommendation: Use the static valueOf(double) method to construct a BigDecimal from a double if you expect it to have a String representation with the same value; use this constructor if you want to get the exact value of the binary double, or you need more speed than is possible by going via the String representation of the double.

Note: the results of this constructor can be somewhat unexpected. One might expect that new BigDecimal(0.1) is exactly "0.1", but it is actually "0.1000000000000000055511151231257827021181583404541015625". This is so because 0.1 cannot be represented exactly as a double (or, for that matter, as a binary fraction of any finite length). Thus, the double value -.1 that seems to be passed in to the constructor is actually the value 0.1000000000000000055511151231257827021181583404541015625.

Stated otherwise, new BigDecimal(0.1) is not the same as new BigDecimal("0.1"). The (String) constructor indeed is perfectly predictable: new BigDecimal("0.1") is exactly equal to 0.1, as one would expect. Therefore, it is generally recommended that the (String) constructor be used in preference to this one.

Parameters:
d - double value to be converted to BigDecimal.
Throws:
java.lang.NumberFormatException - val is equal to Double.NEGATIVE_INFINITY, Double.POSITIVE_INFINITY, or Double.NaN.
See Also:
valueOf(double)

BigDecimal

public BigDecimal(java.math.BigDecimal bd)
Constructs a be.arci.math.BigDecimal object from a java.math.BigDecimal as though the parameter had been represented as a String (using its toString() method) and the be.arci.math.BigDecimal(java.lang.String) constructor had then been used. The parameter must not be null.
Parameters:
bd - The java.math.BigDecimal to be translated; this parameter must not be null.

BigDecimal

public BigDecimal(java.math.BigInteger bi)
Constructs a BigDecimal which is the exact decimal representation of the java.math.BigInteger, with a scale of zero. The value of the BigDecimal is the same as the value of the BigInteger. The parameter must not be null.

The BigDecimal will contain only decimal digits, prefixed with a leading minus sign if the BigInteger is negative. A leading zero will be present only if the BigInteger is zero.

Parameters:
bi - BigInteger value to be converted to BigDecimal; this parameter must not be null.

BigDecimal

public BigDecimal(java.math.BigInteger bi,
                  int iScale)
Translates a java.math.BigInteger unscaled value and an int scale into a BigDecimal. The value of the BigDecimal is (bi / 10iScale).

The BigDecimal will contain only decimal digits, (with an embedded decimal point followed by scale decimal digits if the scale is positive), prefixed with a leading minus sign if the BigInteger is negative. A leading zero will be present only if the BigInteger is zero.

Parameters:
bi - unscaled value of the BigDecimal; this parameter must not be null.
iScale - the positive scale of the BigDecimal (the position at which a decimal point must be placed in the BigInteger parameter, measured in decimal digits from the right).
Throws:
java.lang.NumberFormatException - scale is negative

BigDecimal

public BigDecimal(java.lang.String s)
Convenience constructor for locales where the decimal separator is the '.' character.
Parameters:
s - String representation of BigDecimal.
Throws:
java.lang.NumberFormatException - s is not a valid representation of a BigDecimal.
See Also:
BigDecimal(String s, char cDecimalSeparator)

BigDecimal

public BigDecimal(java.lang.String s,
                  char cDecimalSeparator)
Constructs a BigDecimal object from a String, which must represent a valid number, as described formally in IBM's specification referred to above.

In summary, the String representation consists of an optional minus sign followed by a sequence of zero or more decimal digits, optionally followed by a fraction, and, in addition to what java.math.BigDecimal accepts as numbers; this number may be followed by an exponent in the usual notation, to know an 'E' or 'e' followed by a signed or unsigned integer (the exponent proper) that indicates how the decimal point will be shifted (i.e. by multiplying the number by the power of ten indicated by the exponent). The fraction consists of of a decimal point followed by zero or more decimal digits. The String must contain at least one digit in the integer or fractional part. It follows conventional syntax, and may not contain any extraneous characters (whitespace or grouping characters, for example).

Some valid strings from which a BigDecimal might be constructed are: 

     "0"         // Zero
     "0.00"      // Zero (with 2 decimal places)
  "2318"         // A whole ('natural') number
  "2318."        // The same as 2318
   "-83"         // A signed whole number
    "99.95"      // Two decimal places
    "+0.012"     // Plus sign is allowed, but has no implications
      ".012"     // The same as 0.012
     "0.67E-3"   // Exponential notation for 0.00067
     "7e+5"      // Exponential notation for 700000, with lowercase 'e'
     "7E5"       // Exponential notation for 700000; note that the '+' in exponent is not obligatory
If the String uses exponential notation (that is, includes an e or an E), then the BigDecimal number will be expressed in SCIENTIFIC notation when rendered by toString() (where the power of ten is adjusted so there is a single non-zero digit to the left of the decimal point); in this case if the number is zero then it will be expressed as the single digit 0, and if non-zero it will have an exponent unless that exponent would be 0. The exponent both in the String constructed from and the String the BigDecimal would be rendered to by toString() is limited to the range -1000000000 (-10E9) < exponent < 1000000000 (10E9).
There is no way to construct a BigDecimal which has ENGINEERING notation when rendered by toString(). A sequence like BigDecimal bd = new BigDecimal("4e+9").plus(new MathContext(0, MathContext.ENGINEERING)); (or other operations with an 'engineering' MathContext) will result in a BigDecimal number with ENGINEERING notation.
If the String does not use exponential notation, then the BigDecimal number will be expressed in PLAIN notation when rendered by toString(). In this case the number zero will be expressed with as many decimal places as it is constructed with.
In all cases, the BigDecimal number retains the precision (number of decimal digits) of the String it was constructed from.

Any digits in the parameter must be decimal; that is, Character.digit(c, 10) (where c is the character in question) should not return -1.

Note: This constructor is not in com.ibm.math.BigDecimal.

Parameters:
s - String representation of BigDecimal.
cDecimalSeparator - the decimal separator used in s. The decimal separator for a locale can be retrieved from a java.text.DecimalFormatSymbols object for that locale.
Throws:
java.lang.NumberFormatException - s is not a valid representation of a BigDecimal.
Since:
2.02
See Also:
BigDecimal(String s), "Character.digit(char, int)", MathContext.PLAIN, MathContext.SCIENTIFIC, MathContext.ENGINEERING

BigDecimal

public BigDecimal(byte[] abAsciiDigits)
Convenience constructor for locales where the decimal separator is the '.' character.
Parameters:
abAsciiDigits - The byte[] array containing the number to be converted, in ASCII format (i.e. 0 represented by 0x30 or (byte)'0', 1 by 0x31 or (byte)'1', and soforth).
Throws:
java.lang.NumberFormatException - abAsciiDigits is not a valid representation of a BigDecimal.
See Also:
BigDecimal(byte[] abAsciiDigits, char cDecimalSeparator)

BigDecimal

public BigDecimal(byte[] abAsciiDigits,
                  char cDecimalSeparator)
Constructs a BigDecimal object from an array of bytes.

Constructs a BigDecimal as decscribed for the BigDecimal(java.lang.String) constructor, but using this constructor is faster if the String is available as an array of ASCII character bytes (e.g. when reading from a file).

Note: This constructor is not in com.ibm.math.BigDecimal.

Parameters:
abAsciiDigits - The byte[] array containing the number to be converted, in ASCII format (i.e. 0 represented by 0x30 or (byte)'0', 1 by 0x31 or (byte)'1', and soforth).
cDecimalSeparator - the decimal separator used in abAsciiDigits. The decimal separator for a locale can be retrieved from a java.text.DecimalFormatSymbols object for that locale.
Throws:
java.lang.NumberFormatException - abAsciiDigits is not a valid representation of a BigDecimal.
Since:
2.02
See Also:
BigDecimal(byte[] abAsciiDigits)

BigDecimal

public BigDecimal(byte[] abAsciiDigits,
                  int iStart,
                  int iLength)
Convenience constructor for locales where the decimal separator is the '.' character.
Parameters:
abAsciiDigits - The byte[] array containing the number to be converted, in ASCII format (i.e. 0 represented by 0x30 or (byte)'0', 1 by 0x31 or (byte)'1', and soforth).
iStart - The int offset into the array of the start of the number to be converted.
iLength - The int length of the number; the subarray indicated by iStart and iLength must be wholly contained within abAsciiDigits.
Throws:
java.lang.NumberFormatException - the subarray of abAsciiDigits is not a valid representation of a BigDecimal.
See Also:
BigDecimal(byte[] abAsciiDigits, int iStart, int iLength, char cDecimalSeparator)

BigDecimal

public BigDecimal(byte[] abAsciiDigits,
                  int iStart,
                  int iLength,
                  char cDecimalSeparator)
Constructs a BigDecimal object from a subarray of bytes.

Constructs a BigDecimal as decscribed for the BigDecimal(java.lang.String) constructor, but using this constructor is faster if the String is available as an array of ASCII character bytes (e.g. when reading from a file).

Note: This constructor is not in com.ibm.math.BigDecimal.

Parameters:
abAsciiDigits - The byte[] array containing the number to be converted, in ASCII format (i.e. 0 represented by 0x30 or (byte)'0', 1 by 0x31 or (byte)'1', and soforth), in a subarray.
iStart - The int offset into the array of the start of the number to be converted.
iLength - The int length of the number; the subarray indicated by iStart and iLength must be wholly contained within abAsciiDigits.
cDecimalSeparator - the decimal separator used in abAsciiDigits. The decimal separator for a locale can be retrieved from a java.text.DecimalFormatSymbols object for that locale.
Throws:
java.lang.NumberFormatException - the subarray of abAsciiDigits is not a valid representation of a BigDecimal.
Since:
2.02
See Also:
BigDecimal(byte[] abAsciiDigits, int iStart, int iLength)

BigDecimal

public BigDecimal(char[] ac)
Convenience constructor for locales where the decimal separator is the '.' character.
Parameters:
ac - The char[] array containing the number to be converted.
Throws:
java.lang.NumberFormatException - ac is not a valid representation of a BigDecimal.
See Also:
BigDecimal(char[] ac, char cDecimalSeparator)

BigDecimal

public BigDecimal(char[] ac,
                  char cDecimalSeparator)
Constructs a BigDecimal object from an array of characters.

Constructs a BigDecimal as decscribed for the BigDecimal(java.lang.String) constructor, but using this constructor is faster if the String is available in character array form.

Note: This constructor is not in com.ibm.math.BigDecimal.

Parameters:
ac - The char[] array containing the number to be converted.
cDecimalSeparator - the decimal separator used in ac. The decimal separator for a locale can be retrieved from a java.text.DecimalFormatSymbols object for that locale.
Throws:
java.lang.NumberFormatException - ac is not a valid representation of a BigDecimal.
Since:
2.02
See Also:
BigDecimal(char[] ac)

BigDecimal

public BigDecimal(char[] ac,
                  int iStart,
                  int iLength)
Convenience constructor for locales where the decimal separator is the '.' character.
Parameters:
ac - The char[] array containing the number to be converted in the specified subarray.
iStart - The int offset into the array of the start of the number to be converted.
iLength - The int length of the number in the array; the subarray indicated by iStart and iLength must be wholly contained within ac.
Throws:
java.lang.NumberFormatException - the subarray of ac is not a valid representation of a BigDecimal.
See Also:
BigDecimal(char[] ac, int iStart, int iLength, char cDecimalSeparator)

BigDecimal

public BigDecimal(char[] ac,
                  int iStart,
                  int iLength,
                  char cDecimalSeparator)
Constructs a BigDecimal object from a subarray of characters.

Constructs a BigDecimal as decscribed for the BigDecimal(java.lang.String) constructor, but using this constructor is faster if the String is available in character array form.

Note: This constructor is not in com.ibm.math.BigDecimal.

Parameters:
ac - The char[] array containing the number to be converted in the specified subarray.
iStart - The int offset into the array of the start of the number to be converted.
iLength - The int length of the number in the array; the subarray indicated by iStart and iLength must be wholly contained within ac.
cDecimalSeparator - the decimal separator used in ac. The decimal separator for a locale can be retrieved from a java.text.DecimalFormatSymbols object for that locale.
Throws:
java.lang.NumberFormatException - the subarray of ac is not a valid representation of a BigDecimal.
Since:
2.02
See Also:
BigDecimal(char[] ac, int iStart, int iLength)
Method Detail

abs

public BigDecimal abs()
Implements the absolute value operator, and returns a positive BigDecimal value equal in magnitude to this value.

java.math.BigDecimal compatibility signature, the same as abs(new MathContext(0, MathContext.PLAIN)).

Returns:
abs(this)

abs

public BigDecimal abs(MathContext mc)
Implements the absolute value operator, performed within the mathematical context mc, and returns a positive BigDecimal value equal in magnitude to this value (apart from rounding specified by the MathContext).

If the current object is zero or positive, then the result of invoking the plus(MathContext) method with the same parameter is returned. Otherwise, the result of invoking the negate(MathContext) method with the same parameter is returned.

Parameters:
mc - The MathContext; must not be null.
Returns:
abs(this)

add

public BigDecimal add(BigDecimal bd)
Implements the addition operator (+), using fixed point arithmetic, and returns a BigDecimal whose scale is max(this.scale(), bd.scale()).

java.math.BigDecimal compatibility signature, the same as add(bd, new MathContext(0, MathContext.PLAIN)).

Parameters:
bd - value to be added to this BigDecimal; must not be null.
Returns:
this + bd

add

public BigDecimal add(BigDecimal bd,
                      MathContext mc)
Implements the addition operator (+), within the context specified by mc.
Parameters:
bd - value to be added to this BigDecimal; must not be null.
mc - The MathContext arithmetic settings; must not be null.
Returns:
this + bd

byteValueExact

public byte byteValueExact()
                    throws java.lang.ArithmeticException
Converts this BigDecimal to a Java byte value (an 8-bit signed integer); if the BigDecimal has a non-zero decimal part or is out of range for a Java byte value then an ArithmeticException is thrown.

NOTE
The corresponding method byteValue() is inherited from java.lang.Number.

Returns:
A byte equal in value to this.
Throws:
java.lang.ArithmeticException - if this has a non-zero decimal part, or will not fit in a byte.

compareTo

public int compareTo(java.lang.Object o)
Performs numerical comparison of this BigDecimal with the specified Object. If the Object is a BigDecimal, this method behaves like compareTo(BigDecimal). Otherwise, it throws a ClassCastException, for BigDecimals are comparable only to other BigDecimals.

Note: This method signature implements the Comparable interface of Java 2; the compareTo(BigDecimal, MathContext) method should be used when a context is needed for the comparison.

Note: Even though this method signature implements the Comparable interface of Java 2, it will be present in JDK1.x versions of this class; the only difference being that these versions do not implement the java.lang.Comparable interface, as that isn't in JDK1.x.

Specified by:
compareTo in interface java.lang.Comparable
Parameters:
o - Object to which this BigDecimal is to be compared; must not be null.
Returns:
-1, 0 or +1 as this BigDecimal is numerically less than, equal to, or greater than o, which must be a BigDecimal.
Throws:
ClassCastException - o is not a BigDecimal.
See Also:
compareTo(be.arci.math.BigDecimal), Comparable

compareTo

public int compareTo(BigDecimal bd)
Performs numerical comparison of this BigDecimal with the specified BigDecimal, using unlimited precision.

java.math.BigDecimal compatibility signature, the same as compareTo(bd, new MathContext(0, MathContext.PLAIN)).

Note: A compareTo(Object) method is also provided for implementing the Comparable interface of Java 2.

Two BigDecimals that are equal in value but have a different scale (like 2.0 and 2.00) are considered equal by this method. This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=); we suggest performing these comparisons as: (x.compareTo(y) <op> 0), where <op> is one of the six comparison operators.

Parameters:
bd - BigDecimal to which this BigDecimal is to be compared; must not be null.
Returns:
-1, 0 or 1 as this BigDecimal is numerically less than, equal to, or greater than bd.

compareTo

public int compareTo(BigDecimal bd,
                     MathContext mc)
Performs numerical comparison of this BigDecimal with the specified BigDecimal, within the context specified by mc.

Note that, due to the possible re-scaling and rounding specified in mc, this method allows for 'inexact' comparison, as is so often requested for floating point values. Please let me know if you see a purpose for another form of 'inexact' comparison; I was thinking of something like compareWithinMargin(BigDecimal bdComparand, double percents),
which could return 0 ('equal value') if this * (1-percents) < bdComparand < this * (1+percents),
else +1 or -1 depending on this < or > bdComparand

Parameters:
bd - The BigDecimal for the right hand side of the comparison; must not be null.
mc - The MathContext arithmetic settings; must not be null.
Returns:
An int whose value is -1, 0, or 1 as this is numerically less than, equal to, or greater than bd.

divide

public BigDecimal divide(BigDecimal bd)
Implements the division (/) operator, using fixed point arithmetic, and returns a BigDecimal quotient whose scale will be the same as the scale of this BigDecimal (the dividend) if this were formatted without exponential notation.

java.math.BigDecimal compatibility signature, the same as divide(bd, new MathContext(0, MathContext.PLAIN)).

Parameters:
bd - The BigDecimal divisor; must not be null.
Returns:
A plain BigDecimal whose value is this / bd, using fixed point arithmetic.
Throws:
java.lang.ArithmeticException - bd is zero.

divide

public BigDecimal divide(BigDecimal bd,
                         int roundingMode)
Implements the division (/) operator, using fixed point arithmetic and a rounding mode, and returns a BigDecimal quotient whose scale will be the same as the scale of this BigDecimal (the dividend) if this were formatted without exponential notation. If rounding must be performed to generate a result with that scale, the specified rounding mode is applied.

java.math.BigDecimal compatibility signature, the same as divide(bd, new MathContext(0, MathContext.PLAIN, false, roundingMode)).

Parameters:
bd - The BigDecimal divisor; must not be null.
roundingMode - rounding mode to apply.
Returns:
this / bd
Throws:
java.lang.ArithmeticException - bd==0, or roundingMode==ROUND_UNNECESSARY and this.scale() is insufficient to represent the result of the division exactly.
java.lang.IllegalArgumentException - roundingMode does not represent a valid rounding mode.
See Also:
MathContext.ROUND_UP, MathContext.ROUND_DOWN, MathContext.ROUND_CEILING, MathContext.ROUND_FLOOR, MathContext.ROUND_HALF_UP, MathContext.ROUND_HALF_DOWN, MathContext.ROUND_HALF_EVEN, MathContext.ROUND_UNNECESSARY

divide

public BigDecimal divide(BigDecimal bd,
                         int iScale,
                         int roundingMode)
Implements the division (/) operator, using fixed point arithmetic and a rounding mode, and returns a BigDecimal quotient whose scale is as specified. If rounding must be performed to generate a result with the specified scale, the specified rounding mode is applied.

java.math.BigDecimal compatibility signature, has no equivalent with MathContext parameter.

Parameters:
bd - The BigDecimal divisor; must not be null.
iScale - scale of the BigDecimal quotient to be returned.
roundingMode - rounding mode to apply.
Returns:
this / bd
Throws:
java.lang.ArithmeticException - bd is zero, iScale is negative, or roundingMode==ROUND_UNNECESSARY and this BigDecimal's scale is insufficient to represent the result of the division exactly.
java.lang.IllegalArgumentException - roundingMode does not represent a valid rounding mode.
See Also:
MathContext.ROUND_UP, MathContext.ROUND_DOWN, MathContext.ROUND_CEILING, MathContext.ROUND_FLOOR, MathContext.ROUND_HALF_UP, MathContext.ROUND_HALF_DOWN, MathContext.ROUND_HALF_EVEN, MathContext.ROUND_UNNECESSARY

divide

public BigDecimal divide(BigDecimal bd,
                         MathContext mc)
Implements the division (/) operator, within the context specified by mc.
Parameters:
bd - The BigDecimal divisor; must not be null.
mc - The MathContext arithmetic settings; must not be null.
Returns:
this / bd.
Throws:
java.lang.ArithmeticException - if bd is zero.

divideAndRemainder

public BigDecimal[] divideAndRemainder(BigDecimal bd)
Implements the integer division (/) and remainder (%) operators, using fixed point arithmetic.

Note: This method is not in com.ibm.math.BigDecimal.

The same as divideAndRemainder(bd, new MathContext(0, MathContext.PLAIN)).

Parameters:
bd - The BigDecimal divisor; must not be null.
Returns:
an array of two BigDecimals: the integer quotient (this / bd) is at index [0], and the remainder (this % bd) is at index [1].
Throws:
java.lang.ArithmeticException - bd==0
See Also:
divideInteger(BigDecimal), remainder(BigDecimal)

divideAndRemainder

public BigDecimal[] divideAndRemainder(BigDecimal bd,
                                       MathContext mc)
Implements the integer division (/) and remainder (%) operators, within the context specified by mc.

Note: This method is not in com.ibm.math.BigDecimal.

Parameters:
bd - The BigDecimal divisor; must not be null.
mc - The MathContext arithmetic settings; must not be null.
Returns:
an array of two BigDecimals: the quotient (this / bd) is at index [0], and the remainder (this % bd) is at index [1].
Throws:
java.lang.ArithmeticException - bd==0
See Also:
divideInteger(BigDecimal,MathContext), remainder(BigDecimal,MathContext)

divideInteger

public BigDecimal divideInteger(BigDecimal bd)
Implements the integer division (/) operator, using fixed point arithmetic.

The same as divideInteger(bd, new MathContext(0, MathContext.PLAIN)).

Parameters:
bd - The BigDecimal divisor; must not be null.
Returns:
The integer part of the quotient this / bd.
Throws:
java.lang.ArithmeticException - if bd is zero.

divideInteger

public BigDecimal divideInteger(BigDecimal bd,
                                MathContext mc)
Implements the integer division (/) operator, within the context specified by mc.
Parameters:
bd - The BigDecimal divisor; must not be null.
mc - The MathContext arithmetic settings; must not be null.
Returns:
The integer part of the quotient this / bd.
Throws:
java.lang.ArithmeticException - if bd is zero or if the result will not fit in the number of digits specified for the context.

doubleValue

public double doubleValue()
Converts this BigDecimal to a Java double value. Similar to the double-to-float narrowing primitive conversion defined in The Java Language Specification: if this BigDecimal has too great a magnitude to represent as a double, it will be converted to DOUBLE.NEGATIVE_INFINITY or DOUBLE.POSITIVE_INFINITY as appropriate.

Note: There is not and cannot be a doubleValueExact() method like there is an intValueExact() etc.

Overrides:
doubleValue in class java.lang.Number
Returns:
this BigDecimal converted to a double.

equals

public boolean equals(java.lang.Object o)
Compares this BigDecimal with the specified Object for equality. Unlike compareTo, this method considers two BigDecimals equal only if their String representations are identical (they have the same characters in the same sequence). Thus for this method "2.0" is not equal to "2.00" nor to "20E-1". The compareTo() method should be used for numerical comparisons.
Overrides:
equals in class java.lang.Object
Parameters:
o - Object to which this BigDecimal is to be compared; null is never equal.
Returns:
true if and only if the specified Object is a BigDecimal that is exactly equal to this BigDecimal, false otherwise.
See Also:
compareTo(be.arci.math.BigDecimal)

floatValue

public float floatValue()
Converts this BigDecimal to a Java float value. Similar to the double-to-float narrowing primitive conversion defined in The Java Language Specification: if this BigDecimal has too great a magnitude to represent as a float, it will be converted to FLOAT.NEGATIVE_INFINITY or FLOAT.POSITIVE_INFINITY as appropriate.
Overrides:
floatValue in class java.lang.Number
Returns:
this BigDecimal converted to a float.

format

public java.lang.String format(int iIntDigits,
                               int iDecDigits)
Modifies the String representation of this BigDecimal according to a set of formatting parameters, without using exponential notation.

The same as format(iIntDigits, iDecDigits, -1, -1, MathContext.SCIENTIFIC, -1)

This method is provided as a primitive for use by more sophisticated classes, such as DecimalFormat, that can apply locale-sensitive editing of the result. The level of formatting that it provides is a necessary part of the BigDecimal class as it is sensitive to and must follow the calculation and rounding rules for BigDecimal arithmetic. However, if the function is provided elsewhere, it may be removed from this class.

The parameters iIntDigits and iDecDigits specify the number of characters to be used for representing the integer part and decimal part of the result respectively. If either parameter is -1 (which indicates the default action), the number of characters used will be exactly as many as are needed for that part.

iIntDigits, if not -1, must be a positive number (not 0); if it is larger than is needed to contain the integer part, that part is padded on the left with blanks to the requested length. If iIntDigits is not large enough to contain the integer part of the number (including the sign, for negative numbers) an exception is thrown.

iDecDigits, if not -1, must be a non-negative number; if it is not the same size as the decimal part of the number, the number will be rounded (or extended with zeros) to fit. If iDecDigits is 0, the number will be rounded to an integer and will have no decimal point. The rounding mode is MathContext.ROUND_HALF_UP.

Other rounding methods, and the use of exponential notation, can be selected by using format(int,int,int,int,int,int).

Parameters:
iIntDigits - The number of places before the decimal point, or -1 to use as many digits as needed.
iDecDigits - The number of places after the decimal point, or -1 to use as many digits as needed.
Returns:
A String representing this BigDecimal, formatted according to the specified parameters
Throws:
java.lang.ArithmeticException - if the number cannot be formatted as requested.
java.lang.IllegalArgumentException - if a parameter is out of range.
See Also:
toString(), toCharArray()

format

public java.lang.String format(int iIntDigits,
                               int iDecDigits,
                               int iExpDigits,
                               int iMaxIntDigits,
                               int iNot,
                               int roundingMode)
Modifies the String representation of this BigDecimal according to a set of layout parameters, and allowing exponential notation. A value of -1 for any parameter (except iNot) indicates that the default action or value for that parameter should be used.

This method is provided as a primitive for use by more sophisticated classes, such as DecimalFormat, that can apply locale-sensitive editing of the result. The level of formatting that it provides is a necessary part of the BigDecimal class as it is sensitive to and must follow the calculation and rounding rules for BigDecimal arithmetic. However, if the function is provided elsewhere, it may be removed from this class.

The two parameters iIntDigits and iDecDigits specify the number of characters to be used for the integer part and decimal part of the result respectively, as described for format(int,int). If either of these is -1, the number of characters used will be exactly as many as are needed for that part.

The parameters iExpDigits, iMaxIntDigits, and iNot control the use of exponential notation.
iExpDigits, if not -1, must be a positive number (not 0), and sets the number of digits after the sign of the exponent to be used for any exponent part; the requested space is always reserved for an exponent: if no exponent is needed (for example, if the exponent will be 0) then iExpDigits+2 blanks are appended to the result. If iExpDigits is not large enough to contain the exponent, an exception is thrown. The default action, when iExpDigits is -1, is to use as many digits as needed.

iMaxIntDigits, if not -1, sets the trigger point for use of exponential notation. If, before any rounding, the number of places needed before the decimal point exceeds iMaxIntDigits, or if the absolute value of the result is less than 0.000001 (10E-6), then exponential form will be used. If iMaxIntDigits is -1, exponential notation will never be used. If iMaxIntDigits is 0, exponential notation is always used unless the exponent would be 0.

iNot sets the form of exponential notation (if needed). It may be either MathContext.SCIENTIFIC or MathContext.ENGINEERING. If the engineering notation is requested, up to three digits (plus sign, if negative) may be needed for the integer part of the result (iIntDigits). Otherwise, only one digit (plus sign, if negative) is needed.

roundingMode, selects the rounding algorithm to be used, and must be one of the rounding mode constants of the MathContext class. The default (MathContext.ROUND_HALF_UP) may also be selected by using the value -1. The special value MathContext.ROUND_UNNECESSARY may be used to assert that the formatting discards no non-zero digits; if it does, an ArithmeticException is thrown.

Parameters:
iIntDigits - The number of places before the decimal point, or -1 to use -1 as many digits as needed.
iDecDigits - The number of places after the decimal point, or -1 to use as many digits as needed.
iExpDigits - The number of digits to use for any exponent, or -1 to use as many digits as needed.
iMaxIntDigits - The number of digits before the decimal point triggering the use of exponential notation; use 0 to force exponential notation, and use -1 to force plain notation (no exponential notation).
iNot - The form of exponential notation to be used (MathContext.SCIENTIFIC or MathContext.ENGINEERING).
roundingMode - The rounding mode to use. Use -1 for the default, MathContext.ROUND_HALF_UP.
Returns:
A String representing this BigDecimal, formatted according to the specified parameters
Throws:
java.lang.ArithmeticException - if the number cannot be formatted as requested.
java.lang.IllegalArgumentException - if a parameter is out of range.
See Also:
toString(), toCharArray()

getDigits

public int getDigits()
Returns the count of decimal digits in the significand, with a minimum of 1 digit for the BigDecimal ZERO.

Note: This method is not in com.ibm.math.BigDecimal.

getExponent

public int getExponent()
Returns the exponent of this number if it would be expressed in scientific notation (0 <= base number < 1). This is a good indication of the order of magnitude of this number. Note: This method is not in com.ibm.math.BigDecimal.

Examples:
"1"getExponent() returns 0 (1E+0)
"14154"getExponent() returns 4 (1.4154E+4)
"0.00000014154"getExponent() returns -7 (1.4154E-7)
"14.154E6"getExponent() returns 7 (1.4154E+7)

Returns:
the exponent of this number in scientific notation (0 <= base number < 1)
Since:
2.02
See Also:
scale(), getDigits()

hashCode

public int hashCode()
Returns the hashcode for this BigDecimal. Note that two BigDecimals that are numerically equal but differ in scale (like 2.0 and 2.00) will generally not have the same hash code; two BigDecimal objects are only guaranteed to produce the same hashcode if they are exactly equal, as defined by the method equals.
Overrides:
hashCode in class java.lang.Object
Returns:
hash code for this BigDecimal.
See Also:
equals(Object)

intValue

public int intValue()
Converts this BigDecimal to a Java int value. Standard narrowing primitive conversion as defined in The Java Language Specification for narrowing conversion of a floating-point number to an integral type is NOT followed. Rather the (non-standard) behaviour of java.math.BigDecimal is followed for backward compatibility: any fractional part of this BigDecimal will be discarded (the standard's term is round toward zero); but then if the resulting "BigInteger" is too big in absolute value to fit in an int (32-bit signed integer), leading bits are discarded or 'decapitated' and only the low-order 32 bits are returned (whereas the standard floating-point to integer value narrowing conversion would have required to return Integer.MAX_VALUE or Integer.MIN_VALUE).

To avoid unexpected errors when these conditions occur, use the intValueExact() method.

Overrides:
intValue in class java.lang.Number
Returns:
this BigDecimal converted to an int.

intValueExact

public int intValueExact()
                  throws java.lang.ArithmeticException
Converts this BigDecimal to a Java int value; if the BigDecimal has a non-zero decimal part or is out of the possible range for a Java int (32-bit signed integer) result then an ArithmeticException is thrown.
Returns:
An int equal in value to this.
Throws:
java.lang.ArithmeticException - if this has a non-zero decimal part, or will not fit in an int.

isByteValue

public boolean isByteValue()
Returns true if a call to byteValueExact() will return succesfully (without throwing an ArithmeticException).

Note: This method is not in com.ibm.math.BigDecimal.

isIntValue

public boolean isIntValue()
Returns true if a call to intValueExact() will return succesfully (without throwing an ArithmeticException).

Note: This method is not in com.ibm.math.BigDecimal.

isLongValue

public boolean isLongValue()
Returns true if a call to longValueExact() will return succesfully (without throwing an ArithmeticException).

Note: This method is not in com.ibm.math.BigDecimal.

isShortValue

public boolean isShortValue()
Returns true if a call to shortValueExact() will return succesfully (without throwing an ArithmeticException).

Note: This method is not in com.ibm.math.BigDecimal.

longValue

public long longValue()
Converts this BigDecimal to a Java long value. Standard narrowing primitive conversion as defined in The Java Language Specification for narrowing conversion of a floating-point number to an integral type is NOT followed. Rather the (non-standard) behaviour of java.math.BigDecimal is followed for backward compatibility: any fractional part of this BigDecimal will be discarded (the standard's term is round toward zero); but then if the resulting "BigInteger" is too big in absolute value to fit in a long (64-bit signed integer), leading bits are discarded or 'decapitated' and only the low-order 64 bits are returned (whereas the standard floating-point to integer value narrowing conversion would have required to return Long.MAX_VALUE or Long.MIN_VALUE).

To avoid unexpected errors when these conditions occur, use the longValueExact() method.

Overrides:
longValue in class java.lang.Number
Returns:
this BigDecimal converted to a long.

longValueExact

public long longValueExact()
                    throws java.lang.ArithmeticExcepti