Класс перечисления RoundingMode

java.lang.Object

java.lang.Enum<RoundingMode>

java.math.RoundingMode

Все реализуемые интерфейсы:: Serializable, Comparable<RoundingMode>, Constable

public enum RoundingMode extends Enum<RoundingMode>

Указывает политику округления для числовых операций, способных отбрасывать точность. Каждый режим округления указывает, как вычисляется наименее значащая возвращаемая цифра округленного результата. Если возвращается меньше цифр, чем нужно для представления точного числового результата, отброшенные цифры будут называться отброшенной дробной частью независимо от вклада этих цифр в значение числа. Другими словами, рассматриваемая как числовое значение, отброшенная дробная часть может иметь абсолютное значение больше единицы.

Описание каждого режима округления включает таблицу, показывающую, как различные двузначные десятичные значения округлялись бы до однозначного десятичного значения в соответствии с рассматриваемым режимом округления. Столбец «Результат» в таблицах можно получить, создав 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 по плавающей арифметике, IEEE 754-2019. Там, где это присутствует, эта взаимосвязь будет отмечена в документации конкретной константы.

С:

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

Режим округления к нулю. Никогда не увеличивает цифру перед отбрасываемой дробной частью (т. е. усечение). Обратите внимание, что этот режим округления никогда не увеличивает величину вычисленного значения. Этот режим соответствует атрибуту направления округления IEEE 754-2019 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-2019 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-2019 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-2019 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, если чётная. Обратите внимание, что этот режим округления статистически минимизирует кумулятивную ошибку при многократном применении в последовательности вычислений. Иногда известен как "округление по правилам банка", и в основном используется в США. Этот режим округления аналогичен политике округления, используемой для арифметики float и double в Java. Этот режим соответствует атрибуту направления округления IEEE 754-2019 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, 2021, 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/17/docs/api/java.base/java/math/RoundingMode.html