Класс BigDecimal

public static final BigDecimal ZERO

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

public static final BigDecimal ONE

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

public static final BigDecimal TEN

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

public BigDecimal(char[] in)

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

public BigDecimal(char[] in, MathContext mc)

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

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]
 

public BigDecimal(String val, MathContext mc)

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

public BigDecimal(double val)

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

Примечания:

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

public BigDecimal(double val, MathContext mc)

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

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

public BigDecimal(BigInteger val)

Преобразует BigInteger в BigDecimal. Порядок BigDecimal равен нулю.

public BigDecimal(BigInteger val, MathContext mc)

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

public BigDecimal(BigInteger unscaledVal, int scale)

Преобразует BigInteger необозначенное значение и int порядок в BigDecimal. Значение BigDecimal равно (unscaledVal × 10-scale).

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

Преобразует BigInteger необозначенное значение и int порядок в BigDecimal, с округлением в соответствии с настройками контекста. Значение BigDecimal равно (unscaledVal × 10-scale), округлённое в соответствии с настройками контекста precision.

public BigDecimal(int val)

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

public BigDecimal(int val, MathContext mc)

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

public BigDecimal(long val)

Преобразует длинное целое число в BigDecimal. Масштаб BigDecimal равен нулю.

public BigDecimal(long val, MathContext mc)

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

public static BigDecimal valueOf(long unscaledVal, int scale)

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

public static BigDecimal valueOf(long val)

Преобразует значение длинного целого числа в BigDecimal с масштабом ноль.

public static BigDecimal valueOf(double val)

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

public BigDecimal add(BigDecimal augend)

Возвращает BigDecimal, значение которого равно сумме текущего и переданного BigDecimal, а масштаб равен max(this.scale(), augend.scale()).

public BigDecimal add(BigDecimal augend, MathContext mc)

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

public BigDecimal subtract(BigDecimal subtrahend)

Возвращает BigDecimal, значение которого равно разности текущего и переданного BigDecimal, а масштаб равен max(this.scale(), subtrahend.scale()).

public BigDecimal subtract(BigDecimal subtrahend, MathContext mc)

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

public BigDecimal multiply(BigDecimal multiplicand)

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

public BigDecimal multiply(BigDecimal multiplicand, MathContext mc)

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

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

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

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

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

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

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

public BigDecimal divide(BigDecimal divisor, RoundingMode roundingMode)

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

public BigDecimal divide(BigDecimal divisor)

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

public BigDecimal divide(BigDecimal divisor, MathContext mc)

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

public BigDecimal divideToIntegralValue(BigDecimal divisor)

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

public BigDecimal divideToIntegralValue(BigDecimal divisor, MathContext mc)

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

public BigDecimal remainder(BigDecimal divisor)

Возвращает значение BigDecimal, значение которого равно (this % divisor).

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

public BigDecimal remainder(BigDecimal divisor, MathContext mc)

Возвращает значение BigDecimal, значение которого равно (this % divisor), с округлением в соответствии с параметрами контекста. Параметры контекста влияют на неявное деление, используемое для вычисления остатка. Само вычисление остатка по определению точное. Поэтому остаток может содержать более чем mc.getPrecision() цифр.

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

public BigDecimal[] divideAndRemainder(BigDecimal divisor)

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

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

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

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

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

public BigDecimal sqrt(MathContext mc)

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

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

Особые случаи:

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

public BigDecimal pow(int n)

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

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

public BigDecimal pow(int n, MathContext mc)

Возвращает BigDecimal со значением (thisn). Текущая реализация использует основной алгоритм, определенный в 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 положительно, результат вычисляется с помощью метода возведения в степень через удвоение (repeated squaring) в один накопитель. Индивидуальные умножения с накопителем используют те же настройки контекста математики, что и в mc, за исключением увеличенной точности до mc.precision + elength + 1, где elength — количество десятичных знаков в n.
  • если n отрицательно, результат вычисляется так, как если бы n было положительно; затем это значение делится на единицу, используя рабочую точность, указанную выше.
  • Конечное значение, полученное в любом из положительного или отрицательного случая, затем округляется до заданной точности.

public BigDecimal abs()

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

public BigDecimal abs(MathContext mc)

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

public BigDecimal negate()

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

public BigDecimal negate(MathContext mc)

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

public BigDecimal plus()

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

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

public BigDecimal plus(MathContext mc)

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

Действие этого метода идентично действию метода round(MathContext).

public int signum()

Возвращает функцию знака этого BigDecimal.

public int scale()

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

public int precision()

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

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

public BigInteger unscaledValue()

Возвращает BigInteger со значением, равным незначащему значению этого BigDecimal. (Вычисляет (this * 10this.scale()).)

public BigDecimal round(MathContext mc)

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

Действие этого метода идентично действию метода plus(MathContext).

public BigDecimal setScale(int newScale, RoundingMode roundingMode)

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

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

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

public BigDecimal setScale(int newScale)

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

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

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

public BigDecimal movePointLeft(int n)

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

public BigDecimal movePointRight(int n)

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

public BigDecimal scaleByPowerOfTen(int n)

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

public BigDecimal stripTrailingZeros()

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

public int compareTo(BigDecimal val)

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

public boolean equals(Object x)

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

public BigDecimal min(BigDecimal val)

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

public BigDecimal max(BigDecimal val)

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

public int hashCode()

Возвращает код хэширования для этого BigDecimal. Код хэширования вычисляется как функция от неизменённого значения и масштаба этого BigDecimal.

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"
 

Примечания:

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

public String toEngineeringString()

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

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

public String toPlainString()

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

public BigInteger toBigInteger()

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

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

public BigInteger toBigIntegerExact()

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

public long longValue()

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

public long longValueExact()

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

public int intValue()

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

public int intValueExact()

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

public short shortValueExact()

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

public byte byteValueExact()

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

public float floatValue()

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

public double doubleValue()

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

public BigDecimal ulp()

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