Other methods

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.