Класс BigDecimal

java.lang.Object

java.lang.Number

java.math.BigDecimal

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

public class BigDecimal extends Number implements Comparable<BigDecimal>

Неизменяемые знаковые десятичные числа произвольной точности.


BigDecimal

состоит из целого числа произвольной точности — немасштабированного значения — и 32-битного целого числа — масштаба. Если масштаб равен нулю или положителен, он соответствует количеству цифр справа от десятичной точки. Если масштаб отрицателен, немасштабированное значение числа умножается на десять в степени, равной модулю масштаба. Таким образом, значение числа, представленного BigDecimal, равно (unscaledValue × 10^-scale).

Класс BigDecimal предоставляет операции для арифметических вычислений, управления масштабом, округления, сравнения, хеширования и преобразования форматов. Метод toString() предоставляет каноническое представление BigDecimal.

Класс BigDecimal предоставляет пользователю полный контроль над поведением округления. Если режим округления не указан и точный результат не может быть представлен, выбрасывается ArithmeticException; в противном случае вычисления можно выполнять с выбранной точностью и режимом округления, передав соответствующий объект MathContext операции. В обоих случаях для управления округлением предусмотрено восемь режимов округления. Использование целочисленных полей этого класса (например, ROUND_HALF_UP) для представления режима округления объявлено устаревшим; вместо этого следует использовать значения перечисления RoundingMode enum (например, RoundingMode.HALF_UP).

Если объект MathContext передан с настройкой точности, равной 0 (например, MathContext.UNLIMITED), арифметические операции выполняются точно, как и арифметические методы, которым не передаётся объект MathContext. Следствием вычисления точного результата является то, что настройка режима округления объекта MathContext с точностью 0 не используется и, следовательно, не имеет значения. При делении точное частное может иметь бесконечное десятичное разложение, например при делении 1 на 3. Если частное имеет бесконечное десятичное разложение, а операция задана так, чтобы возвращать точный результат, выбрасывается ArithmeticException. В противном случае возвращается точный результат деления, как и для других операций.

Если настройка точности не равна 0, правила арифметики BigDecimal в целом совместимы с выбранными режимами работы арифметики, определёнными в ANSI X3.274-1996 и ANSI X3.274-1996/AM 1-2000 (раздел 7.4). В отличие от этих стандартов, BigDecimal включает множество режимов округления. Любые расхождения между этими стандартами ANSI и спецификацией BigDecimal разрешаются в пользу BigDecimal.

Поскольку одно и то же числовое значение может иметь разные представления (с разными масштабами), правила арифметики и округления должны задавать как числовой результат, так и масштаб, используемый в представлении результата. Разные представления одного и того же числового значения называются элементами одной когорты. Естественный порядок BigDecimal считает элементы одной когорты равными. В отличие от него, для равенства, проверяемого методом equals, числовое значение и представление должны совпадать. Результаты таких методов, как scale() и unscaledValue(), будут различаться для численно равных значений с разными представлениями.

В общем случае режимы округления и настройка точности определяют, как операции возвращают результаты с ограниченным количеством цифр, если точный результат содержит больше цифр (возможно, бесконечно много в случае деления и извлечения квадратного корня), чем возвращаемый результат. Сначала общее количество возвращаемых цифр задаётся настройкой precision объекта MathContext; эта настройка определяет точность результата. Подсчёт цифр начинается с самой левой ненулевой цифры точного результата. Режим округления определяет, как отбрасываемые конечные цифры влияют на возвращаемый результат.

Для всех арифметических операторов операция выполняется так, как если бы сначала вычислялся точный промежуточный результат, а затем он округлялся до количества цифр, заданного настройкой точности (если это необходимо), с использованием выбранного режима округления. Если точный результат не возвращается, некоторые разряды точного результата отбрасываются. Когда округление увеличивает модуль возвращаемого результата, перенос может создать новый разряд в начале числа, если там стоит цифра «9». Например, при округлении значения 999.9 до трёх цифр вверх результат будет численно равен тысяче и представлен как 100×10¹. В таких случаях новая цифра «1» становится старшим разрядом возвращаемого результата.

Для методов и конструкторов с параметром MathContext, если результат неточный, а режим округления — UNNECESSARY, будет выброшено ArithmeticException.

Помимо логического точного результата, для каждой арифметической операции существует предпочтительный масштаб представления результата. Предпочтительный масштаб для каждой операции указан в таблице ниже.

Предпочтительные масштабы результатов арифметических операций
Операция	Предпочтительный масштаб результата
Сложение	max(addend.scale(), augend.scale())
Вычитание	max(minuend.scale(), subtrahend.scale())
Умножение	multiplier.scale() + multiplicand.scale()
Деление	dividend.scale() - divisor.scale()
Квадратный корень	ceil(radicand.scale()/2.0)
Корень n-й степени	ceil((double) radicand.scale()/n)

Эти масштабы используются методами, возвращающими точные арифметические результаты; однако для точного деления может потребоваться больший масштаб, поскольку точный результат может содержать больше цифр. Например, 1/32 — это 0.03125.

До округления масштаб логического точного промежуточного результата равен предпочтительному масштабу этой операции. Если точный числовой результат нельзя представить с помощью precision цифр, округление выбирает набор возвращаемых цифр, а масштаб результата уменьшается по сравнению с масштабом промежуточного результата до наименьшего масштаба, позволяющего представить фактически возвращаемые цифры precision. Если точный результат можно представить не более чем precision цифрами, возвращается представление результата с масштабом, наиболее близким к предпочтительному. В частности, точно представимое частное может быть представлено меньшим количеством, чем precision цифр, за счёт удаления конечных нулей и уменьшения масштаба. Например, при округлении до трёх цифр с использованием режима округления floor,
19/100 = 0.19 // integer=19, scale=2
но
21/110 = 0.190 // integer=190, scale=3

Обратите внимание, что для сложения, вычитания и умножения уменьшение масштаба будет равно количеству разрядов точного результата, которые отбрасываются. Если округление приводит к переносу и созданию нового старшего разряда, отбрасывается на одну цифру результата больше, чем в случае, когда новый разряд не создаётся.

Семантика округления других методов может немного отличаться. Например, результат метода pow при использовании указанного алгоритма иногда может отличаться от округлённого математического результата более чем на одну единицу последнего разряда, то есть на один ulp.

Для управления масштабом BigDecimal предусмотрены два типа операций: операции изменения масштаба/округления и операции перемещения десятичной точки. Операции изменения масштаба/округления (setScale и round) возвращают BigDecimal, значение которого приблизительно (или точно) равно значению операнда, но масштаб или точность которого соответствует заданному значению; то есть они увеличивают или уменьшают точность хранимого числа, минимально влияя на его значение. Операции перемещения десятичной точки (movePointLeft и movePointRight) возвращают BigDecimal, созданный из операнда путём перемещения десятичной точки на заданное расстояние в указанном направлении.

Масштаб представлен 32-битным целым числом, поэтому диапазон его значений велик, но ограничен. Если масштаб результата выходит за пределы диапазона 32-битного целого числа из-за переполнения или потери значимости, операция может выбросить ArithmeticException.

Для краткости и ясности в описаниях методов BigDecimal используется псевдокод. Выражение псевдокода (i + j) — это сокращённая запись фразы «BigDecimal, значение которого равно значению BigDecimal i, сложенному со значением BigDecimal j». Выражение псевдокода (i == j) — это сокращённая запись фразы «true тогда и только тогда, когда BigDecimal i представляет то же значение, что и BigDecimal j». Другие выражения псевдокода интерпретируются аналогично. Квадратные скобки используются для обозначения конкретной пары BigInteger и масштаба, определяющей значение BigDecimal; например, [19, 2] — это BigDecimal, численно равный 0.19 и имеющий масштаб 2.

Все методы и конструкторы этого класса выбрасывают NullPointerException, если для любого входного параметра передана ссылка на объект null.

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

Следует соблюдать осторожность при использовании объектов BigDecimal в качестве ключей в SortedMap или элементов в SortedSet, поскольку естественный порядок


BigDecimal

не согласован с equals. Дополнительную информацию см. в документации Comparable, SortedMap или SortedSet.

Связь с десятичной арифметикой IEEE 754

Начиная с редакции 2008 года, стандарт IEEE 754 для арифметики с плавающей запятой охватывает десятичные форматы и операции. Хотя десятичная арифметика, определённая IEEE 754 и этим классом, во многом схожа, существуют и заметные различия. Основное сходство между


BigDecimal

и десятичной арифметикой IEEE 754 заключается в концептуальном подходе: вычисляется математическое значение операции как вещественное число с бесконечной точностью, после чего это число преобразуется в представимое десятичное число с плавающей запятой в соответствии с правилом округления. Для BigDecimal правило округления называется режимом округления, а в IEEE 754-2019 — атрибутом направления округления. Если точное значение не представимо, правило округления определяет, какое из двух представимых десятичных значений, между которыми находится точное значение, будет выбрано в качестве результата вычисления. Понятие предпочтительного масштаба/предпочтительного показателя также используется в обеих системах.

В числе различий — поддержка IEEE 754 нескольких видов значений, которые не моделируются в BigDecimal, включая отрицательный ноль, знаковые бесконечности и NaN (не число). IEEE 754 определяет форматы, параметризуемые основанием (двоичным или десятичным), количеством значащих цифр и диапазоном показателя. Формат задаёт множество представимых значений. Большинство операций принимают на вход одно или несколько значений заданного формата и возвращают результат в том же формате. Масштаб объекта BigDecimal эквивалентен показателю значения IEEE 754, взятому с противоположным знаком. Значения BigDecimal не имеют формат в том же смысле: у всех значений один и тот же возможный диапазон масштаба/показателя, а немасштабированное значение имеет произвольную точность. Вместо этого для операций BigDecimal, принимающих параметр MathContext, если MathContext имеет ненулевую точность, множество возможных представимых значений результата определяется точностью аргумента MathContext. Например, в BigDecimal при умножении ненулевого трёхзначного числа на ненулевое четырёхзначное число в контексте объекта MathContext с точностью три результат будет содержать три цифры (при условии отсутствия переполнения, потери значимости и т. д.).

Правила округления, реализованные в операциях BigDecimal и задаваемые режимами округления, представляют собой надмножество атрибутов направления округления IEEE 754.

Арифметика BigDecimal будет наиболее близка к десятичной арифметике IEEE 754, если для округления всех исходных значений и промежуточных операций использовать MathContext, соответствующий десятичному формату IEEE 754, например decimal64 или decimal128. Вычисленные числовые значения могут отличаться, если превышен диапазон показателя аппроксимируемого формата IEEE 754, поскольку MathContext не ограничивает масштаб результатов BigDecimal. Операции, которые привели бы к NaN или точной бесконечности, например деление на ноль, в арифметике BigDecimal выбрасывают ArithmeticException.

Алгоритмическая сложность

Операции над значениями BigDecimal имеют разную алгоритмическую сложность; в общем случае она зависит как от размера немасштабированного значения, так и от размера масштаба. Например, на точное умножение двух значений BigDecimal распространяются те же ограничения сложности, что и на умножение BigInteger немасштабированных значений. В отличие от этого, значение BigDecimal с компактным представлением, таким как new BigDecimal(1E-1000000000), при вызове метода toPlainString() может дать результат длиной более миллиарда символов.

Операции также могут выделять память для промежуточных результатов и выполнять над ними вычисления; объём этих выделений потенциально может быть пропорционален времени выполнения алгоритма.

Пользователи BigDecimal, которым необходимо ограничить время выполнения или объём памяти операций, могут отсеивать значения BigDecimal, у которых немасштабированные значения или масштабы превышают выбранную величину.

С момента версии:

1.1

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

См. также:

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

Модификатор и тип	Поле	Описание
`static final BigDecimal`	`ONE`	Значение 1 с масштабом 0.
`static final int`	`ROUND_CEILING`	Устарело. Вместо этого используйте `RoundingMode.CEILING`.
`static final int`	`ROUND_DOWN`	Устарело. Вместо этого используйте `RoundingMode.DOWN`.
`static final int`	`ROUND_FLOOR`	Устарело. Вместо этого используйте `RoundingMode.FLOOR`.
`static final int`	`ROUND_HALF_DOWN`	Устарело. Вместо этого используйте `RoundingMode.HALF_DOWN`.
`static final int`	`ROUND_HALF_EVEN`	Устарело. Вместо этого используйте `RoundingMode.HALF_EVEN`.
`static final int`	`ROUND_HALF_UP`	Устарело. Вместо этого используйте `RoundingMode.HALF_UP`.
`static final int`	`ROUND_UNNECESSARY`	Устарело. Вместо этого используйте `RoundingMode.UNNECESSARY`.
`static final int`	`ROUND_UP`	Устарело. Вместо этого используйте `RoundingMode.UP`.
`static final BigDecimal`	`TEN`	Значение 10 с масштабом 0.
`static final BigDecimal`	`TWO`	Значение 2 с масштабом 0.
`static final BigDecimal`	`ZERO`	Значение 0 с масштабом 0.

Краткое описание конструкторов

Конструктор	Описание
`BigDecimal(char[] in)`	Преобразует представление `BigDecimal` в виде массива символов в `BigDecimal`, принимая ту же последовательность символов, что и конструктор `BigDecimal(String)`.
`BigDecimal(char[] in, int offset, int len)`	Преобразует представление `BigDecimal` в виде массива символов в `BigDecimal`, принимая ту же последовательность символов, что и конструктор `BigDecimal(String)`, и позволяя указать подмассив.
`BigDecimal(char[] in, int offset, int len, MathContext mc)`	Преобразует представление `BigDecimal` в виде массива символов в `BigDecimal`, принимая ту же последовательность символов, что и конструктор `BigDecimal(String)`, позволяя указать подмассив и выполняя округление согласно настройкам контекста.
`BigDecimal(char[] in, MathContext mc)`	Преобразует представление `BigDecimal` в виде массива символов в `BigDecimal`, принимая ту же последовательность символов, что и конструктор `BigDecimal(String)`, и выполняя округление согласно настройкам контекста.
`BigDecimal(double val)`	Преобразует `double` в `BigDecimal`, являющееся точным десятичным представлением двоичного значения с плавающей точкой типа `double`.
`BigDecimal(double val, MathContext mc)`	Преобразует `double` в `BigDecimal`, выполняя округление согласно настройкам контекста.
`BigDecimal(int val)`	Преобразует `int` в `BigDecimal`.
`BigDecimal(int val, MathContext mc)`	Преобразует `int` в `BigDecimal`, выполняя округление согласно настройкам контекста.
`BigDecimal(long val)`	Преобразует `long` в `BigDecimal`.
`BigDecimal(long val, MathContext mc)`	Преобразует `long` в `BigDecimal`, выполняя округление согласно настройкам контекста.
`BigDecimal(String val)`	Преобразует строковое представление `BigDecimal` в `BigDecimal`.
`BigDecimal(String val, MathContext mc)`	Преобразует строковое представление `BigDecimal` в `BigDecimal`, принимая те же строки, что и конструктор `BigDecimal(String)`, и выполняя округление согласно настройкам контекста.
`BigDecimal(BigInteger val)`	Преобразует `BigInteger` в `BigDecimal`.
`BigDecimal(BigInteger unscaledVal, int scale)`	Преобразует ненормализованное значение типа `BigInteger` и масштаб типа `int` в `BigDecimal`.
`BigDecimal(BigInteger unscaledVal, int scale, MathContext mc)`	Преобразует ненормализованное значение типа `BigInteger` и масштаб типа `int` в `BigDecimal`, выполняя округление согласно настройкам контекста.
`BigDecimal(BigInteger val, MathContext mc)`	Преобразует `BigInteger` в `BigDecimal`, выполняя округление согласно настройкам контекста.

Краткое описание методов

Модификатор и тип	Метод	Описание
`BigDecimal`	`abs()`	Возвращает `BigDecimal`, значение которого равно абсолютному значению этого `BigDecimal`, а масштаб равен `this.scale()`.
`BigDecimal`	`abs(MathContext mc)`	Возвращает `BigDecimal`, значение которого равно абсолютному значению этого `BigDecimal`; округление выполняется согласно настройкам контекста.
`BigDecimal`	`add(BigDecimal augend)`	Возвращает `BigDecimal` со значением `(this + augend)` и масштабом `max(this.scale(), augend.scale())`.
`BigDecimal`	`add(BigDecimal augend, MathContext mc)`	Возвращает `BigDecimal` со значением `(this + augend)`; округление выполняется согласно настройкам контекста.
`byte`	`byteValueExact()`	Преобразует этот `BigDecimal` в `byte`, проверяя наличие потери информации.
`int`	`compareTo(BigDecimal val)`	Сравнивает этот `BigDecimal` с указанным `BigDecimal` по числовому значению.
`BigDecimal`	`divide(BigDecimal divisor)`	Возвращает `BigDecimal` со значением `(this / divisor)` и предпочтительным масштабом `(this.scale() - divisor.scale())`; если точное частное нельзя представить (поскольку его десятичное разложение бесконечно), выбрасывается `ArithmeticException`.
`BigDecimal`	`divide(BigDecimal divisor, int roundingMode)`	Устарело. Вместо этого устаревшего метода следует использовать метод `divide(BigDecimal, RoundingMode)`.
`BigDecimal`	`divide(BigDecimal divisor, int scale, int roundingMode)`	Устарело. Вместо этого устаревшего метода следует использовать метод `divide(BigDecimal, int, RoundingMode)`.
`BigDecimal`	`divide(BigDecimal divisor, int scale, RoundingMode roundingMode)`	Возвращает `BigDecimal` со значением `(this / divisor)` и указанным масштабом.
`BigDecimal`	`divide(BigDecimal divisor, MathContext mc)`	Возвращает `BigDecimal` со значением `(this / divisor)`; округление выполняется согласно настройкам контекста.
`BigDecimal`	`divide(BigDecimal divisor, RoundingMode roundingMode)`	Возвращает `BigDecimal` со значением `(this / divisor)` и масштабом `this.scale()`.
`BigDecimal[]`	`divideAndRemainder(BigDecimal divisor)`	Возвращает массив `BigDecimal` из двух элементов, содержащий результат `divideToIntegralValue`, за которым следует результат `remainder` для двух операндов.
`BigDecimal[]`	`divideAndRemainder(BigDecimal divisor, MathContext mc)`	Возвращает массив `BigDecimal` из двух элементов, содержащий результат `divideToIntegralValue`, за которым следует результат `remainder` для двух операндов; вычисления выполняются с округлением согласно настройкам контекста.
`BigDecimal`	`divideToIntegralValue(BigDecimal divisor)`	Возвращает `BigDecimal`, значение которого равно целой части частного `(this / divisor)`, округлённой вниз.
`BigDecimal`	`divideToIntegralValue(BigDecimal divisor, MathContext mc)`	Возвращает `BigDecimal`, значение которого равно целой части `(this / divisor)`.
`double`	`doubleValue()`	Преобразует этот `BigDecimal` в `double`.
`boolean`	`equals(Object x)`	Проверяет, равен ли этот `BigDecimal` указанному `Object`.
`float`	`floatValue()`	Преобразует этот `BigDecimal` в `float`.
`int`	`hashCode()`	Возвращает хеш-код этого `BigDecimal`.
`int`	`intValue()`	Преобразует этот `BigDecimal` в `int`.
`int`	`intValueExact()`	Преобразует этот `BigDecimal` в `int`, проверяя наличие потери информации.
`long`	`longValue()`	Преобразует этот `BigDecimal` в `long`.
`long`	`longValueExact()`	Преобразует этот `BigDecimal` в `long`, проверяя наличие потери информации.
`BigDecimal`	`max(BigDecimal val)`	Возвращает максимум этого `BigDecimal` и `val`.
`BigDecimal`	`min(BigDecimal val)`	Возвращает минимум этого `BigDecimal` и `val`.
`BigDecimal`	`movePointLeft(int n)`	Возвращает `BigDecimal`, эквивалентное этому значению, но с десятичной точкой, сдвинутой `n` разрядов влево.
`BigDecimal`	`movePointRight(int n)`	Возвращает `BigDecimal`, эквивалентное этому значению, но с десятичной точкой, сдвинутой `n` разрядов вправо.
`BigDecimal`	`multiply(BigDecimal multiplicand)`	Возвращает `BigDecimal` со значением `(this × multiplicand)` и масштабом `(this.scale() + multiplicand.scale())`.
`BigDecimal`	`multiply(BigDecimal multiplicand, MathContext mc)`	Возвращает `BigDecimal` со значением `(this × multiplicand)`; округление выполняется согласно настройкам контекста.
`BigDecimal`	`negate()`	Возвращает `BigDecimal` со значением `(-this)` и масштабом `this.scale()`.
`BigDecimal`	`negate(MathContext mc)`	Возвращает `BigDecimal` со значением `(-this)`; округление выполняется согласно настройкам контекста.
`BigDecimal`	`plus()`	Возвращает `BigDecimal` со значением `(+this)` и масштабом `this.scale()`.
`BigDecimal`	`plus(MathContext mc)`	Возвращает `BigDecimal` со значением `(+this)`; округление выполняется согласно настройкам контекста.
`BigDecimal`	`pow(int n)`	Возвращает `BigDecimal` со значением `(thisⁿ)`. Степень вычисляется точно, с неограниченной точностью.
`BigDecimal`	`pow(int n, MathContext mc)`	Возвращает `BigDecimal` со значением `(thisⁿ)`.
`int`	`precision()`	Возвращает точность этого `BigDecimal`.
`BigDecimal`	`remainder(BigDecimal divisor)`	Возвращает `BigDecimal` со значением `(this % divisor)`.
`BigDecimal`	`remainder(BigDecimal divisor, MathContext mc)`	Возвращает `BigDecimal` со значением `(this % divisor)`; округление выполняется согласно настройкам контекста.
`BigDecimal`	`rootn(int n, MathContext mc)`	Возвращает приближённое значение корня `n`-й степени из `this` с округлением согласно настройкам контекста.
`BigDecimal`	`round(MathContext mc)`	Возвращает `BigDecimal`, округлённое согласно настройкам `MathContext`.
`int`	`scale()`	Возвращает масштаб этого `BigDecimal`.
`BigDecimal`	`scaleByPowerOfTen(int n)`	Возвращает BigDecimal, числовое значение которого равно (`this` * 10ⁿ).
`BigDecimal`	`setScale(int newScale)`	Возвращает `BigDecimal` с указанным масштабом и числовым значением, равным значению этого `BigDecimal`.
`BigDecimal`	`setScale(int newScale, int roundingMode)`	Устарело. Вместо этого устаревшего метода следует использовать метод `setScale(int, RoundingMode)`.
`BigDecimal`	`setScale(int newScale, RoundingMode roundingMode)`	Возвращает `BigDecimal` с указанным масштабом; ненормализованное значение определяется умножением или делением ненормализованного значения этого `BigDecimal` на соответствующую степень десяти, чтобы сохранить его общее значение.
`short`	`shortValueExact()`	Преобразует этот `BigDecimal` в `short`, проверяя наличие потери информации.
`int`	`signum()`	Возвращает функцию знака для этого `BigDecimal`.
`BigDecimal`	`sqrt(MathContext mc)`	Возвращает приближённое значение квадратного корня из `this` с округлением согласно настройкам контекста.
`BigDecimal`	`stripTrailingZeros()`	Возвращает `BigDecimal`, численно равное этому значению, но без конечных нулей в представлении.
`BigDecimal`	`subtract(BigDecimal subtrahend)`	Возвращает `BigDecimal` со значением `(this - subtrahend)` и масштабом `max(this.scale(), subtrahend.scale())`.
`BigDecimal`	`subtract(BigDecimal subtrahend, MathContext mc)`	Возвращает `BigDecimal` со значением `(this - subtrahend)`; округление выполняется согласно настройкам контекста.
`BigInteger`	`toBigInteger()`	Преобразует этот `BigDecimal` в `BigInteger`.
`BigInteger`	`toBigIntegerExact()`	Преобразует этот `BigDecimal` в `BigInteger`, проверяя наличие потери информации.
`String`	`toEngineeringString()`	Возвращает строковое представление этого `BigDecimal`, используя инженерную нотацию, если требуется показатель степени.
`String`	`toPlainString()`	Возвращает строковое представление этого `BigDecimal` без поля показателя степени.
`String`	`toString()`	Возвращает строковое представление этого `BigDecimal`, используя научную нотацию, если требуется показатель степени.
`BigDecimal`	`ulp()`	Возвращает размер ulp — единицы младшего разряда этого `BigDecimal`.
`BigInteger`	`unscaledValue()`	Возвращает `BigInteger`, значение которого равно ненормализованному значению этого `BigDecimal`.
`static BigDecimal`	`valueOf(double val)`	Преобразует `double` в `BigDecimal`, используя каноническое строковое представление `double`, возвращаемое методом `Double.toString(double)`.
`static BigDecimal`	`valueOf(long val)`	Преобразует значение типа `long` в `BigDecimal` с нулевым масштабом.
`static BigDecimal`	`valueOf(long unscaledVal, int scale)`	Преобразует ненормализованное значение типа `long` и масштаб типа `int` в `BigDecimal`.

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

byteValue, shortValue

Модификатор и тип	Метод	Описание
`byte`	`byteValue()`	Возвращает значение указанного числа как `byte`.
`short`	`shortValue()`	Возвращает значение указанного числа как `short`.

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

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

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

Подробное описание полей

ZERO

public static final BigDecimal ZERO

Значение 0 с масштабом 0.

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

ONE

public static final BigDecimal ONE

Значение 1 с масштабом 0.

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

TWO

public static final BigDecimal TWO

Значение 2 с масштабом 0.

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

TEN

public static final BigDecimal TEN

Значение 10 с масштабом 0.

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

ROUND_UP

@Deprecated(since="9") public static final int ROUND_UP

Устарел.

Вместо него используйте RoundingMode.UP.

Режим округления от нуля. Всегда увеличивает цифру перед отбрасываемой ненулевой дробной частью. Обратите внимание, что этот режим округления никогда не уменьшает модуль вычисленного значения.

См. также:

ROUND_DOWN

@Deprecated(since="9") public static final int ROUND_DOWN

Устарел.

Вместо него используйте RoundingMode.DOWN.

Режим округления к нулю. Никогда не увеличивает цифру перед отбрасываемой дробной частью (то есть отсекает её). Обратите внимание, что этот режим округления никогда не увеличивает модуль вычисленного значения.

См. также:

ROUND_CEILING

@Deprecated(since="9") public static final int ROUND_CEILING

Устарел.

Вместо него используйте RoundingMode.CEILING.

Режим округления к плюс бесконечности. Если BigDecimal положительно, действует как ROUND_UP; если отрицательно — как ROUND_DOWN. Обратите внимание, что этот режим округления никогда не уменьшает вычисленное значение.

См. также:

ROUND_FLOOR

@Deprecated(since="9") public static final int ROUND_FLOOR

Устарел.

Вместо него используйте RoundingMode.FLOOR.

Режим округления к минус бесконечности. Если BigDecimal положительно, действует как ROUND_DOWN; если отрицательно — как ROUND_UP. Обратите внимание, что этот режим округления никогда не увеличивает вычисленное значение.

См. также:

ROUND_HALF_UP

@Deprecated(since="9") public static final int ROUND_HALF_UP

Устарел.

Вместо него используйте RoundingMode.HALF_UP.

Режим округления к «ближайшему соседу», если только оба соседа не равноудалены — в этом случае округление выполняется вверх. Действует как ROUND_UP, если отбрасываемая дробная часть ≥ 0.5; в противном случае действует как ROUND_DOWN. Обратите внимание, что именно этому режиму округления большинство из нас учились в школе.

См. также:

ROUND_HALF_DOWN

@Deprecated(since="9") public static final int ROUND_HALF_DOWN

Устарел.

Вместо него используйте RoundingMode.HALF_DOWN.

Режим округления к «ближайшему соседу», если только оба соседа не равноудалены — в этом случае округление выполняется вниз. Действует как ROUND_UP, если отбрасываемая дробная часть > 0.5; в противном случае действует как ROUND_DOWN.

См. также:

ROUND_HALF_EVEN

@Deprecated(since="9") public static final int ROUND_HALF_EVEN

Устарел.

Вместо него используйте RoundingMode.HALF_EVEN.

Режим округления к «ближайшему соседу», если только оба соседа не равноудалены — в этом случае округление выполняется в сторону чётного соседа. Действует как ROUND_HALF_UP, если цифра слева от отбрасываемой дробной части нечётная; если она чётная — действует как ROUND_HALF_DOWN. Обратите внимание, что этот режим округления минимизирует накопленную погрешность при многократном применении в последовательности вычислений.

См. также:

ROUND_UNNECESSARY

@Deprecated(since="9") public static final int ROUND_UNNECESSARY

Устарел.

Вместо него используйте RoundingMode.UNNECESSARY.

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

См. также:

Подробное описание конструкторов

BigDecimal

public BigDecimal(char[] in, int offset, int len)

Преобразует представление BigDecimal в виде массива символов в BigDecimal, принимая ту же последовательность символов, что и конструктор BigDecimal(String), при этом позволяя указать подмассив.

Примечание по реализации:: Если последовательность символов уже доступна в массиве символов, использование этого конструктора быстрее, чем преобразование массива char в строку и использование конструктора BigDecimal(String).
Параметры:: in — массив char, являющийся источником символов.; offset — индекс первого символа массива для проверки.; len — количество рассматриваемых символов.
Исключения:: NumberFormatException — если in не является допустимым представлением BigDecimal или заданный подмассив не целиком входит в in.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(char[] in, int offset, int len, MathContext mc)

Примечание по реализации:: Если последовательность символов уже доступна в массиве символов, использование этого конструктора быстрее, чем преобразование массива char в строку и использование конструктора BigDecimal(String).
Параметры:: in — массив char, являющийся источником символов.; offset — индекс первого символа массива для проверки.; len — количество рассматриваемых символов.; mc — используемый контекст.
Исключения:: NumberFormatException — если in не является допустимым представлением BigDecimal или заданный подмассив не целиком входит в in.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(char[] in)

Преобразует представление BigDecimal в виде массива символов в BigDecimal, принимая ту же последовательность символов, что и конструктор BigDecimal(String).

Примечание по реализации:: Если последовательность символов уже доступна в виде массива символов, использование этого конструктора быстрее, чем преобразование массива char в строку и использование конструктора BigDecimal(String).
Параметры:: in — массив char, являющийся источником символов.
Исключения:: NumberFormatException — если in не является допустимым представлением BigDecimal.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(char[] in, MathContext mc)

Преобразует представление BigDecimal в виде массива символов в BigDecimal, принимая ту же последовательность символов, что и конструктор BigDecimal(String), и выполняя округление в соответствии с настройками контекста.

Примечание по реализации:: Если последовательность символов уже доступна в виде массива символов, использование этого конструктора быстрее, чем преобразование массива char в строку и использование конструктора BigDecimal(String).
Параметры:: in — массив char, являющийся источником символов.; mc — используемый контекст.
Исключения:: NumberFormatException — если in не является допустимым представлением BigDecimal.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(String val)

Преобразует строковое представление BigDecimal в BigDecimal. Строковое представление состоит из необязательного знака, '+' ( '\u002B') или '-' ('\u002D'), за которым следует последовательность из нуля или более десятичных цифр («целая часть»); после неё могут необязательно следовать дробная часть и показатель степени.

Дробная часть состоит из десятичной точки, за которой следует ноль или более десятичных цифр. Строка должна содержать хотя бы одну цифру в целой или дробной части. Число, образованное знаком, целой и дробной частями, называется значащей частью.

Показатель степени состоит из символа 'e' ('\u0065') или 'E' ('\u0045'), за которым следует одна или более десятичных цифр.

Более формально, строки, принимаемые этим конструктором, описываются следующей грамматикой:

BigDecimalString:

Sign_opt Significand Exponent_opt

Sign:

+
-

Significand:

IntegerPart . FractionPart_opt
. FractionPart
IntegerPart

IntegerPart:

Digits

FractionPart:

Digits

Exponent:

ExponentIndicator SignedInteger

ExponentIndicator:

e
E

SignedInteger:

Sign_opt Digits

Digits:

Digit
Digits Digit

Digit:

любой символ, для которого Character.isDigit(char) возвращает true, включая 0, 1, 2 ...

Масштаб возвращаемого значения BigDecimal будет равен количеству цифр в дробной части или нулю, если строка не содержит десятичной точки, с учётом корректировки на показатель степени; если строка содержит показатель степени, он вычитается из масштаба. Полученное значение масштаба должно находиться в диапазоне от Integer.MIN_VALUE до Integer.MAX_VALUE включительно.

Преобразование символов в цифры выполняется с помощью Character.digit(char, int), установленного для преобразования в систему счисления с основанием 10. Строка не должна содержать посторонних символов (например, пробелов).

Примеры:
Значение возвращаемого BigDecimal равно значащая часть × 10^{показатель степени}. Для каждой строки слева справа показано полученное представление [BigInteger, scale].

"0"            [0,0]
"0.00"         [0,2]
"123"          [123,0]
"-123"         [-123,0]
"1.23E3"       [123,-1]
"1.23E+3"      [123,-1]
"12.3E+7"      [123,-6]
"12.0"         [120,1]
"12.3"         [123,1]
"0.00123"      [123,5]
"-1.23E-12"    [-123,14]
"1234.5E-4"    [12345,5]
"0E+7"         [0,-7]
"-0"           [0,0]

Примечание к API:: Для значений, отличных от float и double NaN и ±Infinity, этот конструктор совместим со значениями, возвращаемыми методами Float.toString(float) и Double.toString(double). Как правило, это предпочтительный способ преобразования float или double в BigDecimal, поскольку он не страдает от непредсказуемости конструктора BigDecimal(double).
Параметры:: val — строковое представление BigDecimal.
Исключения:: NumberFormatException — если val не является допустимым представлением BigDecimal.

BigDecimal

public BigDecimal(String val, MathContext mc)

Преобразует строковое представление BigDecimal в BigDecimal, принимая те же строки, что и конструктор BigDecimal(String), и выполняя округление в соответствии с настройками контекста.

Параметры:: val — строковое представление BigDecimal.; mc — используемый контекст.
Исключения:: NumberFormatException — если val не является допустимым представлением BigDecimal.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(double val)

Преобразует double в BigDecimal, являющийся точным десятичным представлением двоичного числа с плавающей точкой double. Масштаб возвращаемого BigDecimal — наименьшее значение, при котором (10^scale × val) является целым числом.

Примечания:

Результаты этого конструктора могут быть несколько непредсказуемыми. Можно предположить, что запись new BigDecimal(0.1) в Java создаёт BigDecimal, точно равный 0.1 (немасштабированное значение 1 с масштабом 1), однако фактически он равен 0.1000000000000000055511151231257827021181583404541015625. Это происходит потому, что 0.1 нельзя представить точно в виде double (или, впрочем, в виде двоичной дроби любой конечной длины). Таким образом, значение, передаваемое в конструктор, не равно точно 0.1, несмотря на кажущееся обратное.
Конструктор String, напротив, полностью предсказуем: запись new BigDecimal("0.1") создаёт BigDecimal, который точно равен 0.1, как и следовало ожидать. Поэтому обычно рекомендуется предпочитать ему конструктор String.
Если double необходимо использовать как источник для BigDecimal, учтите, что этот конструктор выполняет точное преобразование; его результат не совпадает с результатом преобразования double в String с помощью метода Double.toString(double) и последующего использования конструктора BigDecimal(String). Чтобы получить такой результат, используйте метод static valueOf(double).

Параметры:: val — значение double, преобразуемое в BigDecimal.
Исключения:: NumberFormatException — если val является бесконечностью или NaN.

BigDecimal

public BigDecimal(double val, MathContext mc)

Преобразует double в BigDecimal, выполняя округление в соответствии с настройками контекста. Масштаб BigDecimal — наименьшее значение, при котором (10^scale × val) является целым числом.

Результаты этого конструктора могут быть несколько непредсказуемыми, поэтому его использование обычно не рекомендуется; см. примечания к конструктору BigDecimal(double).

Параметры:: val — значение double, преобразуемое в BigDecimal.; mc — используемый контекст.
Исключения:: NumberFormatException — если val является бесконечностью или NaN.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(BigInteger val)

Преобразует BigInteger в BigDecimal. Масштаб BigDecimal равен нулю.

Параметры:: val — значение BigInteger, преобразуемое в BigDecimal.

BigDecimal

public BigDecimal(BigInteger val, MathContext mc)

Преобразует BigInteger в BigDecimal, выполняя округление в соответствии с настройками контекста. Масштаб BigDecimal равен нулю.

Параметры:: val — значение BigInteger, преобразуемое в BigDecimal.; mc — используемый контекст.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(BigInteger unscaledVal, int scale)

Преобразует немасштабированное значение BigInteger и масштаб int в BigDecimal. Значение BigDecimal равно (unscaledVal × 10^-scale).

Параметры:: unscaledVal — немасштабированное значение BigDecimal.; scale — масштаб BigDecimal.

BigDecimal

public BigDecimal(BigInteger unscaledVal, int scale, MathContext mc)

Преобразует немасштабированное значение BigInteger и масштаб int в BigDecimal, выполняя округление в соответствии с настройками контекста. Значение BigDecimal равно

(unscaledVal ×
10^-scale)

с округлением согласно настройкам точности и режима округления precision.

Параметры:: unscaledVal — немасштабированное значение BigDecimal.; scale — масштаб BigDecimal.; mc — используемый контекст.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(int val)

Преобразует int в BigDecimal. Масштаб BigDecimal равен нулю.

Параметры:: val — значение int, преобразуемое в BigDecimal.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(int val, MathContext mc)

Преобразует int в BigDecimal, выполняя округление в соответствии с настройками контекста. Масштаб BigDecimal до округления равен нулю.

Параметры:: val — значение int, преобразуемое в BigDecimal.; mc — используемый контекст.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(long val)

Преобразует long в BigDecimal. Масштаб BigDecimal равен нулю.

Параметры:: val — значение long, преобразуемое в BigDecimal.
Начиная с версии:: 1.5

BigDecimal

public BigDecimal(long val, MathContext mc)

Преобразует long в BigDecimal, выполняя округление в соответствии с настройками контекста. Масштаб BigDecimal до округления равен нулю.

Параметры:: val — значение long, преобразуемое в BigDecimal.; mc — используемый контекст.
Начиная с версии:: 1.5

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

valueOf

public static BigDecimal valueOf(long unscaledVal, int scale)

Преобразует немасштабированное значение long и масштаб int в BigDecimal.

Примечание к API:: Этот статический фабричный метод рекомендуется вместо конструктора (long, int), поскольку позволяет повторно использовать часто встречающиеся значения BigDecimal.
Параметры:: unscaledVal — немасштабированное значение BigDecimal.; scale — масштаб BigDecimal.
Возвращает:: BigDecimal, значение которого равно (unscaledVal × 10^-scale).

valueOf

public static BigDecimal valueOf(long val)

Преобразует значение long в BigDecimal с масштабом 0.

Примечание к API:: Этот статический фабричный метод рекомендуется вместо конструктора (long), поскольку позволяет повторно использовать часто встречающиеся значения BigDecimal.
Параметры:: val — значение BigDecimal.
Возвращает:: BigDecimal, значение которого равно val.

valueOf

public static BigDecimal valueOf(double val)

Преобразует double в BigDecimal, используя каноническое строковое представление double, предоставляемое методом Double.toString(double).

Примечание к API:: Как правило, это предпочтительный способ преобразования double в BigDecimal, поскольку возвращаемое значение равно результату создания BigDecimal из результата вызова Double.toString(double).
Хотя аргумент float v можно передать этому методу, результат часто содержит намного больше завершающих цифр, чем точность float. Рассмотрите возможность использования вместо него new BigDecimal(Float.toString(v)).
Параметры:: val — значение double, преобразуемое в BigDecimal.
Возвращает:: BigDecimal, значение которого равно или приблизительно равно значению val.
Исключения:: NumberFormatException — если val является бесконечностью или NaN.
Начиная с версии:: 1.5

add

public BigDecimal add(BigDecimal augend)

Возвращает BigDecimal со значением

(this +
augend)

и масштабом

max(this.scale(),
augend.scale())

Параметры:: augend — значение, которое нужно прибавить к этому BigDecimal.
Возвращает:: this + augend

add

public BigDecimal add(BigDecimal augend, MathContext mc)

Возвращает BigDecimal со значением (this + augend), выполняя округление в соответствии с настройками контекста. Если одно из чисел равно нулю и задана ненулевая точность, результатом становится другое число, при необходимости округлённое.

Параметры:: augend — значение, которое нужно прибавить к этому BigDecimal.; mc — используемый контекст.
Возвращает:: this + augend, при необходимости округлённое.
Начиная с версии:: 1.5

subtract

public BigDecimal subtract(BigDecimal subtrahend)

Возвращает BigDecimal со значением

(this -
subtrahend)

и масштабом

max(this.scale(),
subtrahend.scale())

Параметры:: subtrahend — значение, которое нужно вычесть из этого BigDecimal.
Возвращает:: this - subtrahend

subtract

public BigDecimal subtract(BigDecimal subtrahend, MathContext mc)

Возвращает BigDecimal со значением (this - subtrahend), выполняя округление в соответствии с настройками контекста. Если subtrahend равно нулю, результатом становится это значение, при необходимости округлённое. Если это значение равно нулю, результатом становится subtrahend.negate(mc).

Параметры:: subtrahend — значение, которое нужно вычесть из этого BigDecimal.; mc — используемый контекст.
Возвращает:: this - subtrahend, при необходимости округлённое.
Начиная с версии:: 1.5

multiply

public BigDecimal multiply(BigDecimal multiplicand)

Возвращает BigDecimal со значением

(this ×
multiplicand)

и масштабом

(this.scale() +
multiplicand.scale())

Параметры:: multiplicand — значение, на которое умножается этот BigDecimal.
Возвращает:: this * multiplicand

multiply

public BigDecimal multiply(BigDecimal multiplicand, MathContext mc)

Возвращает BigDecimal со значением

(this ×
multiplicand)

, округлённым согласно настройкам контекста.

Параметры:: multiplicand — значение, на которое умножается этот BigDecimal.; mc — используемый контекст.
Возвращает:: this * multiplicand, при необходимости округлённое.
Начиная с:: 1.5

divide

@Deprecated(since="9") public BigDecimal divide(BigDecimal divisor, int scale, int roundingMode)

Устарело.

Вместо этого устаревшего метода следует использовать метод divide(BigDecimal, int, RoundingMode).

Возвращает BigDecimal со значением

(this /
divisor)

и заданным масштабом. Если для получения результата с заданным масштабом необходимо выполнить округление, применяется указанный режим округления.

Параметры:

divisor — значение, на которое делится этот BigDecimal.

scale — масштаб возвращаемого частного BigDecimal.

roundingMode — применяемый режим округления.

Возвращает:

this / divisor

Исключения:

ArithmeticException — если divisor равно нулю, roundingMode==ROUND_UNNECESSARY, а указанного масштаба недостаточно для точного представления результата деления.

IllegalArgumentException — если roundingMode не соответствует допустимому режиму округления.

См. также:

divide

public BigDecimal divide(BigDecimal divisor, int scale, RoundingMode roundingMode)

Возвращает BigDecimal со значением

(this /
divisor)

Параметры:: divisor — значение, на которое делится этот BigDecimal.; scale — масштаб возвращаемого частного BigDecimal.; roundingMode — применяемый режим округления.
Возвращает:: this / divisor
Исключения:: ArithmeticException — если divisor равно нулю, roundingMode==RoundingMode.UNNECESSARY, а указанного масштаба недостаточно для точного представления результата деления.
Начиная с:: 1.5

divide

@Deprecated(since="9") public BigDecimal divide(BigDecimal divisor, int roundingMode)

Устарело.

Вместо этого устаревшего метода следует использовать метод divide(BigDecimal, RoundingMode).

Возвращает BigDecimal со значением

(this /
divisor)

и масштабом this.scale(). Если для получения результата с заданным масштабом необходимо выполнить округление, применяется указанный режим округления.

Параметры:

divisor — значение, на которое делится этот BigDecimal.

roundingMode — применяемый режим округления.

Возвращает:

this / divisor

Исключения:

ArithmeticException — если divisor==0 или roundingMode==ROUND_UNNECESSARY, а this.scale() недостаточно для точного представления результата деления.

IllegalArgumentException — если roundingMode не соответствует допустимому режиму округления.

См. также:

divide

public BigDecimal divide(BigDecimal divisor, RoundingMode roundingMode)

Возвращает BigDecimal со значением

(this /
divisor)

Параметры:: divisor — значение, на которое делится этот BigDecimal.; roundingMode — применяемый режим округления.
Возвращает:: this / divisor
Исключения:: ArithmeticException — если divisor==0 или roundingMode==RoundingMode.UNNECESSARY, а this.scale() недостаточно для точного представления результата деления.
Начиная с:: 1.5

divide

public BigDecimal divide(BigDecimal divisor)

Возвращает BigDecimal со значением

(this /
divisor)

и предпочтительным масштабом

(this.scale() -
divisor.scale())

; если точное частное невозможно представить (из-за бесконечной десятичной дроби), выбрасывается ArithmeticException.

Параметры:: divisor — значение, на которое делится этот BigDecimal.
Возвращает:: this / divisor
Исключения:: ArithmeticException — если точное частное не имеет конечного десятичного представления, в том числе при делении на ноль
Начиная с:: 1.5

divide

public BigDecimal divide(BigDecimal divisor, MathContext mc)

Возвращает BigDecimal со значением

(this /
divisor)

, округлённым согласно настройкам контекста.

Параметры:: divisor — значение, на которое делится этот BigDecimal.; mc — используемый контекст.
Возвращает:: this / divisor, при необходимости округлённое.
Исключения:: ArithmeticException — если результат является неточным, но режим округления — UNNECESSARY или mc.precision == 0, а частное представляет собой бесконечную десятичную дробь, в том числе при делении на ноль
Начиная с:: 1.5

divideToIntegralValue

public BigDecimal divideToIntegralValue(BigDecimal divisor)

Возвращает BigDecimal, значение которого равно целой части частного (this / divisor), округлённой вниз. Предпочтительный масштаб результата —

(this.scale() -
divisor.scale())

Параметры:: divisor — значение, на которое делится этот BigDecimal.
Возвращает:: Целую часть this / divisor.
Исключения:: ArithmeticException — если divisor==0
Начиная с:: 1.5

divideToIntegralValue

public BigDecimal divideToIntegralValue(BigDecimal divisor, MathContext mc)

Возвращает BigDecimal, значение которого равно целой части (this / divisor). Поскольку целая часть точного частного не зависит от режима округления, режим округления не влияет на значения, возвращаемые этим методом. Предпочтительный масштаб результата — (this.scale() - divisor.scale()). Выбрасывается ArithmeticException, если для целой части точного частного требуется более mc.precision цифр.

Параметры:: divisor — значение, на которое делится этот BigDecimal.; mc — используемый контекст.
Возвращает:: Целую часть this / divisor.
Исключения:: ArithmeticException — если divisor==0; ArithmeticException — если mc.precision > 0 и для результата требуется точность более чем в mc.precision цифр.
Начиная с:: 1.5

remainder

public BigDecimal remainder(BigDecimal divisor)

Возвращает BigDecimal со значением (this % divisor).

Остаток определяется выражением this.subtract(this.divideToIntegralValue(divisor).multiply(divisor)). Обратите внимание, что это не операция вычисления остатка по модулю (результат может быть отрицательным).

Параметры:: divisor — значение, на которое делится этот BigDecimal.
Возвращает:: this % divisor.
Исключения:: ArithmeticException — если divisor==0
Начиная с:: 1.5

remainder

public BigDecimal remainder(BigDecimal divisor, MathContext mc)

Возвращает BigDecimal со значением

(this %
divisor)

, округлённым согласно настройкам контекста. Настройки MathContext влияют на неявное деление, используемое для вычисления остатка. Само вычисление остатка по определению является точным. Поэтому остаток может содержать более mc.getPrecision() цифр.

Остаток определяется выражением this.subtract(this.divideToIntegralValue(divisor, mc).multiply(divisor)). Обратите внимание, что это не операция вычисления остатка по модулю (результат может быть отрицательным).

Параметры:

divisor — значение, на которое делится этот BigDecimal.

mc — используемый контекст.

Возвращает:

this % divisor, при необходимости округлённое.

Исключения:

ArithmeticException — если divisor==0

ArithmeticException — если результат является неточным, но режим округления — UNNECESSARY, или mc.precision > 0 и для результата this.divideToIntegralValue(divisor) требуется точность более чем в mc.precision цифр.

Начиная с:

1.5

См. также:

divideAndRemainder

public BigDecimal[] divideAndRemainder(BigDecimal divisor)

Возвращает массив BigDecimal из двух элементов, содержащий результат divideToIntegralValue, за которым следует результат remainder для двух операндов.

Обратите внимание: если нужны и целое частное, и остаток, этот метод работает быстрее, чем отдельные вызовы методов divideToIntegralValue и remainder, поскольку деление выполняется только один раз.

Параметры:

divisor — значение, на которое делится этот BigDecimal и для которого вычисляется остаток.

Возвращает:

массив BigDecimal из двух элементов: частное (результат divideToIntegralValue) находится в первом элементе, а остаток — в последнем.

Исключения:

ArithmeticException — если divisor==0

Начиная с:

1.5

См. также:

divideAndRemainder

public BigDecimal[] divideAndRemainder(BigDecimal divisor, MathContext mc)

Возвращает массив BigDecimal из двух элементов, содержащий результат divideToIntegralValue, за которым следует результат remainder для двух операндов, вычисленные с округлением согласно настройкам контекста.

Параметры:

divisor — значение, на которое делится этот BigDecimal и для которого вычисляется остаток.

mc — используемый контекст.

Возвращает:

Исключения:

ArithmeticException — если divisor==0

Начиная с:

1.5

См. также:

sqrt

public BigDecimal sqrt(MathContext mc)

Возвращает приближённое значение квадратного корня из this, округлённое согласно настройкам контекста.

Предпочтительный масштаб возвращаемого результата равен Math.ceilDiv(this.scale(), 2). Значение возвращаемого результата всегда отличается от точного десятичного значения для заданной точности не более чем на одну единицу последнего разряда. Если режим округления — HALF_UP, HALF_DOWN или HALF_EVEN, результат отличается от точного десятичного значения не более чем на половину единицы последнего разряда.

Особый случай:

Квадратный корень числа, численно равного ZERO, численно равен ZERO и имеет предпочтительный масштаб, определяемый приведённым выше общим правилом. В частности, для ZERO значение ZERO.sqrt(mc).equals(ZERO) истинно при любом MathContext в качестве аргумента.

Параметры:

mc — используемый контекст.

Возвращает:

квадратный корень из this.

Исключения:

ArithmeticException — если this меньше нуля.

ArithmeticException — если запрошен точный результат (mc.getPrecision()==0), но точный результат не имеет конечного десятичного представления

ArithmeticException — если (mc.getRoundingMode()==RoundingMode.UNNECESSARY), а точный результат не умещается в mc.getPrecision() цифр.

Начиная с:

См. также:

rootn

public BigDecimal rootn(int n, MathContext mc)

Возвращает приближённое значение корня n^-й степени из this, округлённое согласно настройкам контекста.

Предпочтительный масштаб возвращаемого результата равен Math.ceilDiv(this.scale(), n). Значение возвращаемого результата всегда отличается от точного десятичного значения для заданной точности не более чем на одну единицу последнего разряда. Если режим округления — HALF_UP, HALF_DOWN или HALF_EVEN, результат отличается от точного десятичного значения не более чем на половину единицы последнего разряда.

Особый случай:

Корень n^-й степени из числа, численно равного ZERO, численно равен ZERO и имеет предпочтительный масштаб, определяемый приведённым выше общим правилом. В частности, для ZERO значение ZERO.rootn(n, mc).equals(ZERO) истинно при любом MathContext в качестве аргумента.

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

Обратите внимание, что вызов rootn(2, mc) эквивалентен вызову sqrt(mc).

Параметры:

n — степень корня

mc — используемый контекст.

Возвращает:

корень n^-й степени из this.

Исключения:

ArithmeticException — если n == 0 || n == Integer.MIN_VALUE.

ArithmeticException — если n чётное, а this отрицательное.

ArithmeticException — если n отрицательное, а this равно нулю.

ArithmeticException — если запрошен точный результат (mc.getPrecision() == 0), но точный результат не имеет конечного десятичного представления

ArithmeticException — если (mc.getRoundingMode() == RoundingMode.UNNECESSARY), а точный результат не умещается в mc.getPrecision() цифр.

Начиная с:

См. также:

pow

public BigDecimal pow(int n)

Возвращает BigDecimal со значением (thisⁿ). Степень вычисляется точно, с неограниченной точностью.

Параметр n должен находиться в диапазоне от 0 до 999999999 включительно. ZERO.pow(0) возвращает ONE. Обратите внимание, что в будущих версиях допустимый диапазон показателя степени для этого метода может быть расширен.

Параметры:: n — показатель степени, в которую возводится этот BigDecimal.
Возвращает:: thisⁿ
Исключения:: ArithmeticException — если n находится вне допустимого диапазона.
Начиная с:: 1.5

pow

public BigDecimal pow(int n, MathContext mc)

Возвращает BigDecimal со значением (thisⁿ). В текущей реализации используется основной алгоритм, определённый стандартом ANSI X3.274-1996, с округлением согласно настройкам контекста. В общем случае возвращаемое числовое значение отличается от точного числового значения для выбранной точности не более чем на две единицы последнего разряда. Обратите внимание, что в будущих версиях может использоваться другой алгоритм с уменьшенной допустимой погрешностью и расширенным допустимым диапазоном показателя степени.

Алгоритм X3.274-1996:

Выбрасывается исключение ArithmeticException, если
- abs(n) > 999999999
- mc.precision == 0 и n < 0
- mc.precision > 0 и n содержит более mc.precision десятичных цифр
если n равно нулю, возвращается ONE, даже если this равно нулю; в противном случае
- если n положительно, результат вычисляется методом последовательного возведения в квадрат с накоплением в одном аккумуляторе. Для отдельных умножений на аккумулятор используются те же настройки математического контекста, что и в mc, за исключением точности, увеличенной до mc.precision + elength + 1, где elength — число десятичных цифр в n.
- если n отрицательно, результат вычисляется так, как если бы n было положительным; затем единица делится на это значение с указанной выше рабочей точностью.
- Итоговое значение для положительного или отрицательного случая округляется до требуемой точности.

Параметры:: n — показатель степени, в которую возводится этот BigDecimal.; mc — используемый контекст.
Возвращает:: thisⁿ с использованием алгоритма стандарта ANSI X3.274-1996
Исключения:: ArithmeticException — если результат является неточным, но режим округления — UNNECESSARY, или n находится вне допустимого диапазона.
Начиная с:: 1.5

abs

public BigDecimal abs()

Возвращает BigDecimal, значение которого равно абсолютному значению этого BigDecimal, а масштаб равен this.scale().

Возвращает:: abs(this)

abs

public BigDecimal abs(MathContext mc)

Возвращает BigDecimal, значение которого равно абсолютному значению этого BigDecimal, округлённому согласно настройкам контекста.

Параметры:: mc — используемый контекст.
Возвращает:: abs(this), при необходимости округлённое.
Начиная с:: 1.5

negate

public BigDecimal negate()

Возвращает BigDecimal со значением (-this) и масштабом this.scale().

Возвращает:: -this.

negate

public BigDecimal negate(MathContext mc)

Возвращает BigDecimal со значением (-this), округлённым согласно настройкам контекста.

Параметры:: mc — используемый контекст.
Возвращает:: -this, при необходимости округлённое.
Начиная с:: 1.5

plus

public BigDecimal plus()

Возвращает BigDecimal со значением (+this) и масштабом this.scale().

Этот метод, который просто возвращает этот BigDecimal, включён для симметрии с унарным оператором минус — методом negate().

Возвращает:

this.

Начиная с:

1.5

См. также:

plus

public BigDecimal plus(MathContext mc)

Возвращает BigDecimal со значением (+this), округлённым согласно настройкам контекста.

Этот метод действует так же, как метод round(MathContext).

Параметры:

mc — используемый контекст.

Возвращает:

this, при необходимости округлённое. Масштаб нулевого результата будет равен 0.

Начиная с:

1.5

См. также:

signum

public int signum()

Возвращает значение знаковой функции для этого BigDecimal.

Возвращает:: -1, 0 или 1, если значение этого BigDecimal отрицательно, равно нулю или положительно соответственно.

scale

public int scale()

Возвращает масштаб этого BigDecimal. Если масштаб равен нулю или положителен, он соответствует числу цифр справа от десятичной точки. Если масштаб отрицателен, немасштабированное значение числа умножается на десять в степени, равной противоположному значению масштаба. Например, масштаб -3 означает, что немасштабированное значение умножается на 1000.

Возвращает:: масштаб этого BigDecimal.

precision

public int precision()

Возвращает точность этого BigDecimal. (Точность — это число цифр в немасштабированном значении.)

Точность нулевого значения равна 1.

Возвращает:: точность этого BigDecimal.
Начиная с:: 1.5

unscaledValue

public BigInteger unscaledValue()

Возвращает BigInteger, значение которого равно немасштабированному значению этого BigDecimal. (Вычисляет

(this *
10^this.scale())

Возвращает:: немасштабированное значение этого BigDecimal.
Начиная с:: 1.2

round

public BigDecimal round(MathContext mc)

Возвращает BigDecimal, округлённое согласно настройкам MathContext. Если точность равна 0, округление не выполняется.

Этот метод действует так же, как метод plus(MathContext).

Параметры:

mc — используемый контекст.

Возвращает:

BigDecimal, округлённое согласно настройкам MathContext.

Начиная с:

1.5

См. также:

setScale

public BigDecimal setScale(int newScale, RoundingMode roundingMode)

Возвращает BigDecimal с указанным масштабом и немасштабированным значением, полученным умножением или делением немасштабированного значения этого BigDecimal на соответствующую степень десяти для сохранения общего значения. Если в результате операции масштаб уменьшается, немасштабированное значение необходимо разделить (а не умножить), и значение может измениться; в этом случае к результату деления применяется указанный режим округления.

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

Поскольку объекты BigDecimal неизменяемы, вызовы этого метода не изменяют исходный объект, вопреки обычному соглашению, согласно которому методы с именем setX изменяют поле X. Вместо этого setScale возвращает объект с нужным масштабом; возвращаемый объект может быть как новым, так и уже существовавшим.

Параметры:

newScale — масштаб возвращаемого значения BigDecimal.

roundingMode — применяемый режим округления.

Возвращает:

BigDecimal с указанным масштабом и немасштабированным значением, полученным умножением или делением немасштабированного значения этого BigDecimal на соответствующую степень десяти для сохранения общего значения.

Исключения:

ArithmeticException — если roundingMode==UNNECESSARY и для указанного изменения масштаба требуется округление.

Начиная с:

1.5

См. также:

setScale

@Deprecated(since="9") public BigDecimal setScale(int newScale, int roundingMode)

Устарело.

Вместо этого устаревшего метода следует использовать метод setScale(int, RoundingMode).

Возвращает BigDecimal с указанным масштабом, значение без масштаба которого определяется умножением или делением значения без масштаба этого BigDecimal на соответствующую степень десяти для сохранения общего значения. Если в результате операции масштаб уменьшается, значение без масштаба необходимо разделить (а не умножить), и значение может измениться; в этом случае к делению применяется указанный режим округления.

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

Поскольку объекты BigDecimal неизменяемы, вызовы этого метода не приводят к изменению исходного объекта, вопреки обычному соглашению, согласно которому методы с именами setX изменяют поле X. Вместо этого setScale возвращает объект с нужным масштабом; возвращённый объект может быть как новым, так и уже существовавшим.

Параметры:

newScale — масштаб возвращаемого значения BigDecimal.

roundingMode — применяемый режим округления.

Возвращает:

BigDecimal с указанным масштабом, значение без масштаба которого определяется умножением или делением значения без масштаба этого BigDecimal на соответствующую степень десяти для сохранения общего значения.

Вызывает:

ArithmeticException — если roundingMode==ROUND_UNNECESSARY и указанная операция изменения масштаба требует округления.

IllegalArgumentException — если roundingMode не соответствует допустимому режиму округления.

См. также:

setScale

public BigDecimal setScale(int newScale)

Возвращает BigDecimal с указанным масштабом и значением, численно равным значению этого BigDecimal. Вызывает ArithmeticException, если это невозможно.

Этот вызов обычно используется для увеличения масштаба; в этом случае гарантируется существование BigDecimal с указанным масштабом и правильным значением. Вызов также можно использовать для уменьшения масштаба, если вызывающий код знает, что BigDecimal имеет достаточно нулей в конце дробной части (то есть множителей десяти в его целом значении), чтобы изменить масштаб без изменения значения.

Этот метод возвращает тот же результат, что и версии setScale с двумя аргументами, но избавляет вызывающий код от необходимости указывать режим округления в случаях, когда он не имеет значения.

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

Поскольку объекты BigDecimal неизменяемы, вызовы этого метода не приводят к изменению исходного объекта, вопреки обычному соглашению, согласно которому методы с именами setX изменяют поле X. Вместо этого setScale возвращает объект с нужным масштабом; возвращённый объект может быть как новым, так и уже существовавшим.

Параметры:

newScale — масштаб возвращаемого значения BigDecimal.

Возвращает:

Вызывает:

ArithmeticException — если указанная операция изменения масштаба требует округления.

См. также:

movePointLeft

public BigDecimal movePointLeft(int n)

Возвращает BigDecimal, эквивалентное этому значению, но с десятичной точкой, сдвинутой влево на n разрядов. Если n неотрицательно, вызов просто прибавляет n к масштабу. Если n отрицательно, вызов эквивалентен movePointRight(-n). Возвращаемое этим вызовом BigDecimal имеет значение

(this ×
10^-n)

и масштаб

max(this.scale()+n,
0)

Параметры:: n — число разрядов, на которое нужно сдвинуть десятичную точку влево.
Возвращает:: BigDecimal, эквивалентное этому значению, но с десятичной точкой, сдвинутой влево на n разрядов.
Вызывает:: ArithmeticException — при переполнении масштаба.

movePointRight

public BigDecimal movePointRight(int n)

Возвращает BigDecimal, эквивалентное этому значению, но с десятичной точкой, сдвинутой вправо на n разрядов. Если n неотрицательно, вызов просто вычитает n из масштаба. Если n отрицательно, вызов эквивалентен movePointLeft(-n). Возвращаемое этим вызовом BigDecimal имеет значение

(this
× 10ⁿ)

и масштаб

max(this.scale()-n,
0)

Параметры:: n — число разрядов, на которое нужно сдвинуть десятичную точку вправо.
Возвращает:: BigDecimal, эквивалентное этому значению, но с десятичной точкой, сдвинутой вправо на n разрядов.
Вызывает:: ArithmeticException — при переполнении масштаба.

scaleByPowerOfTen

public BigDecimal scaleByPowerOfTen(int n)

Возвращает BigDecimal, числовое значение которого равно (this * 10ⁿ). Масштаб результата равен (this.scale() - n).

Параметры:: n — показатель степени десяти, на который нужно умножить значение
Возвращает:: BigDecimal, числовое значение которого равно (this * 10ⁿ)
Вызывает:: ArithmeticException — если масштаб выходит за пределы диапазона 32-разрядного целого числа.
Начиная с версии:: 1.5

stripTrailingZeros

public BigDecimal stripTrailingZeros()

Возвращает BigDecimal, численно равное этому значению, но без конечных нулей в представлении. Например, удаление конечных нулей из значения BigDecimal 600.0, компоненты [BigInteger, scale] которого равны [6000, 1], даёт 6E2 с компонентами [BigInteger, scale], равными [6, -2]. Если это BigDecimal численно равно нулю, возвращается BigDecimal.ZERO.

Возвращает:: численно равное BigDecimal без конечных нулей.
Вызывает:: ArithmeticException — при переполнении масштаба.
Начиная с версии:: 1.5

compareTo

public int compareTo(BigDecimal val)

Сравнивает это BigDecimal численно с указанным BigDecimal. Два объекта BigDecimal с одинаковыми значениями, но разными масштабами (например, 2.0 и 2.00), считаются равными этим методом. Такие значения относятся к одной когорте. Этот метод предпочтительнее отдельных методов для каждого из шести операторов сравнения булевых значений (<, ==, >, >=, !=, <=). Рекомендуемый способ выполнения таких сравнений:


(x.compareTo(y)

<op> 0), где <op> — один из шести операторов сравнения.

Определён в:: compareTo в интерфейсе Comparable<BigDecimal>
Примечание API:: Обратите внимание: естественный порядок сравнения в этом классе несовместим с equals. Поведение при сравнении результата этого метода с 0 на равенство аналогично проверке численного равенства значений double.
Параметры:: val — BigDecimal, с которым сравнивается это BigDecimal.
Возвращает:: -1, 0 или 1, если это BigDecimal численно меньше, равно или больше val.

equals

public boolean equals(Object x)

Сравнивает это BigDecimal с указанным


Object

на равенство. В отличие от compareTo, этот метод считает два объекта BigDecimal равными, только если их значения и масштабы совпадают. Поэтому 2.0 не равно 2.00 при сравнении этим методом: компоненты [BigInteger, scale] первого равны [20, 1], а компоненты второго — [200, 2].

Переопределяет:

equals в классе Object

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

Пример того, что 2.0 и 2.00 не взаимозаменяемы при некоторых арифметических операциях, — два выражения:

new BigDecimal("2.0" ).divide(BigDecimal.valueOf(3),
HALF_UP)

, результатом которого является 0.7, и

new BigDecimal("2.00").divide(BigDecimal.valueOf(3),
HALF_UP)

, результатом которого является 0.67. Поведение этого метода аналогично проверке эквивалентности представления значений double.

Параметры:

x — Object, с которым сравнивается это BigDecimal.

Возвращает:

true тогда и только тогда, когда указанный Object является BigDecimal, значение и масштаб которого совпадают со значением и масштабом этого BigDecimal.

См. также:

min

public BigDecimal min(BigDecimal val)

Возвращает минимум из этого BigDecimal и val.

Параметры:

val — значение, с которым вычисляется минимум.

Возвращает:

BigDecimal, значение которого меньше из значений этого BigDecimal и val. Если значения равны, согласно методу compareTo, возвращается this.

См. также:

max

public BigDecimal max(BigDecimal val)

Возвращает максимум из этого BigDecimal и val.

Параметры:

val — значение, с которым вычисляется максимум.

Возвращает:

BigDecimal, значение которого больше из значений этого BigDecimal и val. Если значения равны, согласно методу compareTo, возвращается this.

См. также:

hashCode

public int hashCode()

Возвращает хеш-код этого BigDecimal. Хеш-код вычисляется на основе значения без масштаба и масштаба этого BigDecimal.

Переопределяет:

hashCode в классе Object

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

Два объекта BigDecimal, численно равные, но имеющие разные масштабы (например, 2.0 и 2.00), обычно не будут иметь одинаковые хеш-коды.

Возвращает:

хеш-код этого BigDecimal.

См. также:

toString

public String toString()

Возвращает строковое представление этого BigDecimal, используя научную нотацию, если требуется показатель степени.

Стандартная каноническая строковая форма BigDecimal формируется следующим образом: сначала абсолютное значение значения без масштаба BigDecimal преобразуется в строку в десятичной системе с использованием символов от '0' до '9' без ведущих нулей (кроме случая, когда значение равно нулю: тогда используется один символ '0').

Затем вычисляется скорректированный показатель степени: это значение, равное отрицательному масштабу плюс число символов в преобразованном значении без масштаба минус один. Иными словами, -scale+(ulength-1), где ulength — длина абсолютного значения значения без масштаба в десятичных цифрах (его точность).

Если масштаб больше или равен нулю, а скорректированный показатель степени больше или равен -6, число преобразуется в строку без экспоненциальной нотации. В этом случае, если масштаб равен нулю, десятичная точка не добавляется; если масштаб положителен, десятичная точка вставляется так, чтобы масштаб определял число символов справа от неё. При необходимости слева от преобразованного значения без масштаба добавляются символы '0'. Если после этой вставки перед десятичной точкой нет символа, в начало добавляется стандартный символ '0'.

В противном случае (то есть если масштаб отрицателен или скорректированный показатель степени меньше -6) число преобразуется в строку с использованием экспоненциальной нотации. В этом случае, если преобразованное BigInteger содержит больше одной цифры, после первой цифры вставляется десятичная точка. Затем к преобразованному значению без масштаба (возможно, с вставленной десятичной точкой) добавляется показатель степени в строковом представлении: буква 'E', за которой непосредственно следует скорректированный показатель степени в строковом представлении. Последний записывается в десятичной системе с использованием символов от '0' до '9' без ведущих нулей; перед ним всегда ставится знак '-' ('\u002D'), если скорректированный показатель степени отрицателен, и '+' ('\u002B') в противном случае.

Наконец, если значение без масштаба меньше нуля, перед всей строкой ставится знак минус '-' ('\u002D'). Если значение без масштаба равно нулю или положительно, знак не ставится.

Примеры:

Для каждого представления [значение без масштаба, масштаб] слева справа показана результирующая строка.

[123,0]      "123"
[-123,0]     "-123"
[123,-1]     "1.23E+3"
[123,-3]     "1.23E+5"
[123,1]      "12.3"
[123,5]      "0.00123"
[123,10]     "1.23E-8"
[-123,12]    "-1.23E-10"

Примечания:

Между различимыми значениями BigDecimal и результатом этого преобразования существует взаимно однозначное соответствие. Иными словами, каждое различимое значение BigDecimal (значение без масштаба и масштаб) имеет уникальное строковое представление, получаемое с помощью toString. Если преобразовать эту строку обратно в BigDecimal с помощью конструктора BigDecimal(String), исходное значение будет восстановлено.
Строка для заданного числа всегда одинакова и не зависит от локали. Это означает, что её можно использовать как каноническое строковое представление для обмена десятичными данными или как ключ в Hashtable и т. д. Форматирование и разбор чисел с учётом локали выполняются классом NumberFormat и его подклассами.
Метод toEngineeringString() можно использовать для отображения чисел с показателями степени в инженерной нотации, а метод setScale — для округления BigDecimal до заданного числа цифр после десятичной точки.
Используется соответствие цифр символам, предоставляемое Character.forDigit.

Переопределяет:

toString в классе Object

Возвращает:

строковое представление этого BigDecimal.

См. также:

toEngineeringString

public String toEngineeringString()

Возвращает строковое представление этого BigDecimal, используя инженерную нотацию, если требуется показатель степени.

Возвращает строку, представляющую BigDecimal, как описано в методе toString(), за исключением того, что при использовании экспоненциальной нотации степень десяти корректируется до кратного трём значения (инженерная нотация), так чтобы целая часть ненулевых значений находилась в диапазоне от 1 до 999. Если экспоненциальная нотация используется для нулевых значений, добавляются десятичная точка и один или два нулевых разряда дробной части, чтобы сохранить масштаб нулевого значения. Обратите внимание: в отличие от результата toString(), результат этого метода не гарантирует восстановление той же пары [целое значение, масштаб] этого BigDecimal при преобразовании выходной строки обратно в BigDecimal с помощью строкового конструктора. Результат этого метода удовлетворяет менее строгому условию: применение строкового конструктора к результату метода всегда даёт численно равное значение.

Возвращает:: строковое представление этого BigDecimal, использующее инженерную нотацию, если требуется показатель степени.
Начиная с версии:: 1.5

toPlainString

public String toPlainString()

Возвращает строковое представление этого BigDecimal без поля показателя степени. Для значений с положительным масштабом число цифр справа от десятичной точки задаёт масштаб. Для значений с нулевым или отрицательным масштабом результирующая строка формируется так, как если бы значение было преобразовано в численно равное значение с нулевым масштабом и в результат были включены все конечные нули этого значения. Если значение без масштаба меньше нуля, перед всей строкой ставится знак минус '-' ('\u002D'). Если значение без масштаба равно нулю или положительно, знак не ставится. Обратите внимание: если передать результат этого метода в строковый конструктор, будет восстановлено только числовое значение этого BigDecimal; представление нового BigDecimal может иметь другой масштаб. В частности, если масштаб этого BigDecimal отрицателен, строка, полученная этим методом, при обработке строковым конструктором будет иметь нулевой масштаб. (Этот метод ведёт себя аналогично методу toString в версиях 1.4 и более ранних.)

Возвращает:

строковое представление этого BigDecimal без поля показателя степени.

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

1.5

См. также:

toBigInteger

public BigInteger toBigInteger()

Преобразует это BigDecimal в BigInteger. Это преобразование аналогично сужающему примитивному преобразованию из double в long, определённому в Спецификации языка Java: дробная часть этого BigDecimal отбрасывается. Обратите внимание: при этом преобразовании может быть утрачена информация о точности значения BigDecimal.

Чтобы при неточном преобразовании (то есть при отбрасывании ненулевой дробной части) вызывалось исключение, используйте метод toBigIntegerExact().

Возвращает:: это BigDecimal, преобразованное в BigInteger.
См. Спецификацию языка Java:: 5.1.3 Сужающее примитивное преобразование

toBigIntegerExact

public BigInteger toBigIntegerExact()

Преобразует это BigDecimal в BigInteger с проверкой потери информации. Если это BigDecimal имеет ненулевую дробную часть, вызывается исключение.

Возвращает:: это BigDecimal, преобразованное в BigInteger.
Вызывает:: ArithmeticException — если this имеет ненулевую дробную часть.
Начиная с версии:: 1.5

longValue

public long longValue()

Преобразует это BigDecimal в long. Это преобразование аналогично сужающему примитивному преобразованию из double в short, определённому в Спецификации языка Java: дробная часть этого BigDecimal отбрасывается, а если результирующее «BigInteger» слишком велико для представления в long, возвращаются только младшие 64 бита. Обратите внимание: при этом преобразовании может быть утрачена информация об общей величине и точности значения BigDecimal, а также может быть возвращён результат с противоположным знаком.

Определён в:: longValue в классе Number
Возвращает:: это BigDecimal, преобразованное в long.
См. Спецификацию языка Java:: 5.1.3 Сужающее примитивное преобразование

longValueExact

public long longValueExact()

Преобразует это BigDecimal в long с проверкой потери информации. Если это BigDecimal имеет ненулевую дробную часть или выходит за допустимый диапазон результата типа long, вызывается ArithmeticException.

Возвращает:: это BigDecimal, преобразованное в long.
Вызывает:: ArithmeticException — если this имеет ненулевую дробную часть или не помещается в long.
Начиная с версии:: 1.5

intValue

public int intValue()

Преобразует это BigDecimal в int. Это преобразование аналогично сужающему примитивному преобразованию из double в short, определённому в Спецификации языка Java: дробная часть этого BigDecimal отбрасывается, а если результирующее «BigInteger» слишком велико для представления в int, возвращаются только младшие 32 бита. Обратите внимание: при этом преобразовании может быть утрачена информация об общей величине и точности значения BigDecimal, а также может быть возвращён результат с противоположным знаком.

Определён в:: intValue в классе Number
Возвращает:: это BigDecimal, преобразованное в int.
См. Спецификацию языка Java:: 5.1.3 Сужающее примитивное преобразование

intValueExact

public int intValueExact()

Преобразует это BigDecimal в int с проверкой потери информации. Если это BigDecimal имеет ненулевую дробную часть или выходит за допустимый диапазон результата типа int, вызывается ArithmeticException.

Возвращает:: это BigDecimal, преобразованное в int.
Вызывает:: ArithmeticException — если this имеет ненулевую дробную часть или не помещается в int.
Начиная с версии:: 1.5

shortValueExact

public short shortValueExact()

Преобразует это BigDecimal в short с проверкой потери информации. Если это BigDecimal имеет ненулевую дробную часть или выходит за допустимый диапазон результата типа short, вызывается ArithmeticException.

Возвращает:: это BigDecimal, преобразованное в short.
Вызывает:: ArithmeticException — если this имеет ненулевую дробную часть или не помещается в short.
Начиная с версии:: 1.5

byteValueExact

public byte byteValueExact()

Преобразует это BigDecimal в byte с проверкой потери информации. Если это BigDecimal имеет ненулевую дробную часть или выходит за допустимый диапазон результата типа byte, вызывается ArithmeticException.

Возвращает:: это BigDecimal, преобразованное в byte.
Вызывает:: ArithmeticException — если this имеет ненулевую дробную часть или не помещается в byte.
Начиная с версии:: 1.5

floatValue

public float floatValue()

Преобразует это BigDecimal в float. Это преобразование аналогично сужающему примитивному преобразованию из double в float, определённому в Спецификации языка Java: если величина этого BigDecimal слишком велика для представления в виде float, оно преобразуется в Float.NEGATIVE_INFINITY или Float.POSITIVE_INFINITY в зависимости от ситуации. Обратите внимание: даже если возвращаемое значение конечно, при этом преобразовании может быть утрачена информация о точности значения BigDecimal.

Определён в:: floatValue в классе Number
Возвращает:: это BigDecimal, преобразованное в float.
См. Спецификацию языка Java:: 5.1.3 Сужающее примитивное преобразование

doubleValue

public double doubleValue()

Преобразует этот BigDecimal в double. Это преобразование аналогично сужающему преобразованию примитивного типа из double в float, определённому в Спецификации языка Java: если величина этого BigDecimal слишком велика для представления в виде double, оно будет преобразовано в Double.NEGATIVE_INFINITY или Double.POSITIVE_INFINITY в зависимости от ситуации. Обратите внимание, что даже если возвращаемое значение является конечным, это преобразование может привести к потере информации о точности значения BigDecimal.

Определено в:: doubleValue в классе Number
Возвращает:: этот BigDecimal, преобразованный в double.
См. Спецификацию языка Java:: 5.1.3 Сужающее преобразование примитивного типа

ulp

public BigDecimal ulp()

Возвращает размер ulp (единицы последнего разряда) этого BigDecimal. ULP ненулевого значения BigDecimal — это положительное расстояние между этим значением и следующим по величине значением BigDecimal с тем же количеством цифр. ULP нулевого значения численно равен 1 с масштабом this. Результат сохраняется с тем же масштабом, что и this, поэтому результат для нулевых и ненулевых значений равен

[1,
this.scale()]

Возвращает:: размер ulp для this
Начиная с версии:: 1.5

© 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.