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

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

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

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

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

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

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

Операция	Предпочтительный масштаб результата
Сложение	max(масштаб_первого_слагаемого, масштаб_второго_слагаемого)
Вычитание	max(масштаб_уменьшаемого, масштаб_вычитаемого)
Умножение	масштаб_множителя + масштаб_множимого
Деление	масштаб_делимого - масштаб_делителя

Эти масштабы используются методами, возвращающими точные арифметические результаты; за исключением точного деления, которое может потребовать большего масштаба, так как точный результат может иметь больше цифр. Например, 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, созданный из операнда путём перемещения десятичной точки на указанное расстояние в указанном направлении.

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

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

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

См. также:: BigInteger, MathContext, RoundingMode, SortedMap, SortedSet, Сериализованная форма

Поля

Модификатор и тип	Поле и описание
`static BigDecimal`	`ONE` Значение 1 со масштабом 0.
`static int`	`ROUND_CEILING` Режим округления к положительной бесконечности.
`static int`	`ROUND_DOWN` Режим округления к нулю.
`static int`	`ROUND_FLOOR` Режим округления к отрицательной бесконечности.
`static int`	`ROUND_HALF_DOWN` Режим округления к ближайшему соседу, за исключением случаев, когда оба соседа равноудалены, в таком случае округляется вниз.
`static int`	`ROUND_HALF_EVEN` Режим округления к ближайшему соседу, за исключением случаев, когда оба соседа равноудалены, в таком случае округляется к четному соседу.
`static int`	`ROUND_HALF_UP` Режим округления к ближайшему соседу, за исключением случаев, когда оба соседа равноудалены, в таком случае округляется вверх.
`static int`	`ROUND_UNNECESSARY` Режим округления, гарантирующий точный результат операции, поэтому округление не требуется.
`static int`	`ROUND_UP` Режим округления от нуля.
`static BigDecimal`	`TEN` Значение 10 со масштабом 0.
`static BigDecimal`	`ZERO` Значение 0 со масштабом 0.

Конструкторы

Конструктор и описание
`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(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`	`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)` Возвращает `BigDecimal`, значение которого равно `(this / divisor)`, а масштаб — `this.scale()`.
`BigDecimal`	`divide(BigDecimal divisor, int scale, int roundingMode)` Возвращает `BigDecimal`, значение которого равно `(this / divisor)`, а масштаб — указанный.
`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`	`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)` Возвращает `BigDecimal`, масштаб которого равен указанному значению, а значение без масштаба определяется умножением или делением значения без масштаба этого `BigDecimal` на соответствующую степень десяти для сохранения его общего значения.
`BigDecimal`	`setScale(int newScale, RoundingMode roundingMode)` Возвращает `BigDecimal`, масштаб которого равен указанному значению, а значение без масштаба определяется умножением или делением значения без масштаба этого `BigDecimal` на соответствующую степень десяти для сохранения его общего значения.
`short`	`shortValueExact()` Преобразует этот `BigDecimal` в `short`, проверяя потерю информации.
`int`	`signum()` Возвращает функцию знака этого `BigDecimal`.
`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`.

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

byteValue, shortValue

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

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

Поля

ZERO

public static final BigDecimal ZERO

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

С:: 1.5

ONE

public static final BigDecimal ONE

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

С:: 1.5

TEN

public static final BigDecimal TEN

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

С:: 1.5

ROUND_UP

public static final int ROUND_UP

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

См. также:: Постоянные значения полей

ROUND_DOWN

public static final int ROUND_DOWN

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

См. также:: Постоянные значения полей

ROUND_CEILING

public static final int ROUND_CEILING

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

См. также:: Постоянные значения полей

ROUND_FLOOR

public static final int ROUND_FLOOR

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

См. также:: Постоянные значения полей

ROUND_HALF_UP

public static final int ROUND_HALF_UP

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

См. также:: Постоянные значения полей

ROUND_HALF_DOWN

public static final int ROUND_HALF_DOWN

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

См. также:: Постоянные значения полей

ROUND_HALF_EVEN

public static final int ROUND_HALF_EVEN

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

См. также:: Постоянные значения полей

ROUND_UNNECESSARY

public static final int ROUND_UNNECESSARY

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

См. также:: Постоянные значения полей

Конструкторы

BigDecimal

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

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

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

Параметры:: in - массив символов, являющийся источником символов.; offset - первый символ в массиве для проверки.; len - количество символов для рассмотрения.
Исключения:: NumberFormatException - если in не является допустимым представлением BigDecimal или указанный подмассив не полностью находится внутри in.
С:: 1.5

BigDecimal

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

Параметры:: in - массив символов, являющийся источником символов.; offset - первый символ в массиве для проверки.; len - количество символов для рассмотрения.; mc - используемый контекст.
Исключения:: ArithmeticException - если результат неточный, но режим округления UNNECESSARY.; NumberFormatException - если in не является допустимым представлением BigDecimal или указанный подмассив не полностью находится внутри in.
С:: 1.5

BigDecimal

public BigDecimal(char[] in)

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

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

Параметры:: in - массив символов, являющийся источником символов.
Исключения:: NumberFormatException - если in не является допустимым представлением BigDecimal.
С:: 1.5

BigDecimal

public BigDecimal(char[] in,
                  MathContext mc)

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

Параметры:: in - массив символов, являющийся источником символов.; mc - используемый контекст.
Исключения:: ArithmeticException - если результат неточный, но режим округления UNNECESSARY.; NumberFormatException - если in не является допустимым представлением BigDecimal.
С:: 1.5

BigDecimal

public BigDecimal(String val)

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

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

Порядок состоит из символа 'e' ('\u0065') или 'E' ('\u0045'), за которым следует одна или более десятичных цифр. Значение порядка должно находиться в диапазоне от -Integer.MAX_VALUE (Integer.MIN_VALUE+1) до Integer.MAX_VALUE, включительно.

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

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]

Примечание: Для значений, отличных от 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 - контекст, который необходимо использовать.
Исключения:: ArithmeticException - если результат неточен, но режим округления UNNECESSARY.; 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 - Значение с плавающей точкой, подлежащее преобразованию в BigDecimal.
Исключения:: NumberFormatException - если val бесконечен или NaN.

BigDecimal

public BigDecimal(double val,
                  MathContext mc)

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

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

Параметры:: val - значение с плавающей точкой, подлежащее преобразованию в BigDecimal.; mc - контекст, который необходимо использовать.
Исключения:: ArithmeticException - если результат неточен, но режим округления UNNECESSARY.; 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 - контекст, который необходимо использовать.
Исключения:: ArithmeticException - если результат неточен, но режим округления UNNECESSARY.
С:: 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 - контекст, который необходимо использовать.
Исключения:: ArithmeticException - если результат неточен, но режим округления UNNECESSARY.
С:: 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 - контекст, который необходимо использовать.
Исключения:: ArithmeticException - если результат неточен, но режим округления UNNECESSARY.
С:: 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 - используемый контекст.
Исключения:: ArithmeticException - если результат неточен, но режим округления UNNECESSARY.
С:: 1.5

Методы

valueOf

public static BigDecimal valueOf(long unscaledVal,
                                 int scale)

Преобразует long без масштаба и int масштаб в BigDecimal . Этот «статический фабричный метод» предоставляется вместо конструктора (long, int) для возможности повторного использования часто используемых значений BigDecimal.

Параметры:: unscaledVal - значение без масштаба BigDecimal.; scale - масштаб BigDecimal.
Возвращает:: BigDecimal, значение которого (unscaledVal × 10^-scale).

valueOf

public static BigDecimal valueOf(long val)

Преобразует long в BigDecimal с масштабом ноль. Этот «статический фабричный метод» предоставляется вместо конструктора (long) для возможности повторного использования часто используемых значений BigDecimal.

Параметры:: val - значение BigDecimal.
Возвращает:: BigDecimal, значение которого val.

valueOf

public static BigDecimal valueOf(double val)

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

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

Параметры:: 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, округлённое по необходимости.
Исключения:: ArithmeticException - если результат неточен, но режим округления UNNECESSARY.
С:: 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, округлённое по необходимости.
Исключения:: ArithmeticException - если результат неточен, но режим округления UNNECESSARY.
С:: 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, округлённое по необходимости.
Исключения:: ArithmeticException - если результат неточен, но режим округления UNNECESSARY.
С:: 1.5

divide

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

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

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

Параметры:: divisor - значение, на которое нужно разделить этот BigDecimal.; scale - масштаб BigDecimal частного, который должен быть возвращён.; roundingMode - режим округления, который нужно применить.
Возвращает:: this / divisor
Исключения:: ArithmeticException - если divisor равно нулю, roundingMode==ROUND_UNNECESSARY и указанный масштаб недостаточен для точного представления результата деления.; IllegalArgumentException - если roundingMode не представляет собой допустимый режим округления.
См. также:: ROUND_UP, ROUND_DOWN, ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_UNNECESSARY

divide

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

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

divide

public BigDecimal divide(BigDecimal divisor,
                         int roundingMode)

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

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

Параметры:: divisor - значение, на которое нужно разделить этот BigDecimal.; roundingMode - режим округления, который нужно применить.
Возвращает:: this / divisor
Исключения:: ArithmeticException - если divisor==0, или roundingMode==ROUND_UNNECESSARY и this.scale() недостаточно для точного представления результата деления.; IllegalArgumentException - если roundingMode не представляет собой допустимый режим округления.
См. также:: ROUND_UP, ROUND_DOWN, ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_UNNECESSARY

divide

public BigDecimal divide(BigDecimal divisor,
                         RoundingMode roundingMode)

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

Параметры:: 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.divideToIntgralValue(divisor) потребовал бы точности более mc.precision цифр.
С:: 1.5
См. также:: divideToIntegralValue(java.math.BigDecimal, java.math.MathContext)

divideAndRemainder

public BigDecimal[] divideAndRemainder(BigDecimal divisor)

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

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

Параметры:: divisor - значение, на которое следует разделить данный BigDecimal и вычислить остаток.
Возвращает:: массив из двух элементов BigDecimal: частное (результат divideToIntegralValue) — начальный элемент, остаток — конечный элемент.
Выбрасывает:: ArithmeticException - если divisor==0
С:: 1.5
См. также:: divideToIntegralValue(java.math.BigDecimal, java.math.MathContext), remainder(java.math.BigDecimal, java.math.MathContext)

divideAndRemainder

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

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

Параметры:: divisor - значение, на которое следует разделить данный BigDecimal и вычислить остаток.; mc - контекст для использования.
Возвращает:: массив из двух элементов BigDecimal: частное (результат divideToIntegralValue) — начальный элемент, остаток — конечный элемент.
Выбрасывает:: ArithmeticException - если divisor==0; ArithmeticException - если результат неточен, но режим округления UNNECESSARY, или mc.precision > 0 и результат this.divideToIntgralValue(divisor) потребовал бы точности более mc.precision цифр.
С:: 1.5
См. также:: divideToIntegralValue(java.math.BigDecimal, java.math.MathContext), remainder(java.math.BigDecimal, java.math.MathContext)

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

Алгоритм 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), округлённый по необходимости.
Исключения:: ArithmeticException - если результат неточен, но режим округления — UNNECESSARY.
С:: 1.5

negate

public BigDecimal negate()

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

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

negate

public BigDecimal negate(MathContext mc)

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

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

plus

public BigDecimal plus()

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

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

Возвращает:: this.
С:: 1.5
См. также:: negate()

plus

public BigDecimal plus(MathContext mc)

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

Эффект этого метода идентичен эффекту метода round(MathContext).

Параметры:: mc - используемый контекст.
Возвращает:: this, округлённый по необходимости. Результат ноль будет иметь масштаб 0.
Исключения:: ArithmeticException - если результат неточен, но режим округления — UNNECESSARY.
С:: 1.5
См. также:: round(MathContext)

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.
Исключения:: ArithmeticException - если режим округления — UNNECESSARY, и операция BigDecimal требует округления.
С:: 1.5
См. также:: plus(MathContext)

setScale

public BigDecimal setScale(int newScale,
                           RoundingMode roundingMode)

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

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

Параметры:: newScale - масштаб возвращаемого BigDecimal значения.; roundingMode - режим округления для применения.
Возвращает:: BigDecimal с заданным масштабом, и неусечённым значением, определяемым умножением или делением неусечённого значения этого BigDecimal на соответствующую степень десяти для сохранения его общего значения.
Исключения:: ArithmeticException - если roundingMode==UNNECESSARY и указанная операция масштабирования потребуют округления.
С:: 1.5
См. также:: RoundingMode

setScale

public BigDecimal setScale(int newScale,
                           int roundingMode)

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

Параметры:: newScale - масштаб возвращаемого BigDecimal значения.; roundingMode - режим округления для применения.
Возвращает:: BigDecimal с заданным масштабом, и неусечённым значением, определяемым умножением или делением неусечённого значения этого BigDecimal на соответствующую степень десяти для сохранения его общего значения.
Исключения:: ArithmeticException - если roundingMode==ROUND_UNNECESSARY и указанная операция масштабирования потребуют округления.; IllegalArgumentException - если roundingMode не представляет допустимого режима округления.
См. также:: ROUND_UP, ROUND_DOWN, ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_UNNECESSARY

setScale

public BigDecimal setScale(int newScale)

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

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

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

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

Параметры:: newScale - масштаб возвращаемого BigDecimal значения.
Возвращает:: BigDecimal с заданным масштабом, и неусечённым значением, определяемым умножением или делением неусечённого значения этого BigDecimal на соответствующую степень десяти для сохранения его общего значения.
Исключения:: ArithmeticException - если указанная операция масштабирования потребует округления.
См. также:: setScale(int, int), setScale(int, RoundingMode)

movePointLeft

public BigDecimal movePointLeft(int n)

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

Параметры:: n - число разрядов для сдвига десятичной точки влево.
Возвращает:: a 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 - число разрядов для сдвига десятичной точки вправо.
Возвращает:: a BigDecimal, эквивалентное этому, с десятичной точкой, сдвинутой вправо на n разрядов.
Выбрасывает:: ArithmeticException - если масштаб переполняется.

scaleByPowerOfTen

public BigDecimal scaleByPowerOfTen(int n)

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

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

stripTrailingZeros

public BigDecimal stripTrailingZeros()

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

Возвращает:: численно равное BigDecimal с удалёнными хвостовыми нулями.
Since:: 1.5

compareTo

public int compareTo(BigDecimal val)

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

Specified by:: compareTo в интерфейсе Comparable<BigDecimal>
Параметры:: val - BigDecimal, с которым сравнивается этот BigDecimal.
Возвращает:: -1, 0 или 1, в зависимости от того, является ли этот BigDecimal численно меньше, равно или больше val.

equals

public boolean equals(Object x)

Сравнивает этот BigDecimal с указанным Object на равенство. В отличие от compareTo, этот метод считает два объекта BigDecimal равными только в том случае, если они равны по значению и масштабу (следовательно, 2.0 не равно 2.00 при сравнении этим методом).

Overrides:: equals в классе Object
Параметры:: x - Object, с которым сравнивается этот BigDecimal.
Возвращает:: true тогда и только тогда, когда указанный Object является BigDecimal, значение и масштаб которого равны масштабу этого BigDecimal.
См. также:: compareTo(java.math.BigDecimal), hashCode()

min

public BigDecimal min(BigDecimal val)

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

Параметры:: val - значение, с которым вычисляется минимум.
Возвращает:: BigDecimal, значение которого является меньшим из этого BigDecimal и val . Если они равны, как определено методом compareTo, возвращается this.
См. также:: compareTo(java.math.BigDecimal)

max

public BigDecimal max(BigDecimal val)

Возвращает максимальное значение из этого BigDecimal и val.

Параметры:: val - значение, с которым вычисляется максимум.
Возвращает:: BigDecimal, значение которого является большим из этого BigDecimal и val . Если они равны, как определено методом compareTo, возвращается this.
См. также:: compareTo(java.math.BigDecimal)

hashCode

public int hashCode()

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

Overrides:: hashCode в классе Object
Возвращает:: хэш-код для этого BigDecimal.
См. также:: equals(Object)

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.

Overrides:: toString в классе Object
Returns:: строковое представление этого BigDecimal.
См. также:: Character.forDigit(int, int), BigDecimal(java.lang.String)

toEngineeringString

public String toEngineeringString()

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

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

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

toPlainString

public String toPlainString()

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

Returns:: строковое представление этого BigDecimal без поля показателя степени.
Since:: 1.5
См. также:: toString(), toEngineeringString()

toBigInteger

public BigInteger toBigInteger()

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

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

Returns:: этот BigDecimal преобразован в BigInteger.

toBigIntegerExact

public BigInteger toBigIntegerExact()

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

Returns:: этот BigDecimal преобразован в BigInteger.
Throws:: ArithmeticException - если у this есть ненулевая дробная часть.
Since:: 1.5

longValue

public long longValue()

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

Specified by:: longValue в классе Number
Returns:: этот BigDecimal преобразован в long.

longValueExact

public long longValueExact()

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

Returns:: этот BigDecimal преобразован в long.
Throws:: ArithmeticException - если у this есть ненулевая дробная часть или он не помещается в long.
Since:: 1.5

intValue

public int intValue()

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

Specified by:: intValue в классе Number
Returns:: этот BigDecimal преобразован в int.

intValueExact

public int intValueExact()

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

Returns:: этот BigDecimal преобразован в int.
Throws:: ArithmeticException - если у this есть ненулевая дробная часть или он не помещается в int.
Since:: 1.5

shortValueExact

public short shortValueExact()

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

Returns:: этот BigDecimal преобразован в short.
Throws:: ArithmeticException - если у this есть ненулевая дробная часть или он не помещается в short.
Since:: 1.5

byteValueExact

public byte byteValueExact()

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

Returns:: этот BigDecimal преобразован в byte.
Throws:: ArithmeticException - если у this есть ненулевая дробная часть или он не помещается в byte.
Since:: 1.5

floatValue

public float floatValue()

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

Specified by:: floatValue в классе Number
Returns:: этот BigDecimal преобразован в float.

doubleValue

public double doubleValue()

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

Specified by:: doubleValue в классе Number
Returns:: этот BigDecimal преобразован в double.

ulp

public BigDecimal ulp()

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

Возвращает:: размер ulp для this
С:: 1.5

© 1993, 2020, 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.