Класс-перечисление 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	throw `ArithmeticException`
2.5	3	2	3	2	3	2	2	throw `ArithmeticException`
1.6	2	1	2	1	2	2	2	throw `ArithmeticException`
1.1	2	1	2	1	1	1	1	throw `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	throw `ArithmeticException`
-1.6	-2	-1	-1	-2	-2	-2	-2	throw `ArithmeticException`
-2.5	-3	-2	-2	-3	-3	-2	-2	throw `ArithmeticException`
-5.5	-6	-5	-5	-6	-6	-5	-6	throw `ArithmeticException`

Этот enum предназначен для замены перечисления целочисленных констант режимов округления в BigDecimal (BigDecimal.ROUND_UP, BigDecimal.ROUND_DOWN и т. д.).

Примечание к API:

Пять режимов округления, объявленных в этом классе, соответствуют атрибутам направления округления, определенным в Стандарте IEEE по арифметике с плавающей точкой. Если такое соответствие существует, оно отмечается в документации соответствующей константы.

См. Спецификацию языка Java:

15.4 Выражения с плавающей точкой

Начиная с версии:

1.5

Внешние спецификации

См. также:

Краткое описание вложенных классов

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

Enum.EnumDesc<E>

Модификатор и тип	Класс	Описание
`static final class`	`Enum.EnumDesc<E extends Enum<E>>`	Номинальный дескриптор константы `enum`.

Краткое описание констант перечисления

Константа перечисления	Описание
`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()`	Возвращает массив, содержащий константы этого класса-перечисления в порядке их объявления.

Методы, объявленные в классе Enum

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

Модификатор и тип	Метод	Описание
`protected final Object`	`clone()`	Выбрасывает CloneNotSupportedException.
`final int`	`compareTo(RoundingMode o)`	Сравнивает это перечисление с указанным объектом, определяя порядок.
`final Optional<Enum.EnumDesc<RoundingMode>>`	`describeConstable()`	Возвращает дескриптор перечисления `EnumDesc` для этого экземпляра, если его можно создать, или пустой `Optional`, если создать его невозможно.
`final boolean`	`equals(Object other)`	Возвращает true, если указанный объект равен этой константе перечисления.
`protected final void`	`finalize()`	Устарело, подлежит удалению: этот элемент API может быть удален в будущей версии. Метод финализации помечен как устаревший и подлежащий удалению.
`final Class<RoundingMode>`	`getDeclaringClass()`	Возвращает объект Class, соответствующий типу перечисления этой константы.
`final int`	`hashCode()`	Возвращает хеш-код этой константы перечисления.
`final String`	`name()`	Возвращает имя этой константы перечисления точно в том виде, в каком оно объявлено в объявлении перечисления.
`final int`	`ordinal()`	Возвращает порядковый номер этой константы перечисления (ее позицию в объявлении перечисления, где начальной константе присваивается порядковый номер ноль).
`String`	`toString()`	Возвращает имя этой константы перечисления, указанное в объявлении.
`static <T extends Enum<T>> T`	`valueOf(Class<T> enumClass, String name)`	Возвращает константу перечисления указанного класса перечисления с указанным именем.

Методы, объявленные в классе Object

getClass, notify, notifyAll, wait, wait, wait

Модификатор и тип	Метод	Описание
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Заставляет текущий поток ждать пробуждения, обычно вследствие уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ждать пробуждения, обычно вследствие уведомления или прерывания, либо истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ждать пробуждения, обычно вследствие уведомления или прерывания, либо истечения заданного промежутка реального времени.

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

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 remainder и преобразования в целочисленное значение (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

Режим округления к «ближайшему соседу»; если оба соседа равноудалены, округление выполняется вверх. Если отброшенная дробная часть ≥ 0.5, действует как RoundingMode.UP; в противном случае — как 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

Режим округления к «ближайшему соседу»; если оба соседа равноудалены, округление выполняется вниз. Если отброшенная дробная часть > 0.5, действует как RoundingMode.UP; в противном случае — как 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	throw `ArithmeticException`
2.5	throw `ArithmeticException`
1.6	throw `ArithmeticException`
1.1	throw `ArithmeticException`
1.0	1
-1.0	-1
-1.1	throw `ArithmeticException`
-1.6	throw `ArithmeticException`
-2.5	throw `ArithmeticException`
-5.5	throw `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.