BigDecimal

目录搜索

文字

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

java.math
类 BigDecimal

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

所有已实现的接口：: Serializable, Comparable<BigDecimal>

public class BigDecimal
extends Number
implements Comparable<BigDecimal>

不可变的、任意精度的有符号十进制数。BigDecimal 由任意精度的整数非标度值 和 32 位的整数标度 (scale) 组成。如果为零或正数，则标度是小数点后的位数。如果为负数，则将该数的非标度值乘以 10 的负 scale 次幂。因此，BigDecimal 表示的数值是 (unscaledValue × 10^-scale)。

BigDecimal 类提供以下操作：算术、标度操作、舍入、比较、哈希算法和格式转换。toString() 方法提供 BigDecimal 的规范表示形式。

BigDecimal 类使用户能完全控制舍入行为。如果未指定舍入模式，并且无法表示准确结果，则抛出一个异常；否则，通过向该操作提供适当的 MathContext 对象，可以对已选择的精度和舍入模式执行计算。在任何情况下，可以为舍入控制提供八种舍入模式。使用此类（例如，ROUND_HALF_UP）中的整数字段来表示舍入模式已过时；应改为使用 RoundingMode enum（例如，RoundingMode.HALF_UP）的枚举值。

当为 MathContext 对象提供 0 的精度设置（例如，MathContext.UNLIMITED）时，算术运算是准确的，它们是不采用任何 MathContext 对象的算术方法。（这是第 5 版之前的版本支持的唯一行为。）为了计算准确结果，不使用附带 0 精度设置的 MathContext 对象的舍入模式设置，因此与该对象无关。在除法中，准确的商可能是一个无限长的十进制扩展；例如，1 除以 3 所得的商。如果商具有无穷的十进制扩展，但是指定了该操作返回准确结果，则抛出 ArithmeticException。否则，像其他操作那样，返回除法运算的准确结果。

当精度设置不为 0 时，BigDecimal 算法的规则完全符合 ANSI X3.274-1996 和 ANSI X3.274-1996/AM 1-2000（ 7.4 节）中定义的算法的可选操作模式。与上述标准不同，BigDecimal 包括多种舍入模式，它们对于版本 5 以前的 BigDecimal 版本中的除法是强制性的。这些 ANSI 标准和 BigDecimal 规范之间的任何冲突都按照有利于 BigDecimal 的方式进行解决。

由于同一数值可以有不同的表示形式（具有不同的标度），因此运算和舍入的规则必须同时指定数值结果和结果表示形式中所用的标度。

一般情况下，当准确结果（在除法中，可能有无限多位）比返回的数值具有更多位数时，舍入模式和精度设置确定操作如何返回具有有限位数的结果。首先，MathContext 的 precision 设置指定要返回的总位数；这确定了结果的精度。位数计数从准确结果的最左边的非零数字开始。舍入模式确定丢弃的尾部位数如何影响返回的结果。

对于所有算术运算符，运算的执行方式是，首先计算准确的中间结果，然后，使用选择的舍入模式将其舍入为精度设置（如有必要）指定的位数。如果不返回准确结果，则将丢弃准确结果的某些数位。当舍入增加了返回结果的大小时，前导数字“9”的进位传播可能会创建新的数位。例如，将值 999.9 舍入为三位数字，则在数值上等于一千，表示为 100×10¹。在这种情况下，新的 "1" 是返回结果的前导数位。

除了逻辑的准确结果外，每种算术运算都有一个表示结果的首选标度。下表列出了每个运算的首选标度。

算术运算结果的首选标度
运算	结果的首选标度
加	max(addend.scale(), augend.scale())
减	max(minuend.scale(), subtrahend.scale())
乘	multiplier.scale() + multiplicand.scale()
除	dividend.scale() - divisor.scale()

这些标度是返回准确算术结果的方法使用的标度；准确相除可能必须使用较大的标度除外，因为准确的结果可能有较多的位数。例如，1/32 得到 0.03125。

舍入之前，逻辑的准确中间结果的标度是该运算的首选标度。如果用 precision 位数无法表示准确的数值结果，则舍入会选择要返回的一组数字，并将该结果的标度从中间结果的标度减小到可以表示实际返回的 precision 位数的最小标度。如果准确结果可以使用最多 precision 个数字表示，则返回具有最接近首选标度的标度的结果表示形式。尤其是，通过移除结尾零并减少标度，可以用少于 precision 个数字来表示准确的可表示的商。例如，使用 floor 舍入模式将结果舍入为三个数字，
19/100 = 0.19 // integer=19, scale=2
但是
21/110 = 0.190 // integer=190, scale=3

注意，对于加、减和乘，标度的缩减量将等于丢弃的准确结果的数字位置数。如果舍入导致进位传播创建一个新的高位，则当未创建新的数位时，会丢弃该结果的附加数字。

其他方法可能与舍入语义稍微不同。例如，使用指定的算法的 pow 方法得到的结果可能偶尔不同于舍入得到的算术结果，如最后一位有多个单位（ulp）。

可以通过两种类型的操作来处理 BigDecimal 的标度：标度/舍入操作和小数点移动操作。标度/舍入操作（setScale 和 round）返回 BigDecimal，其值近似地（或精确地）等于操作数的值，但是其标度或精度是指定的值；即：它们会增加或减少对其值具有最小影响的存储数的精度。小数点移动操作（movePointLeft 和 movePointRight）返回从操作数创建的 BigDecimal，创建的方法是按指定方向将小数点移动一个指定距离。

为了简洁明了起见，整个 BigDecimal 方法的描述中都使用了伪代码。伪代码表达式 (i + j) 是“其值为 BigDecimal i 加 BigDecimal j 的 BigDecimal”的简写。伪代码表达式 (i == j) 是“当且仅当 BigDecimal i 表示与 BigDecimal j 相同的值时，则为 true”的简写。可以类似地解释其他伪代码表达式。方括号用于表示特定的 BigInteger 和定义 BigDecimal 值的标度对；例如，[19, 2] 表示 BigDecimal 在数值上等于 0.19，标度是 2。

注：如果 BigDecimal 对象用作 SortedMap 中的键或 SortedSet 中的元素，则应特别小心，因为 BigDecimal 的自然排序与 equals 方法不一致。有关更多信息，请参见 Comparable、SortedMap 或 SortedSet。

当为任何输入参数传递 null 对象引用时，此类的所有方法和构造方法都将抛出 NullPointerException。

另请参见：: BigInteger, MathContext, RoundingMode, SortedMap, SortedSet, 序列化表格

字段摘要
`static BigDecimal`	`ONE` 值为 1，标度为 0。
`static int`	`ROUND_CEILING` 接近正无穷大的舍入模式。
`static int`	`ROUND_DOWN` 接近零的舍入模式。
`static int`	`ROUND_FLOOR` 接近负无穷大的舍入模式。
`static int`	`ROUND_HALF_DOWN` 向“最接近的”数字舍入，如果与两个相邻数字的距离相等，则为上舍入的舍入模式。
`static int`	`ROUND_HALF_EVEN` 向“最接近的”数字舍入，如果与两个相邻数字的距离相等，则向相邻的偶数舍入。
`static int`	`ROUND_HALF_UP` 向“最接近的”数字舍入，如果与两个相邻数字的距离相等，则为向上舍入的舍入模式。
`static int`	`ROUND_UNNECESSARY` 断言请求的操作具有精确的结果，因此不需要舍入。
`static int`	`ROUND_UP` 舍入远离零的舍入模式。
`static BigDecimal`	`TEN` 值为 10，标度为 0。
`static BigDecimal`	`ZERO` 值为 0，标度为 0。

构造方法摘要
`BigDecimal(BigInteger val)` 将 `BigInteger` 转换为 `BigDecimal`。
`BigDecimal(BigInteger unscaledVal, int scale)` 将 `BigInteger` 非标度值和 `int` 标度转换为 `BigDecimal`。
`BigDecimal(BigInteger unscaledVal, int scale, MathContext mc)` 将 `BigInteger` 非标度值和 `int` 标度转换为 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal(BigInteger val, MathContext mc)` 将 `BigInteger` 转换为 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal(char[] in)` 将 `BigDecimal` 的字符数组表示形式转换为 `BigDecimal`，接受与 `BigDecimal(String)` 构造方法相同的字符序列。
`BigDecimal(char[] in, int offset, int len)` 将 `BigDecimal` 的字符数组表示形式转换为 `BigDecimal`，接受与 `BigDecimal(String)` 构造方法相同的字符序列，同时允许指定子数组。
`BigDecimal(char[] in, int offset, int len, MathContext mc)` 将 `BigDecimal` 的字符数组表示形式转换为 `BigDecimal`，接受与 `BigDecimal(String)` 构造方法相同的字符序列，同时允许指定子数组，并根据上下文设置进行舍入。
`BigDecimal(char[] in, MathContext mc)` 将 `BigDecimal` 的字符数组表示形式转换为 `BigDecimal`，接受与 `BigDecimal(String)` 构造方法相同的字符序列（根据上下文设置进行舍入）。
`BigDecimal(double val)` 将 `double` 转换为 `BigDecimal`，后者是 `double` 的二进制浮点值准确的十进制表示形式。
`BigDecimal(double val, MathContext mc)` 将 `double` 转换为 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal(int val)` 将 `int` 转换为 `BigDecimal`。
`BigDecimal(int val, MathContext mc)` 将 `int` 转换为 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal(long val)` 将 `long` 转换为 `BigDecimal`。
`BigDecimal(long val, MathContext mc)` 将 `long` 转换为 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal(String val)` 将 `BigDecimal` 的字符串表示形式转换为 `BigDecimal`。
`BigDecimal(String val, MathContext mc)` 将 `BigDecimal` 的字符串表示形式转换为 `BigDecimal`，接受与 `BigDecimal(String)` 构造方法相同的字符串（按照上下文设置进行舍入）。

方法摘要
`BigDecimal`	`abs()` 返回 `BigDecimal`，其值为此 `BigDecimal` 的绝对值，其标度为 `this.scale()`。
`BigDecimal`	`abs(MathContext mc)` 返回其值为此 `BigDecimal` 绝对值的 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal`	`add(BigDecimal augend)` 返回一个 `BigDecimal`，其值为 `(this + augend)`，其标度为 `max(this.scale(), augend.scale())`。
`BigDecimal`	`add(BigDecimal augend, MathContext mc)` 返回其值为 `(this + augend)` 的 `BigDecimal`（根据上下文设置进行舍入）。
`byte`	`byteValueExact()` 将此 `BigDecimal` 转换为 `byte`，以检查丢失的信息。
`int`	`compareTo(BigDecimal val)` 将此 `BigDecimal` 与指定的 `BigDecimal` 比较。
`BigDecimal`	`divide(BigDecimal divisor)` 返回一个 `BigDecimal`，其值为 `(this / divisor)`，其首选标度为 `(this.scale() - divisor.scale())`；如果无法表示准确的商值（因为它有无穷的十进制扩展），则抛出 `ArithmeticException`。
`BigDecimal`	`divide(BigDecimal divisor, int roundingMode)` 返回一个 `BigDecimal`，其值为 `(this / divisor)`，其标度为 `this.scale()`。
`BigDecimal`	`divide(BigDecimal divisor, int scale, int roundingMode)` 返回一个 `BigDecimal`，其值为 `(this / divisor)`，其标度为指定标度。
`BigDecimal`	`divide(BigDecimal divisor, int scale, RoundingMode roundingMode)` 返回一个 `BigDecimal`，其值为 `(this / divisor)`，其标度为指定标度。
`BigDecimal`	`divide(BigDecimal divisor, MathContext mc)` 返回其值为 `(this / divisor)` 的 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal`	`divide(BigDecimal divisor, RoundingMode roundingMode)` 返回一个 `BigDecimal`，其值为 `(this / divisor)`，其标度为 `this.scale()`。
`BigDecimal[]`	`divideAndRemainder(BigDecimal divisor)` 返回由两个元素组成的 `BigDecimal` 数组，该数组包含 `divideToIntegralValue` 的结果，后跟对两个操作数计算所得到的 `remainder`。
`BigDecimal[]`	`divideAndRemainder(BigDecimal divisor, MathContext mc)` 返回由两个元素组成的 `BigDecimal` 数组，该数组包含 `divideToIntegralValue` 的结果，后跟根据上下文设置对两个操作数进行舍入计算所得到的 `remainder` 的结果。
`BigDecimal`	`divideToIntegralValue(BigDecimal divisor)` 返回 `BigDecimal`，其值为向下舍入所得商值 `(this / divisor)` 的整数部分。
`BigDecimal`	`divideToIntegralValue(BigDecimal divisor, MathContext mc)` 返回 `BigDecimal`，其值为 `(this / divisor)` 的整数部分。
`double`	`doubleValue()` 将此 `BigDecimal` 转换为 `double`。
`boolean`	`equals(Object x)` 比较此 `BigDecimal` 与指定的 `Object` 的相等性。
`float`	`floatValue()` 将此 `BigDecimal` 转换为 `float`。
`int`	`hashCode()` 返回此 `BigDecimal` 的哈希码。
`int`	`intValue()` 将此 `BigDecimal` 转换为 `int`。
`int`	`intValueExact()` 将此 `BigDecimal` 转换为 `int`，以检查丢失的信息。
`long`	`longValue()` 将此 `BigDecimal` 转换为 `long`。
`long`	`longValueExact()` 将此 `BigDecimal` 转换为 `long`，以检查丢失的信息。
`BigDecimal`	`max(BigDecimal val)` 返回此 `BigDecimal` 和 `val` 的最大值。
`BigDecimal`	`min(BigDecimal val)` 返回此 `BigDecimal` 和 `val` 的最小值。
`BigDecimal`	`movePointLeft(int n)` 返回一个 `BigDecimal`，它等效于将该值的小数点向左移动 `n` 位。
`BigDecimal`	`movePointRight(int n)` 返回一个 `BigDecimal`，它等效于将该值的小数点向右移动 `n` 位。
`BigDecimal`	`multiply(BigDecimal multiplicand)` 返回一个 `BigDecimal`，其值为 `(this × multiplicand)`，其标度为 `(this.scale() + multiplicand.scale())`。
`BigDecimal`	`multiply(BigDecimal multiplicand, MathContext mc)` 返回其值为 `(this × multiplicand)` 的 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal`	`negate()` 返回 `BigDecimal`，其值为 `(-this)`，其标度为 `this.scale()`。
`BigDecimal`	`negate(MathContext mc)` 返回其值为 `(-this)` 的 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal`	`plus()` 返回 `BigDecimal`，其值为 `(+this)`，其标度为 `this.scale()`。
`BigDecimal`	`plus(MathContext mc)` 返回其值为 `(+this)` 的 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal`	`pow(int n)` 返回其值为 `(thisⁿ)` 的 `BigDecimal`，准确计算该幂，使其具有无限精度。
`BigDecimal`	`pow(int n, MathContext mc)` 返回其值为 `(thisⁿ)` 的 `BigDecimal`。
`int`	`precision()` 返回此 `BigDecimal` 的精度。
`BigDecimal`	`remainder(BigDecimal divisor)` 返回其值为 `(this % divisor)` 的 `BigDecimal`。
`BigDecimal`	`remainder(BigDecimal divisor, MathContext mc)` 返回其值为 `(this % divisor)` 的 `BigDecimal`（根据上下文设置进行舍入）。
`BigDecimal`	`round(MathContext mc)` 返回根据 `MathContext` 设置进行舍入后的 `BigDecimal`。
`int`	`scale()` 返回此 `BigDecimal` 的标度。
`BigDecimal`	`scaleByPowerOfTen(int n)` 返回其数值等于 (`this` * 10ⁿ) 的 BigDecimal。
`BigDecimal`	`setScale(int newScale)` 返回一个 `BigDecimal`，其标度为指定值，其值在数值上等于此 `BigDecimal` 的值。
`BigDecimal`	`setScale(int newScale, int roundingMode)` 返回一个 `BigDecimal`，其标度为指定值，其非标度值通过此 `BigDecimal` 的非标度值乘以或除以十的适当次幂来确定，以维护其总值。
`BigDecimal`	`setScale(int newScale, RoundingMode roundingMode)` 返回 `BigDecimal`，其标度为指定值，其非标度值通过此 `BigDecimal` 的非标度值乘以或除以十的适当次幂来确定，以维护其总值。
`short`	`shortValueExact()` 将此 `BigDecimal` 转换为 `short`，以检查丢失的信息。
`int`	`signum()` 返回此 `BigDecimal` 的正负号函数。
`BigDecimal`	`stripTrailingZeros()` 返回数值上等于此小数，但从该表示形式移除所有尾部零的 `BigDecimal`。
`BigDecimal`	`subtract(BigDecimal subtrahend)` 返回一个 `BigDecimal`，其值为 `(this - subtrahend)`，其标度为 `max(this.scale(), subtrahend.scale())`。
`BigDecimal`	`subtract(BigDecimal subtrahend, MathContext mc)` 返回其值为 `(this - subtrahend)` 的 `BigDecimal`（根据上下文设置进行舍入）。
`BigInteger`	`toBigInteger()` 将此 `BigDecimal` 转换为 `BigInteger`。
`BigInteger`	`toBigIntegerExact()` 将此 `BigDecimal` 转换为 `BigInteger`，以检查丢失的信息。
`String`	`toEngineeringString()` 返回此 `BigDecimal` 的字符串表示形式，需要指数时，则使用工程计数法。
`String`	`toPlainString()` 返回不带指数字段的此 `BigDecimal` 的字符串表示形式。
`String`	`toString()` 返回此 `BigDecimal` 的字符串表示形式，如果需要指数，则使用科学记数法。
`BigDecimal`	`ulp()` 返回此 `BigDecimal` 的 ulp（最后一位的单位）的大小。
`BigInteger`	`unscaledValue()` 返回其值为此 `BigDecimal` 的非标度值的 `BigInteger`。
`static BigDecimal`	`valueOf(double val)` 使用 `Double.toString(double)` 方法提供的 `double` 规范的字符串表示形式将 `double` 转换为 `BigDecimal`。
`static BigDecimal`	`valueOf(long val)` 将 `long` 值转换为具有零标度的 `BigDecimal`。
`static BigDecimal`	`valueOf(long unscaledVal, int scale)` 将 `long` 非标度值和 `int` 标度转换为 `BigDecimal`。

从类 java.lang.Number 继承的方法
`byteValue, shortValue`

从类 java.lang.Object 继承的方法
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

字段详细信息

ZERO

public static final BigDecimal ZERO

值为 0，标度为 0。

从以下版本开始：: 1.5

ONE

public static final BigDecimal ONE

值为 1，标度为 0。

从以下版本开始：: 1.5

TEN

public static final BigDecimal TEN

值为 10，标度为 0。

从以下版本开始：: 1.5

ROUND_UP

public static final int ROUND_UP

舍入远离零的舍入模式。在丢弃非零部分之前始终增加数字。注意，此舍入模式始终不会减少计算值的大小。

另请参见：: 常量字段值

ROUND_DOWN

public static final int ROUND_DOWN

接近零的舍入模式。在丢弃某部分之前始终不增加数字（即截短）。注意，此舍入模式始终不会增加计算值的大小。

另请参见：: 常量字段值

ROUND_CEILING

public static final int ROUND_CEILING

接近正无穷大的舍入模式。如果 BigDecimal 为正，则舍入行为与 ROUND_UP 相同；如果为负，则舍入行为与 ROUND_DOWN 相同。注意，此舍入模式始终不会减少计算值。

另请参见：: 常量字段值

ROUND_FLOOR

public static final int ROUND_FLOOR

接近负无穷大的舍入模式。如果 BigDecimal 为正，则舍入行为与 ROUND_DOWN 相同；如果为负，则舍入行为与 ROUND_UP 相同。注意，此舍入模式始终不会增加计算值。

另请参见：: 常量字段值

ROUND_HALF_UP

public static final int ROUND_HALF_UP

向“最接近的”数字舍入，如果与两个相邻数字的距离相等，则为向上舍入的舍入模式。如果舍弃部分 >= 0.5，则舍入行为与 ROUND_UP 相同；否则舍入行为与 ROUND_DOWN 相同。注意，这是我们大多数人在小学时就学过的舍入模式。

另请参见：: 常量字段值

ROUND_HALF_DOWN

public static final int ROUND_HALF_DOWN

向“最接近的”数字舍入，如果与两个相邻数字的距离相等，则为上舍入的舍入模式。如果舍弃部分 > 0.5，则舍入行为与 ROUND_UP 相同；否则舍入行为与 ROUND_DOWN 相同。

另请参见：: 常量字段值

ROUND_HALF_EVEN

public static final int ROUND_HALF_EVEN

向“最接近的”数字舍入，如果与两个相邻数字的距离相等，则向相邻的偶数舍入。如果舍弃部分左边的数字为奇数，则舍入行为与 ROUND_HALF_UP 相同；如果为偶数，则舍入行为与 ROUND_HALF_DOWN 相同。注意，在重复进行一系列计算时，此舍入模式可以将累加错误减到最小。

另请参见：: 常量字段值

ROUND_UNNECESSARY

public static final int ROUND_UNNECESSARY

断言请求的操作具有精确的结果，因此不需要舍入。如果对获得精确结果的操作指定此舍入模式，则抛出 ArithmeticException。

另请参见：: 常量字段值

构造方法详细信息

public BigDecimal(char[] in,
                  int offset,
                  int len)

将 BigDecimal 的字符数组表示形式转换为 BigDecimal，接受与 BigDecimal(String) 构造方法相同的字符序列，同时允许指定子数组。

注意，如果字符数组中已经提供字符的序列，则使用此构造方法要比将 char 数组转换为字符串并使用 BigDecimal(String) 构造方法更快。

参数：: in - 作为源字符的 char 数组。; offset - 要检查的数组中的第一个字符。; len - 要考虑的字符数。

抛出：

NumberFormatException - 如果 in 不是 BigDecimal 的有效表示形式，或者定义的子数组不完全在 in 中。

从以下版本开始：

1.5

BigDecimal

public BigDecimal(char[] in,
                  int offset,
                  int len,
                  MathContext mc)

将 BigDecimal 的字符数组表示形式转换为 BigDecimal，接受与 BigDecimal(String) 构造方法相同的字符序列，同时允许指定子数组，并根据上下文设置进行舍入。

注意，如果字符数组中已经提供字符的序列，则使用此构造方法要比将 char 数组转换为字符串并使用 BigDecimal(String) 构造方法更快。

参数：: in - 作为源字符的 char 数组。; offset - 要检查的数组中的第一个字符。; len - 要考虑的字符数。; mc - 要使用的上下文。

抛出：

ArithmeticException - 如果结果不准确，且舍入模式为 UNNECESSARY。

NumberFormatException - 如果 in 不是 BigDecimal 的有效表示形式，或者定义的子数组不完全在 in 中。

从以下版本开始：

1.5

BigDecimal

public BigDecimal(char[] in)

将 BigDecimal 的字符数组表示形式转换为 BigDecimal，接受与 BigDecimal(String) 构造方法相同的字符序列。

注意，如果字符序列已经可以作为一个字符数组使用，则使用此构造方法要比将 char 数组转换为字符串并使用 BigDecimal(String) 构造方法更快。

参数：: in - 作为源字符的 char 数组。
抛出：: NumberFormatException - 如果 in 不是 BigDecimal 的有效表示形式。
从以下版本开始：: 1.5

BigDecimal

public BigDecimal(char[] in,
                  MathContext mc)

将 BigDecimal 的字符数组表示形式转换为 BigDecimal，接受与 BigDecimal(String) 构造方法相同的字符序列（根据上下文设置进行舍入）。

注意，如果字符序列已经可以作为一个字符数组使用，则使用此构造方法要比将 char 数组转换为字符串并使用 BigDecimal(String) 构造方法更快。

参数：: in - 作为源字符的 char 数组。; mc - 要使用的上下文。

抛出：

ArithmeticException - 如果结果不准确，且舍入模式为 UNNECESSARY。

NumberFormatException - 如果 in 不是 BigDecimal 的有效表示形式。

从以下版本开始：

1.5

BigDecimal

public BigDecimal(String val)

将 BigDecimal 的字符串表示形式转换为 BigDecimal。字符串表示形式由可选符号 '+' ('\u002B') 或 '-' ('\u002D') 组成，后跟零或多个十进制数字（“整数”）的序列，可以选择后跟一个小数，也可以选择后跟一个指数。

该小数由小数点以及后跟的零或更多十进制数字组成。字符串必须至少包含整数或小数部分中的一个数字。由符号、整数和小数部分组成的数字称为有效位数。

指数由字符 'e'（'\u0065') 或 'E' ('\u0045') 以及后跟的一个或多个十进制数字组成。指数的值必须位于 Integer.MAX_VALUE (Integer.MIN_VALUE+1) 和 Integer.MAX_VALUE（包括）之间。

更正式地说，以下语法描述了此构造方法接受的字符串：

BigDecimalString:

Sign_opt Significand Exponent_opt

Sign:

+
-

Significand:

IntegerPart .FractionPart_opt

. FractionPart

IntegerPart

IntegerPart:

Digits

FractionPart:

Digits

Exponent:

ExponentIndicator SignedInteger

ExponentIndicator:

e

E

SignedInteger:

Sign_opt Digits

Digits:

Digit

Digits Digit

Digit:

Character.isDigit(char) 对其返回 true 的任何字符，如 0、1、2……

返回的 BigDecimal 的标度将是小数部分中的数字位数，如果该字符串不包含小数点，则标度为零，这取决于对指数的调整；如果字符串包含一个指数，则从标度减去该指数。得到的标度值必须位于 Integer.MIN_VALUE 和 Integer.MAX_VALUE（包括）之间。

Character.digit(char, int) 集提供从字符到数字的映射，以转换成基数 10。该字符串不能包含任何额外字符（例如，空白）。

示例：
返回的 BigDecimal 的值等于有效位数 × 10^指数。对于左边的每个字符串，得到的表示形式 [BigInteger, scale] 显示在右边。

 "0"            [0,0]
 "0.00"         [0,2]
 "123"          [123,0]
 "-123"         [-123,0]
 "1.23E3"       [123,-1]
 "1.23E+3"      [123,-1]
 "12.3E+7"      [123,-6]
 "12.0"         [120,1]
 "12.3"         [123,1]
 "0.00123"      [123,5]
 "-1.23E-12"    [-123,14]
 "1234.5E-4"    [12345,5]
 "0E+7"         [0,-7]
 "-0"           [0,0]

注：对于不是 float、double NaN 和 ±Infinity 的值，此构造方法与 Float.toString(float) 和 Double.toString(double) 返回的值兼容。这通常是将 float 或 double 转换为 BigDecimal 的首选方法，因为它不会遇到 BigDecimal(double) 构造方法的不可预知问题。

参数：: val - BigDecimal 的字符串表示形式。
抛出：: NumberFormatException - 如果 val 不是 BigDecimal 的有效表示形式。

BigDecimal

public BigDecimal(String val,
                  MathContext mc)

将 BigDecimal 的字符串表示形式转换为 BigDecimal，接受与 BigDecimal(String) 构造方法相同的字符串（按照上下文设置进行舍入）。

参数：: val - BigDecimal 的字符串表示形式。; mc - 要使用的上下文。

抛出：

ArithmeticException - 如果结果不准确，且舍入模式为 UNNECESSARY。

NumberFormatException - 如果 val 不是 BigDecimal 的有效表示形式。

从以下版本开始：

1.5

BigDecimal

public BigDecimal(double val)

将 double 转换为 BigDecimal，后者是 double 的二进制浮点值准确的十进制表示形式。返回的 BigDecimal 的标度是使 (10^scale × val) 为整数的最小值。

注：

此构造方法的结果有一定的不可预知性。有人可能认为在 Java 中写入 new BigDecimal(0.1) 所创建的 BigDecimal 正好等于 0.1（非标度值 1，其标度为 1），但是它实际上等于 0.1000000000000000055511151231257827021181583404541015625。这是因为 0.1 无法准确地表示为 double（或者说对于该情况，不能表示为任何有限长度的二进制小数）。这样，传入到构造方法的值不会正好等于 0.1（虽然表面上等于该值）。
另一方面，String 构造方法是完全可预知的：写入 new BigDecimal("0.1") 将创建一个 BigDecimal，它正好等于预期的 0.1。因此，比较而言，通常建议优先使用 String 构造方法。
当 double 必须用作 BigDecimal 的源时，请注意，此构造方法提供了一个准确转换；它不提供与以下操作相同的结果：先使用 Double.toString(double) 方法，然后使用 BigDecimal(String) 构造方法，将 double 转换为 String。要获取该结果，请使用 static valueOf(double) 方法。

参数：: val - 要转换为 BigDecimal 的 double 值。
抛出：: NumberFormatException - 如果 val 为无穷大或 NaN。

BigDecimal

public BigDecimal(double val,
                  MathContext mc)

将 double 转换为 BigDecimal（根据上下文设置进行舍入）。BigDecimal 的标度是使 (10^scale × val) 为整数的最小值。

此构造方法的结果有一定的不可预知性，通常不建议使用它，请参见 BigDecimal(double) 构造方法下面的注释。

参数：: val - 要转换为 BigDecimal 的 double 值。; mc - 要使用的上下文。

抛出：

ArithmeticException - 如果结果不准确，但是 RoundingMode 为 UNNECESSARY。

NumberFormatException - 如果 val 为无穷大或 NaN。

从以下版本开始：

1.5

BigDecimal

public BigDecimal(BigInteger val)

将 BigInteger 转换为 BigDecimal。BigDecimal 的标度是零。

参数：: val - 要转换为 BigDecimal 的 BigInteger 值。

BigDecimal

public BigDecimal(BigInteger val,
                  MathContext mc)

将 BigInteger 转换为 BigDecimal（根据上下文设置进行舍入）。BigDecimal 的标度为零。

参数：: val - 要转换为 BigDecimal 的 BigInteger 值。; mc - 要使用的上下文。

抛出：

ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY。

从以下版本开始：

1.5

BigDecimal

public BigDecimal(BigInteger unscaledVal,
                  int scale)

将 BigInteger 非标度值和 int 标度转换为 BigDecimal。BigDecimal 的值为 (unscaledVal × 10^-scale)。

参数：: unscaledVal - BigDecimal 的非标度值。; scale - BigDecimal 的标度。

BigDecimal

public BigDecimal(BigInteger unscaledVal,
                  int scale,
                  MathContext mc)

将 BigInteger 非标度值和 int 标度转换为 BigDecimal（根据上下文设置进行舍入）。BigDecimal 的值为 (unscaledVal × 10^-scale)，它是根据 precision 和舍入模式设置进行舍入的。

参数：: unscaledVal - BigDecimal 的非标度值。; scale - BigDecimal 的标度。; mc - 要使用的上下文。

抛出：

ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY。

从以下版本开始：

1.5

BigDecimal

public BigDecimal(int val)

将 int 转换为 BigDecimal。BigDecimal 的标度为零。

参数：: val - 要转换为 BigDecimal 的 int 值。
从以下版本开始：: 1.5

BigDecimal

public BigDecimal(int val,
                  MathContext mc)

将 int 转换为 BigDecimal（根据上下文设置进行舍入）。在进行任何舍入之前，BigDecimal 的标度为零。

参数：: val - 要转换为 BigDecimal 的 int 值。; mc - 要使用的上下文。

抛出：

ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY。

从以下版本开始：

1.5

BigDecimal

public BigDecimal(long val)

将 long 转换为 BigDecimal。BigDecimal 的标度为零。

参数：: val - 要转换为 BigDecimal 的 long 值。
从以下版本开始：: 1.5

BigDecimal

public BigDecimal(long val,
                  MathContext mc)

将 long 转换为 BigDecimal（根据上下文设置进行舍入）。在进行任何舍入之前，BigDecimal 的标度为零。

参数：: val - 要转换为 BigDecimal 的 long 值。; mc - 要使用的上下文。

抛出：

ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY。

从以下版本开始：

1.5

方法详细信息

valueOf

public static BigDecimal valueOf(long unscaledVal,
                                 int scale)

将 long 非标度值和 int 标度转换为 BigDecimal。提供的此“静态工厂方法”优先于 (long, int) 构造方法，因为前者允许重用经常使用的 BigDecimal 值。

参数：: unscaledVal - BigDecimal 的非标度值。; scale - BigDecimal 的标度。

返回：

其值为 (unscaledVal × 10^-scale) 的 BigDecimal。

valueOf

public static BigDecimal valueOf(long val)

将 long 值转换为具有零标度的 BigDecimal。提供的此“静态工厂方法”优先于 (long) 构造方法，因为前者允许重用经常使用的 BigDecimal 值。

参数：: val - BigDecimal 的值。
返回：: 其值为 val 的 BigDecimal。

valueOf

public static BigDecimal valueOf(double val)

使用 Double.toString(double) 方法提供的 double 规范的字符串表示形式将 double 转换为 BigDecimal。

注：这通常是将 double（或 float）转化为 BigDecimal 的首选方法，因为返回的值等于从构造 BigDecimal（使用 Double.toString(double) 得到的结果）得到的值。

参数：: val - 要转换为 BigDecimal 的 double。
返回：: 其值等于或约等于 val 值的 BigDecimal。
抛出：: NumberFormatException - 如果 val 为无穷大或 NaN。
从以下版本开始：: 1.5

add

public BigDecimal add(BigDecimal augend)

返回一个 BigDecimal，其值为 (this + augend)，其标度为 max(this.scale(), augend.scale())。

参数：: augend - 将添加到此 BigDecimal 中的值。
返回：: this + augend

add

public BigDecimal add(BigDecimal augend,
                      MathContext mc)

返回其值为 (this + augend) 的 BigDecimal（根据上下文设置进行舍入）。如果任一数字为零，并且精度设置为非零，则其他数字（必要时进行舍入）可以作为结果。

参数：: augend - 将添加到此 BigDecimal 中的值。; mc - 要使用的上下文。

返回：

this + augend，必要时进行舍入。

抛出：

ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY。

从以下版本开始：

1.5

subtract

public BigDecimal subtract(BigDecimal subtrahend)

返回一个 BigDecimal，其值为 (this - subtrahend)，其标度为 max(this.scale(), subtrahend.scale())。

参数：: subtrahend - 从此 BigDecimal 减去的值。
返回：: this - subtrahend

subtract

public BigDecimal subtract(BigDecimal subtrahend,
                           MathContext mc)

返回其值为 (this - subtrahend) 的 BigDecimal（根据上下文设置进行舍入）。如果 subtrahend 为零，则将其（必要时进行舍入）作为结果。如果为零，则该结果是 subtrahend.negate(mc)。

参数：: subtrahend - 从此 BigDecimal 减去的值。; mc - 要使用的上下文。

返回：

this - subtrahend，必要时进行舍入。

抛出：

ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY。

从以下版本开始：

1.5

multiply

public BigDecimal multiply(BigDecimal multiplicand)

返回一个 BigDecimal，其值为 (this × multiplicand)，其标度为 (this.scale() + multiplicand.scale())。

参数：: multiplicand - 乘以此 BigDecimal 的值。
返回：: this * multiplicand

multiply

public BigDecimal multiply(BigDecimal multiplicand,
                           MathContext mc)

返回其值为 (this × multiplicand) 的 BigDecimal（根据上下文设置进行舍入）。

参数：: multiplicand - 乘以此 BigDecimal 的值。; mc - 要使用的上下文。

返回：

必要时舍入的 this * multiplicand。

抛出：

ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY。

从以下版本开始：

1.5

divide

public BigDecimal divide(BigDecimal divisor,
                         int scale,
                         int roundingMode)

返回一个 BigDecimal，其值为 (this / divisor)，其标度为指定标度。如果必须执行舍入，以生成具有指定标度的结果，则应用指定的舍入模式。

相对于此遗留方法，应优先使用新的 divide(BigDecimal, int, RoundingMode) 方法。

参数：: divisor - 此 BigDecimal 要除以的值。; scale - 要返回的 BigDecimal 商的标度。; roundingMode - 要应用的舍入模式。

返回：

this / divisor

抛出：

ArithmeticException - 如果 divisor 为零，则 roundingMode==ROUND_UNNECESSARY 和指定的标度不足以准确地表示相除的结果。

IllegalArgumentException - 如果 roundingMode 不表示一个有效的舍入模式。

另请参见：

ROUND_UP, ROUND_DOWN, ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_UNNECESSARY

divide

public BigDecimal divide(BigDecimal divisor,
                         int scale,
                         RoundingMode roundingMode)

返回一个 BigDecimal，其值为 (this / divisor)，其标度为指定标度。如果必须执行舍入，以生成具有指定标度的结果，则应用指定的舍入模式。

参数：: divisor - 此 BigDecimal 要除以的值。; scale - 要返回的 BigDecimal 商的标度。; roundingMode - 要应用的舍入模式。

返回：

this / divisor

抛出：

ArithmeticException - 如果 divisor 为零，则 roundingMode==RoundingMode.UNNECESSARY 和指定的标度不足以准确地表示相除的结果。

从以下版本开始：

1.5

divide

public BigDecimal divide(BigDecimal divisor,
                         int roundingMode)

返回一个 BigDecimal，其值为 (this / divisor)，其标度为 this.scale()。如果必须执行舍入，以生成具有给定标度的结果，则应用指定的舍入模式。

相对于此遗留方法，应优先使用新的 divide(BigDecimal, RoundingMode) 方法。

参数：: divisor - 此 BigDecimal 要除以的值。; roundingMode - 要应用的舍入模式。

返回：

this / divisor

抛出：

ArithmeticException - 如果 divisor==0 或者 roundingMode==ROUND_UNNECESSARY 和 this.scale() 不足以准确地表示相除的结果。

IllegalArgumentException - 如果 roundingMode 不表示一个有效的舍入模式。

另请参见：

ROUND_UP, ROUND_DOWN, ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_UNNECESSARY

divide

public BigDecimal divide(BigDecimal divisor,
                         RoundingMode roundingMode)

返回一个 BigDecimal，其值为 (this / divisor)，其标度为 this.scale()。如果必须执行舍入，以生成具有给定标度的结果，则应用指定的舍入模式。

参数：: divisor - 此 BigDecimal 要除以的值。; roundingMode - 要应用的舍入模式。

返回：

this / divisor

抛出：

ArithmeticException - 如果 divisor==0 或者 roundingMode==RoundingMode.UNNECESSARY 和 this.scale() 不足以准确地表示相除的结果。

从以下版本开始：

1.5

divide

public BigDecimal divide(BigDecimal divisor)

返回一个 BigDecimal，其值为 (this / divisor)，其首选标度为 (this.scale() - divisor.scale())；如果无法表示准确的商值（因为它有无穷的十进制扩展），则抛出 ArithmeticException。

参数：: divisor - 此 BigDecimal 要相除的值。
返回：: this / divisor
抛出：: ArithmeticException - 如果准确的商值没有无穷的十进制扩展
从以下版本开始：: 1.5

divide

public BigDecimal divide(BigDecimal divisor,
                         MathContext mc)

返回其值为 (this / divisor) 的 BigDecimal（根据上下文设置进行舍入）。

参数：: divisor - 此 BigDecimal 要除以的值。; mc - 要使用的上下文。

返回：

this / divisor，必要时进行舍入。

抛出：

ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY 或 mc.precision == 0，并且商值具有无穷的十进制扩展。

从以下版本开始：

1.5

divideToIntegralValue

public BigDecimal divideToIntegralValue(BigDecimal divisor)

返回 BigDecimal，其值为向下舍入所得商值 (this / divisor) 的整数部分。该结果的首选标度为 (this.scale() - divisor.scale())。

参数：: divisor - 此 BigDecimal 要除以的值。
返回：: this / divisor 的整数部分。
抛出：: ArithmeticException - 如果 divisor==0
从以下版本开始：: 1.5

divideToIntegralValue

public BigDecimal divideToIntegralValue(BigDecimal divisor,
                                        MathContext mc)

返回 BigDecimal，其值为 (this / divisor) 的整数部分。因为准确商值的整数部分与舍入模式无关，所以舍入模式不影响此方法返回的值。该结果的首选标度是 (this.scale() - divisor.scale())。如果准确商值的整数部分需要的位数多于 mc.precision，则抛出 ArithmeticException。

参数：: divisor - 此 BigDecimal 要相除的值。; mc - 要使用的上下文。

返回：

this / divisor 的整数部分。

抛出：

ArithmeticException - 如果 divisor==0

ArithmeticException - 如果 mc.precision > 0，并且该结果需要的精度大于 mc.precision。

从以下版本开始：

1.5

remainder

public BigDecimal remainder(BigDecimal divisor)

返回其值为 (this % divisor) 的 BigDecimal。

余数由 this.subtract(this.divideToIntegralValue(divisor).multiply(divisor)) 给出。注意，这不是模操作（结果可以为负）。

参数：: divisor - 此 BigDecimal 要除以的值。
返回：: this % divisor。
抛出：: ArithmeticException - 如果 divisor==0
从以下版本开始：: 1.5

remainder

public BigDecimal remainder(BigDecimal divisor,
                            MathContext mc)

返回其值为 (this % divisor) 的 BigDecimal（根据上下文设置进行舍入）。MathContext 设置会影响用于计算余数的隐式除法。余数计算本身要进行准确的定义。因此，余数包含的数字个数可能多于 mc.getPrecision()。

余数由 this.subtract(this.divideToIntegralValue(divisor, mc).multiply(divisor)) 给出。注意，这不是模操作（结果可以为负）。

参数：: divisor - 此 BigDecimal 要相除的值。; mc - 要使用的上下文。

返回：

this % divisor，必要时进行舍入。

抛出：

ArithmeticException - 如果 divisor==0

ArithmeticException - 如果结果不准确，但舍入模式为 UNNECESSARY，或者 mc.precision > 0，并且 this.divideToIntgralValue(divisor) 的结果要求的精度大于 mc.precision。

从以下版本开始：

1.5

另请参见：

divideToIntegralValue(java.math.BigDecimal, java.math.MathContext)

divideAndRemainder

public BigDecimal[] divideAndRemainder(BigDecimal divisor)

返回由两个元素组成的 BigDecimal 数组，该数组包含 divideToIntegralValue 的结果，后跟对两个操作数计算所得到的 remainder。

注意，如果同时需要整数商和余数，则此方法比分别使用 divideToIntegralValue 和 remainder 方法更快速，因为相除仅需执行一次。

参数：: divisor - 此 BigDecimal 要相除的值和计算的余数。
返回：: 由两个元素组成的 BigDecimal 数组：商值（divideToIntegralValue 的结果）是初始元素，余数是最终元素。
抛出：: ArithmeticException - 如果 divisor==0
从以下版本开始：: 1.5
另请参见：: divideToIntegralValue(java.math.BigDecimal, java.math.MathContext), remainder(java.math.BigDecimal, java.math.MathContext)

divideAndRemainder

public BigDecimal[] divideAndRemainder(BigDecimal divisor,
                                       MathContext mc)

返回由两个元素组成的 BigDecimal 数组，该数组包含 divideToIntegralValue 的结果，后跟根据上下文设置对两个操作数进行舍入计算所得到的 remainder 的结果。

注意，如果同时需要整数商和余数，则此方法比分别使用 divideToIntegralValue 和 remainder 方法更快速，因为相除仅需执行一次。

参数：: divisor - 此 BigDecimal 要相除的值和计算的余数。; mc - 要使用的上下文。

返回：

由两个元素组成的 BigDecimal 数组：商值（divideToIntegralValue 的结果）是初始元素，余数是最终元素。

抛出：

ArithmeticException - 如果 divisor==0

从以下版本开始：

1.5

另请参见：

divideToIntegralValue(java.math.BigDecimal, java.math.MathContext), remainder(java.math.BigDecimal, java.math.MathContext)

pow

public BigDecimal pow(int n)

返回其值为 (thisⁿ) 的 BigDecimal，准确计算该幂，使其具有无限精度。

参数 n 必须在 0 到 999999999（包括）之间。ZERO.pow(0) 返回 ONE。注意，未来版本可能会扩展此方法允许的指数范围。

参数：: n - 此 BigDecimal 的幂。
返回：: thisⁿ
抛出：: ArithmeticException - 如果 n 超出范围。
从以下版本开始：: 1.5

pow

public BigDecimal pow(int n,
                      MathContext mc)

返回其值为 (thisⁿ) 的 BigDecimal。当前实现使用的是 ANSI 标准 X3.274-1996 中定义的核心算法（根据上下文设置进行舍入）。一般情况下，返回的数值在具有选择精度的精确数值的两个 ulp 中。注意，未来版本可以使用不同的算法，以减少允许的错误范围，并增加允许的指数范围。

X3.274-1996 算法为：

如果出现以下情况，则抛出 ArithmeticException 异常
- abs(n) > 999999999
- mc.precision == 0 且 n < 0
- mc.precision > 0 且 n 大于 mc.precision
如果 n 为零，则返回 ONE（即使 this 为零），否则
- 如果 n 为正数，则通过重复的平方技术将此结果计算到一个累加器中。每个附带累加器的乘法都使用与 mc 中相同的数学上下文设置，增加到 mc.precision + elength + 1 的精度除外，其中 elength 表示 n 中的十进制数字的个数。
- 如果 n 为负数，则将 n 视为正数计算其结果；然后使用上面指定的工作精度，用一除以此值。
- 然后将正数或负数的最终值舍入为目标精度。

参数：: n - 此 BigDecimal 的幂。; mc - 要使用的上下文。

返回：

使用 ANSI 标准 X3.274-1996 算法的 thisⁿ

抛出：

ArithmeticException - 如果该结果不准确，但是舍入模式为 UNNECESSARY，或者 n 超出范围。

从以下版本开始：

1.5

abs

public BigDecimal abs()

返回 BigDecimal，其值为此 BigDecimal 的绝对值，其标度为 this.scale()。

返回：: abs(this)

abs

public BigDecimal abs(MathContext mc)

返回其值为此 BigDecimal 绝对值的 BigDecimal（根据上下文设置进行舍入）。

参数：: mc - 要使用的上下文。
返回：: abs(this)，必要时进行舍入。
抛出：: ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY。
从以下版本开始：: 1.5

negate

public BigDecimal negate()

返回 BigDecimal，其值为 (-this)，其标度为 this.scale()。

返回：: -this。

negate

public BigDecimal negate(MathContext mc)

返回其值为 (-this) 的 BigDecimal（根据上下文设置进行舍入）。

参数：: mc - 要使用的上下文。
返回：: abs(this)，必要时进行舍入。
抛出：: ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY。
从以下版本开始：: 1.5

plus

public BigDecimal plus()

返回 BigDecimal，其值为 (+this)，其标度为 this.scale()。

此方法仅返回此 BigDecimal，该方法与一元减方法 negate() 对称。

返回：: this。
从以下版本开始：: 1.5
另请参见：: negate()

plus

public BigDecimal plus(MathContext mc)

返回其值为 (+this) 的 BigDecimal（根据上下文设置进行舍入）。

此方法的效果与 round(MathContext) 方法的效果相同。

参数：: mc - 要使用的上下文。
返回：: this，必要时进行舍入。零结果具有的标度为 0。
抛出：: ArithmeticException - 如果结果不准确，但是舍入模式为 UNNECESSARY。
从以下版本开始：: 1.5
另请参见：: round(MathContext)

signum

public int signum()

返回此 BigDecimal 的正负号函数。

返回：: 当此 BigDecimal 的值为负、零或正时，返回 -1、0 或 1。

scale

public int scale()

返回此 BigDecimal 的标度。如果为零或正数，则标度是小数点后的位数。如果为负数，则将该数的非标度值乘以 10 的负 scale 次幂。例如，-3 标度是指非标度值乘以 1000。

返回：: 此 BigDecimal 的标度。

precision

public int precision()

返回此 BigDecimal 的精度。（精度是非标度值的数字个数。）

零值的精度是 1。

返回：: 此 BigDecimal 的精度。
从以下版本开始：: 1.5

unscaledValue

public BigInteger unscaledValue()

返回其值为此 BigDecimal 的非标度值 的 BigInteger。（计算 (this * 10^this.scale())。）

返回：: 此 BigDecimal 的非标度值。
从以下版本开始：: 1.2

round

public BigDecimal round(MathContext mc)

返回根据 MathContext 设置进行舍入后的 BigDecimal。如果精度设置为 0，则不进行任何舍入操作。

此方法的效果与 plus(MathContext) 方法的效果相同。

参数：: mc - 要使用的上下文。
返回：: 根据 MathContext 设置舍入后的 BigDecimal。
抛出：: ArithmeticException - 如果舍入模式为 UNNECESSARY，并且 BigDecimal 操作要求进行舍入。
从以下版本开始：: 1.5
另请参见：: plus(MathContext)

setScale

public BigDecimal setScale(int newScale,
                           RoundingMode roundingMode)

返回 BigDecimal，其标度为指定值，其非标度值通过此 BigDecimal 的非标度值乘以或除以十的适当次幂来确定，以维护其总值。如果该操作减少标度，则非标度值必须被除（而不是乘），并且该值可以更改；在这种情况下，将指定的舍入模式应用到除法中。

参数：: newScale - 要返回的 BigDecimal 值的标度。; roundingMode - 要应用的舍入模式。

返回：

一个 BigDecimal，其标度为指定值，其非标度值可以通过此 BigDecimal 的非标度值乘以或除以十的适当次幂来确定，以维护其总值。

抛出：

ArithmeticException - 如果 roundingMode==UNNECESSARY，并且指定的标度操作要求进行舍入。

从以下版本开始：

1.5

另请参见：

RoundingMode

setScale

public BigDecimal setScale(int newScale,
                           int roundingMode)

返回一个 BigDecimal，其标度为指定值，其非标度值通过此 BigDecimal 的非标度值乘以或除以十的适当次幂来确定，以维护其总值。如果该操作减少标度，则非标度值必须被除（而不是乘），并且该值可以更改；在这种情况下，将指定的舍入模式应用到除法中。

注意，由于 BigDecimal 对象是不可变的，此方法的调用不会导致初始对象被修改，这与使用名为 setX 变异字段 X 方法的常规约定相反。相反，setScale 返回具有适当标度的对象；返回的对象不一定是新分配的。

相对于此遗留方法，应优先使用新的 setScale(int, RoundingMode) 方法。

参数：: newScale - 要返回的 BigDecimal 值的标度。; roundingMode - 要应用的舍入模式。

返回：

一个 BigDecimal，其标度为指定值，其非标度值可以通过此 BigDecimal 的非标度值乘以或除以十的适当次幂来确定。

抛出：

ArithmeticException - 如果 roundingMode==ROUND_UNNECESSARY，并且指定的标度操作要求进行舍入。

IllegalArgumentException - 如果 roundingMode 不表示一个有效的舍入模式。

另请参见：

ROUND_UP, ROUND_DOWN, ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_UNNECESSARY

setScale

public BigDecimal setScale(int newScale)

返回一个 BigDecimal，其标度为指定值，其值在数值上等于此 BigDecimal 的值。如果这不可能，则抛出 ArithmeticException。

此调用通常用于增加标度，在这种情况下，可以保证存在指定标度和正确值的 BigDecimal。如果调用方知道 BigDecimal在其小数部分的结尾有足够多的零（即其整数值中的十的因子），则该调用也可用于减少标度，以允许重新标度，而不更改其值。

此方法返回与 setScale 的两个参数版本相同的结果，但是，为调用方省去了指定舍入模式的麻烦（舍入模式不影响结果）。

注意，由于 BigDecimal 对象是不可变的，因此此方法的调用不会导致初始对象被修改，这与使用名为 setX 变异字段 X 方法的常规约定相反。相反，setScale 返回具有适当标度的对象；返回的对象不一定是新分配的。

参数：: newScale - 要返回的 BigDecimal 值的标度。
返回：: 一个 BigDecimal，其标度为指定值，其非标度值可以通过此 BigDecimal 的非标度值乘以或除以十的适当次幂来确定，以维护其总值。
抛出：: ArithmeticException - 如果指定的标度操作要求进行舍入。
另请参见：: setScale(int, int), setScale(int, RoundingMode)

movePointLeft

public BigDecimal movePointLeft(int n)

返回一个 BigDecimal，它等效于将该值的小数点向左移动 n 位。如果 n 为非负数，则调用仅将 n 添加到该标度。如果 n 为负数，则该调用等效于 movePointRight(-n)。此调用返回的 BigDecimal 的值为 (this × 10^-n)，标度为 max(this.scale()+n, 0)。

参数：: n - 将小数点向左移动的位数。
返回：: 一个 BigDecimal，它等效于将该值的小数点向左移动 n 位。
抛出：: ArithmeticException - 如果标度溢出。

movePointRight

public BigDecimal movePointRight(int n)

返回一个 BigDecimal，它等效于将该值的小数点向右移动 n 位。如果 n 为非负数，则该调用仅从该标度减去 n。如果 n 为负，则该调用等效于 movePointLeft(-n)。此调用返回的 BigDecimal 的值为 (this × 10ⁿ)，标度为 max(this.scale()-n, 0)。

参数：: n - 将小数点向右移动的位数。
返回：: 一个 BigDecimal，它等效于将该值的小数点向右移动 n 位。
抛出：: ArithmeticException - 如果标度溢出。

scaleByPowerOfTen

public BigDecimal scaleByPowerOfTen(int n)

返回其数值等于 (this * 10ⁿ) 的 BigDecimal。该结果的标度为 (this.scale() - n)。

抛出：: ArithmeticException - 如果该标度的范围超出 32 位整数的范围。
从以下版本开始：: 1.5

stripTrailingZeros

public BigDecimal stripTrailingZeros()

返回数值上等于此小数，但从该表示形式移除所有尾部零的 BigDecimal。例如，从 BigDecimal 值 600.0 中移除尾部零，该值具有的 [BigInteger, scale] 组件等于 [6000, 1]，使用 [BigInteger, scale] 组件生成的 6E2 等于 [6, -2]

返回：: 数值上等于移除所有尾部零的 BigDecimal。
从以下版本开始：: 1.5

compareTo

public int compareTo(BigDecimal val)

将此 BigDecimal 与指定的 BigDecimal 比较。根据此方法，值相等但具有不同标度的两个 BigDecimal 对象（如，2.0 和 2.00）被认为是相等的。相对六个 boolean 比较运算符 (<, ==, >, >=, !=, <=) 中每一个运算符的各个方法，优先提供此方法。建议使用以下语句执行上述比较：(x.compareTo(y) <op> 0)，其中 <op> 是六个比较运算符之一。

指定者：: 接口 Comparable<BigDecimal> 中的 compareTo

参数：: val - 将此 BigDecimal 与之比较的 BigDecimal。
返回：: 当此 BigDecimal 在数字上小于、等于或大于 val 时，返回 -1、0 或 1。

equals

public boolean equals(Object x)

比较此 BigDecimal 与指定的 Object 的相等性。与 compareTo 不同，仅当两个 BigDecimal 对象的值和标度都相等时，此方法才认为它们相等（因此通过此方法进行比较时，2.0 不等于 2.00）。

覆盖：: 类 Object 中的 equals

参数：: x - 将与此 BigDecimal 进行比较的 Object。
返回：: 当且仅当指定的 Object 为 BigDecimal，并且其值和标度都等于此 BigDecimal 的值和标度时，返回 true。
另请参见：: compareTo(java.math.BigDecimal), hashCode()

min

public BigDecimal min(BigDecimal val)

返回此 BigDecimal 和 val 的最小值。

参数：: val - 要计算最小值的值。
返回：: 其值为 BigDecimal 和 val 中较小值的 BigDecimal。根据 compareTo 方法的定义，如果它们相等，则返回 this。
另请参见：: compareTo(java.math.BigDecimal)

max

public BigDecimal max(BigDecimal val)

返回此 BigDecimal 和 val 的最大值。

参数：: val - 要计算最大值的值。
返回：: 其值为此 BigDecimal 和 val 中较大值的 BigDecimal。根据 compareTo 方法的定义，如果它们相等，则返回 this。
另请参见：: compareTo(java.math.BigDecimal)

hashCode

public int hashCode()

返回此 BigDecimal 的哈希码。注意，数值上相等但标度不同的两个 BigDecimal 对象（如，2.0 和 2.00）通常没有相同的哈希码。

覆盖：: 类 Object 中的 hashCode

返回：: 此 BigDecimal 的哈希码。
另请参见：: equals(Object)

toString

public String toString()

返回此 BigDecimal 的字符串表示形式，如果需要指数，则使用科学记数法。

根据以下步骤可创建 BigDecimal 的标准的规范化字符串形式：首先，使用不带前导零的字符 '0' 至 '9'（如果其值为零，则使用单个 '0' 字符）将 BigDecimal 的非标度值的绝对值转换为以十为基数的字符串。

其次，计算调整的指数；这是无效的标度，加上转换的非标度值中的字符数减 1。即：-scale+(ulength-1)，其中 ulength 是十进制数字中非标度值的绝对值的长度（其精度）。

如果该标度大于或等于零，并且调整的指数大于或等于 -6，则在不使用指数记数法的情况下将该数转换为字符形式。在这种情况下，如果标度为零，则不添加小数点，如果标度为正数，则插入小数点，且标度指定了小数点右边的字符个数。必要时，将字符 '0' 添加到转换的非标度值的左边。如果插入后小数点前面没有字符，则以传统字符 '0' 为前缀。

否则（即：如果标度为负数，或者调整的指数小于 -6），使用指数记数法将该数转换为字符形式。在这种情况下，如果转换后的 BigInteger 多于一位数，则小数点插入在第一个数字之后。然后，将字符形式的指数作为转换的非标度值（也许具有插入的小数点）的后缀；这包含字母 'E' 和直接跟在其后的转换为字符形式的调整指数。后者的基数为十，使用的字符是 '0' 到 '9'，没有前导零，并且，如果调整的指数为负数，则总是以符号字符 '-' ('\u002D') 为前缀，否则以 '+' ('\u002B') 为前缀。

最后，如果非标度值小于零，则整个字符串以减号 '-' ('\u002D') 为前缀。如果非标度值为零或正数，则不使用符号字符作为前缀。

示例：

对于左边的每个表示形式 [unscaled value, scale]，得到的字符串显示在右边。

 [123,0]      "123"
 [-123,0]     "-123"
 [123,-1]     "1.23E+3"
 [123,-3]     "1.23E+5"
 [123,1]      "12.3"
 [123,5]      "0.00123"
 [123,10]     "1.23E-8"
 [-123,12]    "-1.23E-10"

注：

可区分的 BigDecimal 值和此转换的结果之间存在一对一的映射关系。即：每个可区分的 BigDecimal 值（非标度值和标度）都有唯一的字符串表示形式，作为使用 toString 的结果。如果使用 BigDecimal(String) 构造方法将该字符串表示形式转换为 BigDecimal，则将恢复初始值。
给定的数产生的字符串总是相同的；它不受语言环境的影响。这意味着它可以用作交换十进制数据的规范化字符串表示形式，或用作 Hashtable 的关键字等等。NumberFormat 类及其子类可以处理区分语言环境的数的格式化和分析。
toEngineeringString() 方法可用于在工程计数法中表示带有指数的数。setScale 方法可用于对 BigDecimal 进行舍入，使其小数点后的位数为已知位数。
使用 Character.forDigit 提供的数字到字符的映射关系。

覆盖：: 类 Object 中的 toString

返回：: 此 BigDecimal 的字符串表示形式。
另请参见：: Character.forDigit(int, int), BigDecimal(java.lang.String)

toEngineeringString

public String toEngineeringString()

返回此 BigDecimal 的字符串表示形式，需要指数时，则使用工程计数法。

返回如 toString() 方法中所描述的表示 BigDecimal 的字符串，不包括使用指数记数法的情况，将十的幂调整为三的倍数（工程记数法），这样，非零值的整数部分的范围是 1 到 999。如果对零值使用指数记数法，则使用小数点和小数的一（或二）个零数字，以便保留零值的标度。注意，与 toString() 的输出不同，如果使用 string constructor 将输出字符串转换为 BigDecimal，则此方法的输出不保证恢复此 BigDecimal 的相同 [integer, scale] 对。此方法满足以下较弱约束，即产生的结果在数值上始终等于将字符串构造方法应用到方法的输出得到的结果。

返回：: 此 BigDecimal 的字符串表示形式，如果需要指数，则使用工程记数法。
从以下版本开始：: 1.5

toPlainString

public String toPlainString()

返回不带指数字段的此 BigDecimal 的字符串表示形式。对于具有正标度的值，小数点右边的数字个数用于指示标度。对于具有零或负标度的值，生成得到的字符串，好像将该值转换为在数值上等于具有零标度的值一样，并且好像零标度值的所有尾部零都出现在该结果中。如果非标度值小于零，则整个字符串以减号 '-' ('\u002D') 为前缀。如果非标度值为零或正数，则没有任何符号字符作为前缀。注意，如果将此方法的结果传递到 string constructor，则只需要恢复此 BigDecimal 的数值；新的 BigDecimal 的表示形式可以有不同的标度。尤其是，如果此 BigDecimal 具有负标度，则在由字符串构造方法进行处理时，此方法产生的字符串将具有零标度。（此方法的作用类似于 1.4 和更早版本中的 toString 方法。）

返回：: 不带指数字段的此 BigDecimal 的字符串表示形式。
从以下版本开始：: 1.5
另请参见：: toString(), toEngineeringString()

toBigInteger

public BigInteger toBigInteger()

将此 BigDecimal 转换为 BigInteger。此转换类似于 Java Language Specification 中定义的从 double 到 long 的基本收缩转换：将丢弃此 BigDecimal 的小数部分。注意，此转换会丢失关于 BigDecimal 值的精度信息。

要在转换不准确时（即当丢弃非零小数部分时）抛出异常，请使用 toBigIntegerExact() 方法。

返回：: 转换为 BigInteger 的此 BigDecimal。

toBigIntegerExact

public BigInteger toBigIntegerExact()

将此 BigDecimal 转换为 BigInteger，以检查丢失的信息。如果此 BigDecimal 具有非零小数部分，则抛出一个异常。

返回：: 转换为 BigInteger 的此 BigDecimal。
抛出：: ArithmeticException - 如果 this 具有非零小数部分。
从以下版本开始：: 1.5

longValue

public long longValue()

将此 BigDecimal 转换为 long。此转换类似于 Java Language Specification 中定义的从 double 到 short 的基本收缩转换：将丢弃此 BigDecimal 的小数部分，并且如果生成的 "BigInteger" 太大而不适合用 long 表示，则仅返回 64 位低位字节。注意，此转换会丢失关于此 BigDecimal 值的总大小和精度的信息，并返回带有相反符号的结果。

指定者：: 类 Number 中的 longValue

返回：: 转换为 long 的此 BigDecimal。

longValueExact

public long longValueExact()

将此 BigDecimal 转换为 long，以检查丢失的信息。如果此 BigDecimal 具有非零小数部分，或者超出 long 结果的可能范围，则抛出 ArithmeticException。

返回：: 转换为 long 的此 BigDecimal。
抛出：: ArithmeticException - 如果 this 具有非零小数部分，或者不适合用 long 表示。
从以下版本开始：: 1.5

intValue

public int intValue()

将此 BigDecimal 转换为 int。此转换类似于 Java Language Specification 中定义的从 double 到 short 的基本收缩转换：将丢弃此 BigDecimal 的所有小数部分，并且如果生成的 "BigInteger" 太大而不适合用 int 表示，则仅返回 32 位低位字节。注意，此转换会丢失关于此 BigDecimal 值的总大小和精度的信息，并返回带有相反符号的结果。

指定者：: 类 Number 中的 intValue

返回：: 转换为 int 的此 BigDecimal。

intValueExact

public int intValueExact()

将此 BigDecimal 转换为 int，以检查丢失的信息。如果此 BigDecimal 具有非零小数部分，或者超出 int 结果的可能范围，则抛出 ArithmeticException。

返回：: 转换为 int 的此 BigDecimal。
抛出：: ArithmeticException - 如果 this 具有非零小数部分，或者不适合用 int 表示。
从以下版本开始：: 1.5

shortValueExact

public short shortValueExact()

将此 BigDecimal 转换为 short，以检查丢失的信息。如果此 BigDecimal 具有非零小数部分，或者超出 short 结果的可能范围，则抛出 ArithmeticException。

返回：: 转换为 short 的此 BigDecimal。
抛出：: ArithmeticException - 如果 this 具有非零小数部分，或者不适合用 short 表示。
从以下版本开始：: 1.5

byteValueExact

public byte byteValueExact()

将此 BigDecimal 转换为 byte，以检查丢失的信息。如果此 BigDecimal 具有非零小数部分，或者超出 byte 结果的可能范围，则抛出 ArithmeticException。

返回：: 转换为 byte 的此 BigDecimal。
抛出：: ArithmeticException - 如果 this 具有非零小数部分，或者不适合用 byte 表示。
从以下版本开始：: 1.5

floatValue

public float floatValue()

将此 BigDecimal 转换为 float。此转换类似于 Java Language Specification 中定义的从 double 到 float 的基本收缩转换：如此 BigDecimal 的值太大而不能表示为 float，则将其适当地转换为 Float.NEGATIVE_INFINITY 或 Float.POSITIVE_INFINITY。注意，即使在返回值为有限值的情况下，此转换也可能丢失关于 BigDecimal 值精度的信息。

指定者：: 类 Number 中的 floatValue

返回：: 转换为 float 的此 BigDecimal。

doubleValue

public double doubleValue()

将此 BigDecimal 转换为 double。此转换类似于 Java Language Specification 中定义的从 double 到 float 的 基本收缩转换：如果此 BigDecimal 的数量太大而不能表示为 double，则将其适当地转换为 Double.NEGATIVE_INFINITY 或 Double.POSITIVE_INFINITY。注意，即使在返回值为有限值的情况下，此转换也可能丢失关于 BigDecimal 值精度的信息。

指定者：: 类 Number 中的 doubleValue

返回：: 转换为 double 的此 BigDecimal。

ulp

public BigDecimal ulp()

返回此 BigDecimal 的 ulp（最后一位的单位）的大小。非零 BigDecimal 值的 ulp 是此值与下一个具有相同位数的较大 BigDecimal 值之间的正距离。零值的 ulp 在数值上等于具有 this 标度的 1。使用与 this 相同的标度存储该结果，这样，零和非零值的结果等于 [1, this.scale()]。

返回：: this 的 ulp 的大小
从以下版本开始：: 1.5

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。

java.math 类 BigDecimal

算术运算结果的首选标度

ZERO

ONE

TEN

ROUND_UP

ROUND_DOWN

ROUND_CEILING

ROUND_FLOOR

ROUND_HALF_UP

ROUND_HALF_DOWN

ROUND_HALF_EVEN

ROUND_UNNECESSARY

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

valueOf

valueOf

valueOf

add

add

subtract

subtract

multiply

multiply

divide

divide

divide

divide

divide

divide

divideToIntegralValue

divideToIntegralValue

remainder

remainder

divideAndRemainder

divideAndRemainder

pow

pow

abs

abs

negate

negate

plus

plus

signum

scale

precision

unscaledValue

round

setScale

setScale

setScale

movePointLeft

movePointRight

scaleByPowerOfTen

stripTrailingZeros

compareTo

equals

min

max

hashCode

toString

toEngineeringString

toPlainString

toBigInteger

toBigIntegerExact

java.math
类 BigDecimal