Decimal arithmetic
Copyright (c) IBM Corporation, 2000. All rights reserved. ©
| 11 Jan 2000 |

[previous | contents | next] |

None of the methods here take a MathContext object as a parameter.

**byteValueExact()**-
Converts the BigDecimal to type

`byte`. If the BigDecimal has a non-zero decimal part or is out of the possible range for a`byte`(8-bit signed integer) result then an`ArithmeticException`is thrown.*Note:*the inherited method**Number.byteValue()**is also available; if that method is used, then if the BigDecimal is out of the possible range for a`byte`(8-bit signed integer) result then only the low-order 8 bits are used. (That is, the number may be*decapitated*) To avoid unexpected errors when these conditions occur, use the**byteValueExact()**method instead. **compareTo(java.lang.Object)**-
Compares the BigDecimal with the value of the parameter, and returns a result of type

`int`.If the parameter is

`null`, or is not an instance of the BigDecimal type, an exception is thrown. Otherwise, the parameter is cast to type`BigDecimal`and the value of**compareTo(BigDecimal)**using the cast parameter is returned.The

**compareTo(BigDecimal[, MathContext])**method should be used when the type of the parameter is known or when a`MathContext`is needed.Implements

**Comparable.compareTo(java.lang.Object)**. **doubleValue()**-
Converts the BigDecimal to type

`double`.The double produced is identical to result of expressing the BigDecimal as a String and then converting it using the

**Double(String)**constructor; this can result in values of`Double.NEGATIVE INFINITY`or`Double.POSITIVE INFINITY`.Implements

**Number.doubleValue()**. **equals(java.lang.Object)**-
Compares the BigDecimal with the value of the parameter, and returns a result of type

`boolean`.If the parameter is

`null`, or is not an instance of the BigDecimal type, or is not exactly equal to the current BigDecimal object, then*false*is returned. Otherwise,*true*is returned.'Exactly equal', here, means that the String representations of the BigDecimal numbers are identical (they have the same characters in the same sequence).

The

**compareTo(BigDecimal[, MathContext])**method should be used for more general comparisons.Overrides

**Object.equals(java.lang.Object)**. **floatValue()**-
Converts the BigDecimal to type

`float`.The float produced is identical to result of expressing the BigDecimal as a String and then converting it using the

**Float(String)**constructor; this can result in values of`Float.NEGATIVE INFINITY`or`Float.POSITIVE INFINITY`.Implements

**Number.floatValue()**. **format(int, int)***and***format(int, int, int, int, int, int)**-
Converts the BigDecimal to type

`java.lang.String`, under the control of formatting (layout) parameters. See also the**toString**method.This method is provided as a primitive for use by more sophisticated classes that will 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.

The parameters, all of type

`int`, are provided to control the format of the String returned. In the prototypes below, parameters are given names for ease of reference. A value of -1 for any parameter indicates that the default action or value for that parameter should be used.If an error is detected during the execution of this method, an

`ArithmeticException`is thrown.Most commonly,

**format**is called with two parameters:**format(***before***,***after***)**The arguments

*before*and*after*may be specified to control the number of characters to be used for the integer part and decimal part of the result respectively. If either of these is -1 (which indicates the default action), the number of characters used will be as many as are needed for that part.*before*must be a positive number; 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*before*is not large enough to contain the integer part of the number (including the sign, for negative numbers) an error results.*after*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. Specifying 0 for*after*will cause the number to be rounded to an integer (that is, it will have no decimal part or decimal point).**Examples:**(In this and following examples, simple method notation for the BigDecimal(String) constructor is used for clarity -- the '*new*' operator would be added for use from Java.)BigDecimal(" - 12.73").format(-1,-1) => "-12.73" BigDecimal("0.000").format(-1,-1) => "0.000" BigDecimal("3").format(4,-1) => " 3" BigDecimal("1.73").format(4,0) => " 2" BigDecimal("1.73").format(4,3) => " 1.730" BigDecimal("-.76").format(4,1) => " -0.8" BigDecimal("3.03").format(4,-1) => " 3.03" BigDecimal("3.03").format(4,3) => " 3.030" BigDecimal("3.03").format(4,1) => " 3.0" BigDecimal(" - 12.73").format(-1,4) => "-12.7300"

A further four arguments may be passed to the format method to control the use of exponential notation and rounding. The syntax of the method with these arguments added is then:**format(***before***,***after***,***explaces***,***exdigits***,***exform***,***exround***)**The first two arguments are as already described. The next three (

*explaces*,*exdigits*, and*exform*) control the exponent part of the result. As before, the default action for any of these arguments may be selected by using the value -1.*explaces*must be a positive number; it sets the number of places (digits after the sign of the exponent) to be used for any exponent part, the default being to use as many as are needed. If*explaces*is specified (is not -1), space is always reserved for an exponent; if one is not needed (for example, if the exponent will be 0) then*explaces*+2 blanks are appended to the result. If*explaces*is specified and is not large enough to contain the exponent, an error results.*exdigits*sets the trigger point for use of exponential notation. If, before any rounding, the number of places needed before the decimal point exceeds*exdigits*, or if the absolute value of the result is less than`0.000001`, then exponential form will be used, provided that*exdigits*was specified. When*exdigits*is -1, exponential notation will never be used. If 0 is specified for*exdigits*, exponential notation is always used unless the exponent would be 0.*exform*sets the form for exponential notation (if needed).*exform*may be either`SCIENTIFIC`(the default) or`ENGINEERING`from the MathContext class. If the latter, engineering, form is requested, up to three digits (plus sign) may be needed for the integer part of the result (*before*).**Examples:**BigDecimal("12345.73").format(-1,-1,2,2,-1,-1) => "1.234573E+04" BigDecimal("12345.73").format(-1,3,-1,0,-1,-1) => "1.235E+4" BigDecimal("1.234573").format(-1,3,-1,0,-1,-1) => "1.235" BigDecimal("123.45").format(-1,3,2,0,-1,-1) => "1.235E+02" BigDecimal("1234.5").format(-1,3,2,0,eng,-1) => "1.235E+03" BigDecimal("12345").format(-1,3,2,0,eng, -1) => "12.345E+03" BigDecimal("1.2345").format(-1,3,2,0,-1,-1) => "1.235 " BigDecimal("12345.73").format(-1,-1,3,6,-1,-1) => "12345.73 " BigDecimal("12345e+5").format(-1,3,-1,-1,-1,-1) => "1234500000.000"

(where`eng`has the value`MathContext.ENGINEERING`).Finally, the sixth argument,

*exround*, selects the rounding algorithm to be used, and must be one of the values indicated by a public constant in the MathContext class whose name starts with`ROUND_`. The default (`ROUND_HALF_UP`) may also be selected by using the value -1, as before.**Examples:**halfdown=MathContext.ROUND_HALF_DOWN halfeven=MathContext.ROUND_HALF_EVEN halfup =MathContext.ROUND_HALF_UP BigDecimal("0.05").format(-1,1,-1,-1,-1,halfdown) => "0.0" BigDecimal("0.05").format(-1,1,-1,-1,-1,halfeven) => "0.0" BigDecimal("0.15").format(-1,1,-1,-1,-1,halfeven) => "0.2" BigDecimal("0.05").format(-1,1,-1,-1,-1,halfup) => "0.1"

The special value`MathContext.ROUND_UNNECESSARY`may be used to detect whether non-zero digits are discarded -- if*exround*has this value than if non-zero digits would be discarded (rounded) during formatting then an`ArithmeticException`is thrown. **hashCode()**-
Returns a hashcode of type

`int`for the object. This hashcode is suitable for use by the`java.util.Hashtable`class.Overrides

**Object.hashCode()**. **intValue()**-
Converts the BigDecimal to type

`int`. If the BigDecimal has a non-zero decimal part it is discarded. If the BigDecimal is out of the possible range for an`int`(32-bit signed integer) result then only the low-order 32 bits are used. (That is, the number may be*decapitated*) To avoid unexpected errors when these conditions occur, use the**intValueExact()**method instead.Implements

**Number.intValue()**. **intValueExact()**-
Converts the BigDecimal to type

`int`. If the BigDecimal has a non-zero decimal part or is out of the possible range for an`int`(32-bit signed integer) result then an`ArithmeticException`is thrown. **longValue()**-
Converts the BigDecimal to type

`long`. If the BigDecimal has a non-zero decimal part it is discarded. If the BigDecimal is out of the possible range for a`long`(64-bit signed integer) result then only the low-order 64 bits are used. (That is, the number may be*decapitated*) To avoid unexpected errors when these conditions occur, use the**longValueExact()**method instead.Implements

**Number.longValue()**. **longValueExact()**-
Converts the BigDecimal to type

`long`. If the BigDecimal has a non-zero decimal part or is out of the possible range for a`long`(64-bit signed integer) result then an`ArithmeticException`is thrown. **movePointLeft(int)**-
Returns a plain BigDecimal whose decimal point has been moved to the left by the number of positions,

*n*, given by the parameter. That is, it returns:this.multiply(TEN.pow(new BigDecimal(-n)))

*n*may be negative, in which case the method returns the same result as**movePointRight(***-n***)**. **movePointRight(int)**-
Returns a plain BigDecimal whose decimal point has been moved to the right by the number of positions,

*n*, given by the parameter. That is, it returns:this.multiply(TEN.pow(new BigDecimal(n)))

*n*may be negative, in which case the method returns the same result as**movePointLeft(***-n***)**. **scale()**-
Returns a non-negative

`int`which is the scale of the number. The scale is the number of digits in the decimal part of the number if the number were formatted without exponential notation. **setScale(int[,int])**-
Returns a plain BigDecimal whose

*scale*is given by the first parameter.If the scale is the same as or greater than the scale of the current BigDecimal then trailing zeros will be added as necessary.

If the scale is less than the scale of the current BigDecimal, then trailing digits will be removed, and the

*rounding mode*given by the second parameter is used to determine if the remaining digits are affected by a carry. In this case, an`IllegalArgumentException`is thrown if*rounding mode*is not a valid rounding mode.The default rounding mode is

**ROUND_UNNECESSARY**, which means that an`ArithmeticException`is thrown if any discarded digits are non-zero.An

`ArithmeticException`is thrown if the*scale*is negative. **shortValueExact()**-
Converts the BigDecimal to type

`short`. If the BigDecimal has a non-zero decimal part or is out of the possible range for a`short`(16-bit signed) result then an`ArithmeticException`is thrown.*Note:*the inherited method**Number.shortValue()**is also available; if that method is used, then if the BigDecimal is out of the possible range for a`short`(16-bit signed integer) result then only the low-order 16 bits are used. (That is, the number may be*decapitated*) To avoid unexpected errors when these conditions occur, use the**shortValueExact()**method instead. **signum()**-
Returns an

`int`value that represents the sign of the BigDecimal. That is, -1 if the BigDecimal is negative, 0 if it is exactly zero, or 1 if it is positive. **toBigDecimal()**-
Returns the number as an object of type

`java.math.BigDecimal`. This is an exact conversion; the result is the same as if the BigDecimal were formatted without any rounding or exponent and then the**java.math.BigDecimal(java.lang.String)**constructor were used to construct the result.*(Note: this method is provided only in the*`com.ibm.math`version of the BigDecimal class. It would not be present in a`java.math`version.) **toBigInteger()**-
Returns the number as an object of type

`java.math.BigInteger`. Any decimal part is truncated (discarded). **toBigIntegerExact()**-
Returns the number as an object of type

`java.math.BigInteger`. If the BigDecimal has a non-zero decimal part then an`ArithmeticException`is thrown. **toCharArray()**-
Returns the BigDecimal as a character array of type

`char[]`, as though the sequence`toString().toCharArray()`had been used. **toString()**-
Returns the standard string of type

`java.lang.String`that exactly represents the BigDecimal, as described in the BigDecimal arithmetic definition.The

**format**method is provided for controlled formatting of BigDecimal numbers.Overrides

**Object.toString()**. **unscaledValue()**-
Returns the number as a BigInteger after removing the scale. That is, the number is expressed as a plain number, any decimal point is then removed, and the result is then converted to a BigInteger.

**valueOf(double)**-
Returns a BigDecimal whose value is the decimal representation of the 64-bit signed binary floating point parameter.

The BigDecimal is constructed as though the

`double`had been converted to a`String`using the**Double.toString()**method and the**BigDecimal(String)**constructor had then been used.This is a static method. A

`NumberFormatException`is thrown if the parameter is infinite, or is not a number (NaN). **valueOf(long[,int])**-
Returns a plain BigDecimal whose value is the first parameter,

*val*, optionally adjusted by a second parameter,*scale*. The default scale is 0.The result is given by:

(new BigDecimal(val)).divide(TEN.pow(new BigDecimal(scale)))

This is a static method. A`NumberFormatException`is thrown if the*scale*is negative.

[previous | contents | next]