Перечисление 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 установлено на рассматриваемый режим округления), и вызвав round на этом числе с соответствующим MathContext. Таблица сводки, показывающая результаты этих операций округления для всех режимов округления, приведена ниже.

**Сводка операций округления при различных режимах округления**
Входное число	Результат округления входного числа до одной цифры с заданным режимом округления
Входное число	`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

См. также:

Сводка вложенных классов

Вложенные классы/интерфейсы, объявленные в классе java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Сводка констант перечисления

Константа перечисления	Описание
`CEILING`	Режим округления до ближайшего большего целого числа.
`DOWN`	Режим округления до ближайшего целого числа к нулю.
`FLOOR`	Режим округления до ближайшего меньшего целого числа.
`HALF_DOWN`	Режим округления до ближайшего целого числа, если оба соседа равноудалены, в противном случае округляет вниз.
`HALF_EVEN`	Режим округления до ближайшего целого числа, если оба соседа равноудалены, в противном случае округляет до ближайшего чётного числа.
`HALF_UP`	Режим округления до ближайшего целого числа, если оба соседа равноудалены, в противном случае округляет вверх.
`UNNECESSARY`	Режим округления, гарантирующий, что результат операции точен, поэтому округление не требуется.
`UP`	Режим округления от нуля.

Сводка методов

Модификатор и тип	Метод	Описание
`static RoundingMode`	`valueOf(int rm)`	Возвращает объект `RoundingMode` , соответствующий устаревшей целочисленной константе режима округления в `BigDecimal`.
`static RoundingMode`	`valueOf(String name)`	Возвращает константу перечисления этого класса с указанным именем.
`static RoundingMode[]`	`values()`	Возвращает массив, содержащий константы этого класса перечисления в порядке их объявления.

Методы, унаследованные от класса java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Методы, унаследованные от класса java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Подробности констант перечисления

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
Входное число	Округленное входное число до одного знака с округлением `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
Входное число	Округленное входное число до одного знака с округлением `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

Режим округления к «ближайшему соседу», если оба соседа равноудалены, в этом случае округлять вверх. Ведет себя как для RoundingMode.UP, если отброшенная дробная часть ≥ 0,5; в противном случае ведет себя как для RoundingMode.DOWN. Обратите внимание, что этот режим округления обычно преподаётся в школе. Этот режим соответствует атрибуту направления округления IEEE 754 roundTiesToAway.

Пример:

Примеры округления в сторону HALF_UP
Входное число	Округленное входное число до одного знака с округлением `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

Режим округления к «ближайшему соседу», если оба соседа равноудалены, в этом случае округлять вниз. Ведет себя как для RoundingMode.UP, если отброшенная дробная часть > 0,5; в противном случае ведет себя как для RoundingMode.DOWN.

Пример:

Примеры округления в сторону HALF_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:

Это режим округления, который статистически минимизирует накопленную ошибку при многократном применении в последовательности вычислений. Иногда его называют «округление банкира» и используется в основном в США. Этот режим округления аналогичен политике округления для большинства операторов арифметики float и double в Java (JLS 15.4). Этот режим соответствует атрибуту направления округления IEEE 754 roundTiesToEven.

Пример:

Примеры округления в сторону HALF_EVEN
Входное число	Округленное входное число до одного знака с округлением `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
Входное число	Округленное входное число до одного знака с округлением `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`

Подробности методов

values

public static RoundingMode[] values()

Возвращает массив, содержащий константы этого класса перечислений в порядке их объявления.

Возвращает:: массив, содержащий константы этого класса перечислений в порядке их объявления

valueOf

public static RoundingMode valueOf(String name)

Возвращает константу перечисления этого класса с указанным именем. Строка должна точно соответствовать идентификатору, используемому для объявления константы перечисления в этом классе. (Дополнительные пробелы не допускаются.)

Параметры:: name - имя возвращаемой константы перечисления.
Возвращает:: константу перечисления с указанным именем
Издаёт исключение:: IllegalArgumentException - если в этом классе перечисления нет константы с указанным именем; NullPointerException - если аргумент равен null

valueOf

public static RoundingMode valueOf(int rm)

Возвращает объект RoundingMode , соответствующий константе режима округления целых чисел в BigDecimal.

Параметры:: rm - константа режима округления целых чисел для преобразования
Возвращает:: RoundingMode , соответствующий заданному целому числу.
Издаёт исключение:: IllegalArgumentException - целое число выходит за пределы диапазона

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/math/RoundingMode.html