Класс перечисления 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, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/math/RoundingMode.html