Module java.base
Package java.math

Enum Class RoundingMode

java.lang.Object
java.lang.Enum<RoundingMode>
java.math.RoundingMode
所有已实现的接口:
Serializable, Comparable<RoundingMode>, Constable
public enum RoundingMode extends Enum<RoundingMode>
指定了数值运算的舍入策略，能够舍弃精度。每个舍入模式指示如何计算舍入结果的最低有效数字。如果返回的数字比表示精确数值所需的数字少，那么被舍弃的数字将被称为被舍弃的分数，无论这些数字对数值的贡献如何。换句话说，作为数值值，被舍弃的分数的绝对值可能大于一。

更一般地，舍入策略定义了从实数到可表示值子集的映射。对于BigDecimal来说，可表示的值是与计算中使用的精度有关的函数。假设数学结果在BigDecimal的指数范围内，数学结果将在结果精度中精确表示，或者将落在两个相邻可表示值之间。对于落在两个可表示值之间的实数，舍入策略确定这两个边界值中的哪一个是结果。对于范围内的实数，对于给定的可表示值集合，舍入策略将实数线的连续段映射到单个可表示值，其中与可表示值相等的实数被映射到该值。

每个舍入模式描述都包括一个表，列出了不同的两位十进制值在所讨论的舍入模式下如何舍入为一位十进制值。表中的结果列可以通过创建具有指定值的BigDecimal数字，使用正确设置的MathContext对象（precision设置为1，roundingMode设置为所讨论的舍入模式），并在这个数字上调用具有正确MathContext的round来获得。下面是显示所有舍入模式的这些舍入操作结果的摘要表。

不同舍入模式下的舍入操作摘要
输入数字 将输入舍入为给定舍入模式下的一位数字的结果
UP DOWN CEILING FLOOR HALF_UP HALF_DOWN HALF_EVEN UNNECESSARY
5.5 6 5 6 5 6 5 6 抛出ArithmeticException
2.5 3 2 3 2 3 2 2 抛出ArithmeticException
1.6 2 1 2 1 2 2 2 抛出ArithmeticException
1.1 2 1 2 1 1 1 1 抛出ArithmeticException
1.0 1 1 1 1 1 1 1 1
-1.0 -1 -1 -1 -1 -1 -1 -1 -1
-1.1 -2 -1 -1 -2 -1 -1 -1 抛出ArithmeticException
-1.6 -2 -1 -1 -2 -2 -2 -2 抛出ArithmeticException
-2.5 -3 -2 -2 -3 -3 -2 -2 抛出ArithmeticException
-5.5 -6 -5 -5 -6 -6 -5 -6 抛出ArithmeticException

这个enum旨在取代BigDecimal中基于整数的舍入模式常量（BigDecimal.ROUND_UP，BigDecimal.ROUND_DOWN等）。

API 注意:
此类中声明的五个舍入模式对应于IEEE浮点算术标准中定义的舍入方向属性。如果存在，这种对应关系将在特定常量的文档中注明。
参见Java语言规范:
15.4 浮点表达式
自版本:
1.5
另请参阅:

  • Enum Constant Details

    • UP

      public static final RoundingMode UP
      远离零舍入的舍入模式。始终增加非零被舍弃分数之前的数字。请注意，此舍入模式永远不会减少计算值的幅度。

      示例:

      舍入模式UP示例
      输入数字 使用UP舍入舍入为一位数字
      5.5 6
      2.5 3
      1.6 2
      1.1 2
      1.0 1
      -1.0 -1
      -1.1 -2
      -1.6 -2
      -2.5 -3
      -5.5 -6

    • DOWN

      public static final RoundingMode DOWN
      向零舍入的舍入模式。永远不会增加被舍弃分数之前的数字（即截断）。请注意，此舍入模式永远不会增加计算值的幅度。
      API 注意:
      此舍入模式类似于用于float和double运算符余数和转换为整数值的舍入策略（JLS 15.4）。此模式对应于IEEE 754舍入方向属性roundTowardZero。

      示例:

      舍入模式DOWN示例
      输入数字 使用DOWN舍入舍入为一位数字
      5.5 5
      2.5 2
      1.6 1
      1.1 1
      1.0 1
      -1.0 -1
      -1.1 -1
      -1.6 -1
      -2.5 -2
      -5.5 -5

    • CEILING

      public static final RoundingMode CEILING
      向正无穷方向舍入的舍入模式。如果结果为正，则行为类似于RoundingMode.UP；如果为负，则行为类似于RoundingMode.DOWN。请注意，此舍入模式永远不会减少计算出的值。此模式对应于IEEE 754舍入方向属性roundTowardPositive。

      示例：

      向正无穷舍入模式示例
      输入数字 使用CEILING舍入后的一位数字
      5.5 6
      2.5 3
      1.6 2
      1.1 2
      1.0 1
      -1.0 -1
      -1.1 -1
      -1.6 -1
      -2.5 -2
      -5.5 -5

    • FLOOR

      public static final RoundingMode FLOOR
      向负无穷方向舍入的舍入模式。如果结果为正，则行为类似于RoundingMode.DOWN；如果为负，则行为类似于RoundingMode.UP。请注意，此舍入模式永远不会增加计算出的值。此模式对应于IEEE 754舍入方向属性roundTowardNegative。

      示例：

      向负无穷舍入模式示例
      输入数字 使用FLOOR舍入后的一位数字
      5.5 5
      2.5 2
      1.6 1
      1.1 1
      1.0 1
      -1.0 -1
      -1.1 -2
      -1.6 -2
      -2.5 -3
      -5.5 -6

    • HALF_UP

      public static final RoundingMode HALF_UP
      向“最接近邻居”方向舍入的舍入模式，除非两个邻居等距，此时向上舍入。如果被舍弃的小数部分≥ 0.5，则行为类似于RoundingMode.UP；否则，行为类似于RoundingMode.DOWN。请注意，这是学校通常教授的舍入模式。此模式对应于IEEE 754舍入方向属性roundTiesToAway。

      示例：

      向最接近邻居舍入模式示例
      输入数字 使用HALF_UP舍入后的一位数字
      5.5 6
      2.5 3
      1.6 2
      1.1 1
      1.0 1
      -1.0 -1
      -1.1 -1
      -1.6 -2
      -2.5 -3
      -5.5 -6

    • HALF_DOWN

      public static final RoundingMode HALF_DOWN
      向“最接近邻居”方向舍入的舍入模式，除非两个邻居等距，此时向下舍入。如果被舍弃的小数部分> 0.5，则行为类似于RoundingMode.UP；否则，行为类似于RoundingMode.DOWN。

      示例：

      向最接近邻居舍入模式示例
      输入数字 使用HALF_DOWN舍入后的一位数字
      5.5 5
      2.5 2
      1.6 2
      1.1 1
      1.0 1
      -1.0 -1
      -1.1 -1
      -1.6 -2
      -2.5 -2
      -5.5 -5

    • HALF_EVEN

      public static final RoundingMode HALF_EVEN
      向“最接近邻居”方向舍入的舍入模式，除非两个邻居等距，此时向偶数邻居舍入。如果被舍弃的小数部分左侧的数字为奇数，则行为类似于RoundingMode.HALF_UP；如果为偶数，则行为类似于RoundingMode.HALF_DOWN。
      API注释：
      当在一系列计算中重复应用时，这是在统计上最小化累积误差的舍入模式。有时被称为“银行家舍入”，主要用于美国。此舍入模式类似于Java中大多数float和double算术运算符使用的舍入策略（JLS 15.4）。此模式对应于IEEE 754舍入方向属性roundTiesToEven。

      示例：

      向最接近偶数舍入模式示例
      输入数字 使用HALF_EVEN舍入后的一位数字
      5.5 6
      2.5 2
      1.6 2
      1.1 1
      1.0 1
      -1.0 -1
      -1.1 -1
      -1.6 -2
      -2.5 -2
      -5.5 -6

    • UNNECESSARY

      public static final RoundingMode UNNECESSARY
      断言请求的操作具有精确结果，因此不需要舍入的舍入模式。如果在产生不精确结果的操作上指定此舍入模式，则会抛出ArithmeticException。

      示例：

      无需舍入模式示例
      输入数字 使用UNNECESSARY舍入后的一位数字
      5.5 抛出ArithmeticException
      2.5 抛出ArithmeticException
      1.6 抛出ArithmeticException
      1.1 抛出ArithmeticException
      1.0 1
      -1.0 -1
      -1.1 抛出ArithmeticException
      -1.6 抛出ArithmeticException
      -2.5 抛出ArithmeticException
      -5.5 抛出ArithmeticException

  • Method Details

    • values

      public static RoundingMode[] values()
      返回包含此枚举类常量的数组，按照它们声明的顺序排列。
      返回：
      包含此枚举类常量的数组，按照它们声明的顺序排列

    • valueOf

      public static RoundingMode valueOf(String name)
      返回具有指定名称的此类的枚举常量。字符串必须与此类中用于声明枚举常量的标识符完全匹配。（不允许存在多余的空格字符。）
      参数：
      name - 要返回的枚举常量的名称
      返回：
      具有指定名称的枚举常量
      抛出：
      IllegalArgumentException - 如果此枚举类没有具有指定名称的常量
      NullPointerException - 如果参数为null

    • valueOf

      public static RoundingMode valueOf(int rm)
      返回与BigDecimal中的传统整数舍入模式常量对应的RoundingMode对象。
      参数：
      rm - 要转换的传统整数舍入模式
      返回：
      对应于给定整数的RoundingMode
      抛出：
      IllegalArgumentException - 整数超出范围