Java : BigDecimal with Examples

BigDecimal (Java SE 17 & JDK 17) API Examples.
You will find code examples on most BigDecimal methods.

Summary

Immutable, arbitrary-precision signed decimal numbers. A BigDecimal consists of an arbitrary precision integer unscaled value and a 32-bit integer scale.

Class diagram

// An example with rounding error.
final double d1 = 0.1;
final double d2 = 0.2;
final double d3 = d1 + d2;

System.out.println(d1); // 0.1
System.out.println(d2); // 0.2
System.out.println(d3); // 0.30000000000000004

// An example with BigDecimal.
final BigDecimal d1 = new BigDecimal("0.1");
final BigDecimal d2 = new BigDecimal("0.2");
final BigDecimal d3 = d1.add(d2);

System.out.println(d1); // 0.1
System.out.println(d2); // 0.2
System.out.println(d3); // 0.3

Fields

static final BigDecimal ONE

The value 1, with a scale of 0.

System.out.println(BigDecimal.ONE); // 1
System.out.println(BigDecimal.ONE.scale()); // 0

static final int ROUND_CEILING

Deprecated. Use RoundingMode.CEILING instead.

Deprecated. Use RoundingMode instead.

static final int ROUND_DOWN

Deprecated. Use RoundingMode.DOWN instead.

Deprecated. Use RoundingMode instead.

static final int ROUND_FLOOR

Deprecated. Use RoundingMode.FLOOR instead.

Deprecated. Use RoundingMode instead.

static final int ROUND_HALF_DOWN

Deprecated. Use RoundingMode.HALF_DOWN instead.

Deprecated. Use RoundingMode instead.

static final int ROUND_HALF_EVEN

Deprecated. Use RoundingMode.HALF_EVEN instead.

Deprecated. Use RoundingMode instead.

static final int ROUND_HALF_UP

Deprecated. Use RoundingMode.HALF_UP instead.

Deprecated. Use RoundingMode instead.

static final int ROUND_UNNECESSARY

Deprecated. Use RoundingMode.UNNECESSARY instead.

Deprecated. Use RoundingMode instead.

static final int ROUND_UP

Deprecated. Use RoundingMode.UP instead.

Deprecated. Use RoundingMode instead.

static final BigDecimal TEN

The value 10, with a scale of 0.

System.out.println(BigDecimal.TEN); // 10
System.out.println(BigDecimal.TEN.scale()); // 0

static final BigDecimal ZERO

The value 0, with a scale of 0.

System.out.println(BigDecimal.ZERO); // 0
System.out.println(BigDecimal.ZERO.scale()); // 0

Constructors

BigDecimal (char[] in)

Translates a character array representation of a BigDecimal into a BigDecimal, accepting the same sequence of characters as the BigDecimal(String) constructor.

final char[] in = "1234567890".toCharArray();
final var dec = new BigDecimal(in);
System.out.println(dec); // 1234567890

final char[] in = "-1234567890".toCharArray();
final var dec = new BigDecimal(in);
System.out.println(dec); // -1234567890

final char[] in = "0.12345".toCharArray();
final var dec = new BigDecimal(in);
System.out.println(dec); // 0.12345

final char[] in = "xyz".toCharArray();
//new BigDecimal(in); // NumberFormatException:

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

Translates a character array representation of a BigDecimal into a BigDecimal, accepting the same sequence of characters as the BigDecimal(String) constructor, while allowing a sub-array to be specified.

final char[] in = "dummy123dummy".toCharArray();
final var dec = new BigDecimal(in, 5, 3);
System.out.println(dec); // 123

final char[] in = "12345".toCharArray();

System.out.println(new BigDecimal(in, 0, 5)); // 12345
System.out.println(new BigDecimal(in, 0, 4)); // 1234
System.out.println(new BigDecimal(in, 0, 3)); // 123
System.out.println(new BigDecimal(in, 0, 2)); // 12
System.out.println(new BigDecimal(in, 0, 1)); // 1
//new BigDecimal(in, 0, 0); // NumberFormatException: No digits found.

System.out.println(new BigDecimal(in, 0, 5)); // 12345
System.out.println(new BigDecimal(in, 1, 4)); // 2345
System.out.println(new BigDecimal(in, 2, 3)); // 345
System.out.println(new BigDecimal(in, 3, 2)); // 45
System.out.println(new BigDecimal(in, 4, 1)); // 5

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

Translates a character array representation of a BigDecimal into a BigDecimal, accepting the same sequence of characters as the BigDecimal(String) constructor, while allowing a sub-array to be specified and with rounding according to the context settings.

Please see : BigDecimal(char[] in, int offset, int len), BigDecimal(char[] in, MathContext mc)

BigDecimal (char[] in, MathContext mc)

Translates a character array representation of a BigDecimal into a BigDecimal, accepting the same sequence of characters as the BigDecimal(String) constructor and with rounding according to the context settings.

final char[] in = "123456789".toCharArray();

final var mcList = List.of(
        new MathContext(9),
        new MathContext(8),
        new MathContext(7),
        new MathContext(6));

for (final var mc : mcList) {
    final var dec = new BigDecimal(in, mc);
    System.out.println("mc ( " + mc + " ) : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//mc ( precision=9 roundingMode=HALF_UP ) : dec = 123456789 : scale = 0
//mc ( precision=8 roundingMode=HALF_UP ) : dec = 123456790 : scale = -1
//mc ( precision=7 roundingMode=HALF_UP ) : dec = 123456800 : scale = -2
//mc ( precision=6 roundingMode=HALF_UP ) : dec = 123457000 : scale = -3

final char[] in = "-123456789".toCharArray();

final var mcList = List.of(
        new MathContext(9),
        new MathContext(8),
        new MathContext(7),
        new MathContext(6));

for (final var mc : mcList) {
    final var dec = new BigDecimal(in, mc);
    System.out.println("mc ( " + mc + " ) : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//mc ( precision=9 roundingMode=HALF_UP ) : dec = -123456789 : scale = 0
//mc ( precision=8 roundingMode=HALF_UP ) : dec = -123456790 : scale = -1
//mc ( precision=7 roundingMode=HALF_UP ) : dec = -123456800 : scale = -2
//mc ( precision=6 roundingMode=HALF_UP ) : dec = -123457000 : scale = -3

final char[] in = "1.2345".toCharArray();

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

for (final var mc : mcList) {
    final var dec = new BigDecimal(in, mc);
    System.out.println("mc ( " + mc + " ) : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : dec = 1.2345 : scale = 4
//mc ( precision=4 roundingMode=HALF_UP ) : dec = 1.235 : scale = 3
//mc ( precision=3 roundingMode=HALF_UP ) : dec = 1.23 : scale = 2
//mc ( precision=2 roundingMode=HALF_UP ) : dec = 1.2 : scale = 1

BigDecimal (double val)

Translates a double into a BigDecimal which is the exact decimal representation of the double's binary floating-point value.

// An example with rounding error.
final var dec = new BigDecimal(0.1);
System.out.println(dec); // 0.1000000000000000055511151231257827021181583404541015625

BigDecimal (double val, MathContext mc)

Translates a double into a BigDecimal, with rounding according to the context settings.

final var mc = MathContext.DECIMAL128;
System.out.println(mc); // precision=34 roundingMode=HALF_EVEN

// An example with rounding error.
final var dec = new BigDecimal(0.1, mc);
System.out.println(dec); // 0.1000000000000000055511151231257827

BigDecimal (int val)

Translates an int into a BigDecimal.

final var dec = new BigDecimal(12345);
System.out.println(dec); // 12345
System.out.println(dec.scale()); // 0

final var dec = new BigDecimal(-5678);
System.out.println(dec); // -5678
System.out.println(dec.scale()); // 0

BigDecimal (int val, MathContext mc)

Translates an int into a BigDecimal, with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

for (final var mc : mcList) {
    final var dec = new BigDecimal(12345, mc);
    System.out.println("mc ( " + mc + " ) : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : dec = 12345 : scale = 0
//mc ( precision=4 roundingMode=HALF_UP ) : dec = 12350 : scale = -1
//mc ( precision=3 roundingMode=HALF_UP ) : dec = 12300 : scale = -2
//mc ( precision=2 roundingMode=HALF_UP ) : dec = 12000 : scale = -3

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

for (final var mc : mcList) {
    final var dec = new BigDecimal(-56789, mc);
    System.out.println("mc ( " + mc + " ) : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : dec = -56789 : scale = 0
//mc ( precision=4 roundingMode=HALF_UP ) : dec = -56790 : scale = -1
//mc ( precision=3 roundingMode=HALF_UP ) : dec = -56800 : scale = -2
//mc ( precision=2 roundingMode=HALF_UP ) : dec = -57000 : scale = -3

BigDecimal (long val)

Translates a long into a BigDecimal.

Please see BigDecimal(int val, MathContext mc) by replacing long.

BigDecimal (long val, MathContext mc)

Translates a long into a BigDecimal, with rounding according to the context settings.

Please see BigDecimal(int val) by replacing long.

BigDecimal (String val)

Translates the string representation of a BigDecimal into a BigDecimal.

final var values = List.of(
        "0",
        "0.00",
        "123",
        "-123",
        "1.23E3",
        "1.23E+3",
        "12.3E+7",
        "12.0",
        "12.3",
        "0.00123",
        "-1.23E-12",
        "1234.5E-4",
        "0E+7",
        "-0"
);

for (final var val : values) {
    final var dec = new BigDecimal(val);
    System.out.println("val = " + val + " : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//val = 0 : dec = 0 : scale = 0
//val = 0.00 : dec = 0.00 : scale = 2
//val = 123 : dec = 123 : scale = 0
//val = -123 : dec = -123 : scale = 0
//val = 1.23E3 : dec = 1230 : scale = -1
//val = 1.23E+3 : dec = 1230 : scale = -1
//val = 12.3E+7 : dec = 123000000 : scale = -6
//val = 12.0 : dec = 12.0 : scale = 1
//val = 12.3 : dec = 12.3 : scale = 1
//val = 0.00123 : dec = 0.00123 : scale = 5
//val = -1.23E-12 : dec = -0.00000000000123 : scale = 14
//val = 1234.5E-4 : dec = 0.12345 : scale = 5
//val = 0E+7 : dec = 0 : scale = -7
//val = -0 : dec = 0 : scale = 0

BigDecimal (String val, MathContext mc)

Translates the string representation of a BigDecimal into a BigDecimal, accepting the same strings as the BigDecimal(String) constructor, with rounding according to the context settings.

Please see also : BigDecimal(String val)

final var mcList = List.of(
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

for (final var mc : mcList) {
    final var dec = new BigDecimal("1234", mc);
    System.out.println("mc ( " + mc + " ) : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//mc ( precision=4 roundingMode=HALF_UP ) : dec = 1234 : scale = 0
//mc ( precision=3 roundingMode=HALF_UP ) : dec = 1230 : scale = -1
//mc ( precision=2 roundingMode=HALF_UP ) : dec = 1200 : scale = -2


final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

for (final var mc : mcList) {
    final var dec = new BigDecimal("1.2345", mc);
    System.out.println("mc ( " + mc + " ) : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : dec = 1.2345 : scale = 4
//mc ( precision=4 roundingMode=HALF_UP ) : dec = 1.235 : scale = 3
//mc ( precision=3 roundingMode=HALF_UP ) : dec = 1.23 : scale = 2
//mc ( precision=2 roundingMode=HALF_UP ) : dec = 1.2 : scale = 1

BigDecimal (BigInteger val)

Translates a BigInteger into a BigDecimal.

final var val = new BigInteger("12345");
System.out.println(val); // 12345

final var dec = new BigDecimal(val);
System.out.println(dec); // 12345
System.out.println(dec.scale()); // 0

final var val = new BigInteger("-5678");
System.out.println(val); // -5678

final var dec = new BigDecimal(val);
System.out.println(dec); // -5678
System.out.println(dec.scale()); // 0

BigDecimal (BigInteger unscaledVal, int scale)

Translates a BigInteger unscaled value and an int scale into a BigDecimal.

final var val = new BigInteger("12345");
System.out.println(val); // 12345

final var dec1 = new BigDecimal(val, 4);
System.out.println(dec1); // 1.2345
System.out.println(dec1.scale()); // 4

final var dec2 = new BigDecimal(val, -4);
System.out.println(dec2.toPlainString()); // 123450000
System.out.println(dec2.scale()); // -4

final var val = new BigInteger("-5678");
System.out.println(val); // -5678

final var dec = new BigDecimal(val, 5);
System.out.println(dec); // -0.05678
System.out.println(dec.scale()); // 5

BigDecimal (BigInteger unscaledVal, int scale, MathContext mc)

Translates a BigInteger unscaled value and an int scale into a BigDecimal, with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

final var val = new BigInteger("12345");
final var scale = 4;

for (final var mc : mcList) {
    final var dec = new BigDecimal(val, scale, mc);
    System.out.println("mc ( " + mc + " ) : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : dec = 1.2345 : scale = 4
//mc ( precision=4 roundingMode=HALF_UP ) : dec = 1.235 : scale = 3
//mc ( precision=3 roundingMode=HALF_UP ) : dec = 1.23 : scale = 2
//mc ( precision=2 roundingMode=HALF_UP ) : dec = 1.2 : scale = 1

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

final var val = new BigInteger("12345");
final var scale = -4;

for (final var mc : mcList) {
    final var dec = new BigDecimal(val, scale, mc);
    System.out.println("mc ( " + mc + " ) : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : dec = 123450000 : scale = -4
//mc ( precision=4 roundingMode=HALF_UP ) : dec = 123500000 : scale = -5
//mc ( precision=3 roundingMode=HALF_UP ) : dec = 123000000 : scale = -6
//mc ( precision=2 roundingMode=HALF_UP ) : dec = 120000000 : scale = -7

BigDecimal (BigInteger val, MathContext mc)

Translates a BigInteger into a BigDecimal rounding according to the context settings.

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

final var val = new BigInteger("12345");

for (final var mc : mcList) {
    final var dec = new BigDecimal(val, mc);
    System.out.println("mc ( " + mc + " ) : dec = "
            + dec.toPlainString() + " : scale = " + dec.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : dec = 12345 : scale = 0
//mc ( precision=4 roundingMode=HALF_UP ) : dec = 12350 : scale = -1
//mc ( precision=3 roundingMode=HALF_UP ) : dec = 12300 : scale = -2
//mc ( precision=2 roundingMode=HALF_UP ) : dec = 12000 : scale = -3

Methods

BigDecimal abs ()

Returns a BigDecimal whose value is the absolute value of this BigDecimal, and whose scale is this.scale().

final var dec = new BigDecimal("1234");
System.out.println(dec); // 1234

final var ret = dec.abs();
System.out.println(ret); // 1234

final var dec = new BigDecimal("-5678");
System.out.println(dec); // -5678

final var ret = dec.abs();
System.out.println(ret); // 5678

final var dec = new BigDecimal("-1.2345");
System.out.println(dec); // -1.2345

final var ret = dec.abs();
System.out.println(ret); // 1.2345

BigDecimal abs (MathContext mc)

Returns a BigDecimal whose value is the absolute value of this BigDecimal, with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

final var dec = new BigDecimal("-12345");

for (final var mc : mcList) {
    final var ret = dec.abs(mc);
    System.out.println("mc ( " + mc + " ) : ret = "
            + ret.toPlainString() + " : scale = " + ret.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : ret = 12345 : scale = 0
//mc ( precision=4 roundingMode=HALF_UP ) : ret = 12350 : scale = -1
//mc ( precision=3 roundingMode=HALF_UP ) : ret = 12300 : scale = -2
//mc ( precision=2 roundingMode=HALF_UP ) : ret = 12000 : scale = -3

BigDecimal add (BigDecimal augend)

Returns a BigDecimal whose value is (this + augend), and whose scale is max(this.scale(), augend.scale()).

final var dec = new BigDecimal("100");
final var augend = new BigDecimal("23");

final var ret = dec.add(augend);
System.out.println(ret); // 123

final var dec = new BigDecimal("100");
final var augend = new BigDecimal("-23");

final var ret = dec.add(augend);
System.out.println(ret); // 77

final var dec = new BigDecimal("0.1");
final var augend = new BigDecimal("0.023");

final var ret = dec.add(augend);
System.out.println(ret); // 0.123

BigDecimal add (BigDecimal augend, MathContext mc)

Returns a BigDecimal whose value is (this + augend), with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

// 1 ＋ 0.2345
final var dec = new BigDecimal("1");
final var augend = new BigDecimal("0.2345");

for (final var mc : mcList) {
    final var ret = dec.add(augend, mc);
    System.out.println("mc ( " + mc + " ) : ret = "
            + ret.toPlainString() + " : scale = " + ret.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : ret = 1.2345 : scale = 4
//mc ( precision=4 roundingMode=HALF_UP ) : ret = 1.235 : scale = 3
//mc ( precision=3 roundingMode=HALF_UP ) : ret = 1.23 : scale = 2
//mc ( precision=2 roundingMode=HALF_UP ) : ret = 1.2 : scale = 1

byte byteValueExact ()

Converts this BigDecimal to a byte, checking for lost information.

Please see intValueExact() by replacing byte.

int compareTo (BigDecimal val)

Compares this BigDecimal numerically with the specified BigDecimal.

final var dec1 = new BigDecimal("111");
final var dec2 = new BigDecimal("222");

System.out.println(dec1.compareTo(dec2)); // -1
System.out.println(dec2.compareTo(dec1)); // 1

final var dec1 = new BigDecimal("1.23");
final var dec2 = new BigDecimal("-1.23");

System.out.println(dec1.compareTo(dec2)); // 1
System.out.println(dec2.compareTo(dec1)); // -1

final var dec1 = new BigDecimal("1234");
final var dec2 = new BigDecimal("1234");

System.out.println(dec1.compareTo(dec2)); // 0
System.out.println(dec2.compareTo(dec1)); // 0

final var dec1 = new BigDecimal("2.0");
System.out.println(dec1); // 2.0
System.out.println(dec1.scale()); // 1

final var dec2 = new BigDecimal("2.00");
System.out.println(dec2); // 2.00
System.out.println(dec2.scale()); // 2

System.out.println(dec1.compareTo(dec2)); // 0
System.out.println(dec2.compareTo(dec1)); // 0

BigDecimal divide (BigDecimal divisor)

Returns a BigDecimal whose value is (this / divisor), and whose preferred scale is (this.scale() - divisor.scale()); if the exact quotient cannot be represented (because it has a non-terminating decimal expansion) an ArithmeticException is thrown.

final var dec = new BigDecimal("6");
final var divisor = new BigDecimal("2");

// 6 ÷ 2
final var ret = dec.divide(divisor);
System.out.println(ret); // 3
System.out.println(ret.scale()); // 0

final var dec = new BigDecimal("5");
final var divisor = new BigDecimal("4");

// 5 ÷ 4
final var ret = dec.divide(divisor);
System.out.println(ret); // 1.25
System.out.println(ret.scale()); // 2

final var dec = new BigDecimal("12");
final var divisor = new BigDecimal("-0.1");

// 12 ÷ -0.1
final var ret = dec.divide(divisor);
System.out.println(ret.toPlainString()); // -120
System.out.println(ret.scale()); // -1

// 10 ÷ 3
final var dec = BigDecimal.TEN;
final var divisor = new BigDecimal("3");

//ArithmeticException: Non-terminating decimal expansion; no exact representable decimal result.
//dec.divide(divisor);

BigDecimal divide (BigDecimal divisor, int roundingMode)

Deprecated. The method divide(BigDecimal, RoundingMode) should be used in preference to this legacy method.

Deprecated.

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

Deprecated. The method divide(BigDecimal, int, RoundingMode) should be used in preference to this legacy method.

Deprecated.

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

Returns a BigDecimal whose value is (this / divisor), and whose scale is as specified.

// 5 ÷ 4
final var dec = new BigDecimal("5");
final var divisor = new BigDecimal("4");

final var ret1 = dec.divide(divisor, 2, RoundingMode.UNNECESSARY);
System.out.println(ret1); // 1.25
System.out.println(ret1.scale()); // 2

final var ret2 = dec.divide(divisor, 1, RoundingMode.HALF_UP);
System.out.println(ret2); // 1.3
System.out.println(ret2.scale()); // 1

final var ret3 = dec.divide(divisor, 1, RoundingMode.FLOOR);
System.out.println(ret3); // 1.2
System.out.println(ret3.scale()); // 1

// 10 ÷ 3
final var dec = BigDecimal.TEN;
final var divisor = new BigDecimal("3");

final var ret = dec.divide(divisor, 5, RoundingMode.HALF_UP);
System.out.println(ret); // 3.33333
System.out.println(ret.scale()); // 5

BigDecimal divide (BigDecimal divisor, MathContext mc)

Returns a BigDecimal whose value is (this / divisor), with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(3),
        new MathContext(2),
        new MathContext(1));

// 5 ÷ 4
final var dec = new BigDecimal("5");
final var divisor = new BigDecimal("4");

for (final var mc : mcList) {
    final var ret = dec.divide(divisor, mc);
    System.out.println("mc ( " + mc + " ) : ret = "
            + ret.toPlainString() + " : scale = " + ret.scale());
}

// Result
// ↓
//mc ( precision=3 roundingMode=HALF_UP ) : ret = 1.25 : scale = 2
//mc ( precision=2 roundingMode=HALF_UP ) : ret = 1.3 : scale = 1
//mc ( precision=1 roundingMode=HALF_UP ) : ret = 1 : scale = 0

// 10 ÷ 3
final var dec = BigDecimal.TEN;
final var divisor = new BigDecimal("3");

final var ret = dec.divide(divisor, new MathContext(5, RoundingMode.CEILING));
System.out.println(ret); // 3.3334
System.out.println(ret.scale()); // 4

BigDecimal divide (BigDecimal divisor, RoundingMode roundingMode)

Returns a BigDecimal whose value is (this / divisor), and whose scale is this.scale().

// 5 ÷ 4
final var dec = new BigDecimal("5.00");
final var divisor = new BigDecimal("4");

final var ret1 = dec.divide(divisor, RoundingMode.UNNECESSARY);
System.out.println(ret1); // 1.25
System.out.println(ret1.scale()); // 2

// 5 ÷ 4
final var dec = new BigDecimal("5.0");
final var divisor = new BigDecimal("4");

final var ret1 = dec.divide(divisor, RoundingMode.CEILING);
System.out.println(ret1); // 1.3
System.out.println(ret1.scale()); // 1

final var ret2 = dec.divide(divisor, RoundingMode.FLOOR);
System.out.println(ret2); // 1.2
System.out.println(ret2.scale()); // 1

// 5 ÷ 4
final var dec = new BigDecimal("5");
final var divisor = new BigDecimal("4.00");

final var ret1 = dec.divide(divisor, RoundingMode.HALF_UP);
System.out.println(ret1); // 1
System.out.println(ret1.scale()); // 0

// 10 ÷ 3
final var dec = new BigDecimal("10.000");
final var divisor = new BigDecimal("3");

final var ret = dec.divide(divisor, RoundingMode.FLOOR);
System.out.println(ret); // 3.333
System.out.println(ret.scale()); // 3

BigDecimal[] divideAndRemainder (BigDecimal divisor)

Returns a two-element BigDecimal array containing the result of divideToIntegralValue followed by the result of remainder on the two operands.

// 11 ÷ 3
final var dec = new BigDecimal("11");
final var divisor = new BigDecimal("3");

final var ret = dec.divideAndRemainder(divisor);
System.out.println(ret.length); // 2

// The quotient.
System.out.println(ret[0]); // 3
System.out.println(ret[0].scale()); // 0

// The remainder.
System.out.println(ret[1]); // 2
System.out.println(ret[1].scale()); // 0

BigDecimal[] divideAndRemainder (BigDecimal divisor, MathContext mc)

Returns a two-element BigDecimal array containing the result of divideToIntegralValue followed by the result of remainder on the two operands calculated with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(3),
        new MathContext(2),
        new MathContext(1));

// 5000 ÷ 400 = 12 remainder 200
final var dec = new BigDecimal("5000.0");
final var divisor = new BigDecimal("400");

for (final var mc : mcList) {
    try {
        System.out.println("mc ( " + mc + " )");

        final var ret = dec.divideAndRemainder(divisor, mc);

        System.out.println("  ret[0] = " + ret[0].toPlainString() + " : scale = " + ret[0].scale());
        System.out.println("  ret[1] = " + ret[1].toPlainString() + " : scale = " + ret[1].scale());

    } catch (ArithmeticException e) {
        System.out.println("  ArithmeticException!");
    }
}

// Result
// ↓
//mc ( precision=3 roundingMode=HALF_UP )
//  ret[0] = 12.0 : scale = 1
//  ret[1] = 200.0 : scale = 1
//mc ( precision=2 roundingMode=HALF_UP )
//  ret[0] = 12 : scale = 0
//  ret[1] = 200.0 : scale = 1
//mc ( precision=1 roundingMode=HALF_UP )
//  ArithmeticException!

BigDecimal divideToIntegralValue (BigDecimal divisor)

Returns a BigDecimal whose value is the integer part of the quotient (this / divisor) rounded down.

// 10 ÷ 2
final var dec = new BigDecimal("10");
final var divisor = new BigDecimal("2");

final var ret = dec.divideToIntegralValue(divisor);
System.out.println(ret); // 5
System.out.println(ret.scale()); // 0

// 50 ÷ 4
final var dec = new BigDecimal("50.0");
final var divisor = new BigDecimal("4");

final var ret = dec.divideToIntegralValue(divisor);
System.out.println(ret); // 12.0
System.out.println(ret.scale()); // 1

// 10 ÷ 3
final var dec = BigDecimal.TEN;
final var divisor = new BigDecimal("3");

final var ret = dec.divideToIntegralValue(divisor);
System.out.println(ret); // 3
System.out.println(ret.scale()); // 0

BigDecimal divideToIntegralValue (BigDecimal divisor, MathContext mc)

Returns a BigDecimal whose value is the integer part of (this / divisor).

final var mcList = List.of(
        new MathContext(3),
        new MathContext(2),
        new MathContext(1));

// 50 ÷ 4
final var dec = new BigDecimal("50.0");
final var divisor = new BigDecimal("4");

for (final var mc : mcList) {
    try {
        final var ret = dec.divideToIntegralValue(divisor, mc);
        System.out.println("mc (" + mc + ") : ret = "
                + ret.toPlainString() + " : scale = " + ret.scale());
    } catch (ArithmeticException e) {
        System.out.println("mc (" + mc + ") : ArithmeticException!");
    }
}

// Result
// ↓
//mc (precision=3 roundingMode=HALF_UP) : ret = 12.0 : scale = 1
//mc (precision=2 roundingMode=HALF_UP) : ret = 12 : scale = 0
//mc (precision=1 roundingMode=HALF_UP) : ArithmeticException!

double doubleValue ()

Converts this BigDecimal to a double.

final var dec = new BigDecimal("1.5");
System.out.println(dec); // 1.5

final double ret = dec.doubleValue();
System.out.println(ret); // 1.5

System.out.println(new BigDecimal(ret)); // 1.5

final var dec = new BigDecimal("0.1");
System.out.println(dec); // 0.1

// An example with rounding error.
final double ret = dec.doubleValue();
System.out.println(ret); // 0.1

System.out.println(new BigDecimal(ret)); // 0.1000000000000000055511151231257827021181583404541015625

boolean equals (Object x)

Compares this BigDecimal with the specified Object for equality.

Please see also : compareTo(BigDecimal val)

final var dec1 = new BigDecimal("111");
final var dec2 = new BigDecimal("222");

System.out.println(dec1.equals(dec2)); // false

final var dec1 = new BigDecimal("1234");
final var dec2 = new BigDecimal("1234");

System.out.println(dec1.equals(dec2)); // true

final var dec1 = new BigDecimal("1.23");
final var dec2 = new BigDecimal("-1.23");

System.out.println(dec1.equals(dec2)); // false

final var dec1 = new BigDecimal("2.0");
final var dec2 = new BigDecimal("2.00");

System.out.println(dec1.equals(dec2)); // false

float floatValue ()

Converts this BigDecimal to a float.

final var dec = new BigDecimal("1.5");
System.out.println(dec); // 1.5

final float ret = dec.floatValue();
System.out.println(ret); // 1.5

System.out.println(new BigDecimal(ret)); // 1.5

// An example with rounding error.
final var dec = new BigDecimal("0.1");
System.out.println(dec); // 0.1

final float ret = dec.floatValue();
System.out.println(ret); // 0.1

System.out.println(new BigDecimal(ret)); // 0.100000001490116119384765625

final var dec = new BigDecimal("1234567890123456789012345678901234567890");
System.out.println(dec); // 1.5

final float ret = dec.floatValue();
System.out.println(ret); // Infinity

int hashCode ()

Returns the hash code for this BigDecimal.

final var dec1 = new BigDecimal("111");
final var dec2 = new BigDecimal("222");

System.out.println(dec1.hashCode()); // 3441
System.out.println(dec2.hashCode()); // 6882

final var dec1 = new BigDecimal("1234");
final var dec2 = new BigDecimal("1234");

System.out.println(dec1 != dec2); // true
System.out.println(dec1.hashCode()); // 38254
System.out.println(dec2.hashCode()); // 38254

final var dec1 = new BigDecimal("1.23");
final var dec2 = new BigDecimal("-1.23");

System.out.println(dec1.hashCode()); // 3815
System.out.println(dec2.hashCode()); // -3811

final var dec1 = new BigDecimal("2.0");
final var dec2 = new BigDecimal("2.00");

System.out.println(dec1.hashCode()); // 621
System.out.println(dec2.hashCode()); // 6202

int intValue ()

Converts this BigDecimal to an int.

final var dec = new BigDecimal("12345");
System.out.println(dec); // 12345

final int ret = dec.intValue();
System.out.println(ret); // 12345

final var dec = new BigDecimal("12.345");
System.out.println(dec); // 12.345

final int ret = dec.intValue();
System.out.println(ret); // 12

System.out.println(Integer.MAX_VALUE); // 2147483647

final var dec1 = new BigDecimal("2147483647");
final var dec2 = new BigDecimal("2147483648");

System.out.println(dec1); // 2147483647
System.out.println(dec2); // 2147483648

System.out.println(dec1.intValue()); // 2147483647
System.out.println(dec2.intValue()); // -2147483648

int intValueExact ()

Converts this BigDecimal to an int, checking for lost information.

final var dec = new BigDecimal("12345");
System.out.println(dec); // 12345

final int ret = dec.intValueExact();
System.out.println(ret); // 12345

final var dec = new BigDecimal("12.345");
System.out.println(dec); // 12.345

//dec.intValueExact(); // ArithmeticException: Rounding necessary

System.out.println(Integer.MAX_VALUE); // 2147483647

final var dec1 = new BigDecimal("2147483647");
final var dec2 = new BigDecimal("2147483648");

System.out.println(dec1); // 2147483647
System.out.println(dec2); // 2147483648

System.out.println(dec1.intValue()); // 2147483647

//dec2.intValueExact(); // ArithmeticException: Overflow

long longValue ()

Converts this BigDecimal to a long.

Please see intValue() by replacing long.

long longValueExact ()

Converts this BigDecimal to a long, checking for lost information.

Please see intValueExact() by replacing long.

BigDecimal max (BigDecimal val)

Returns the maximum of this BigDecimal and val.

final var dec1 = new BigDecimal("123");
final var dec2 = new BigDecimal("456");

System.out.println(dec1.max(dec2)); // 456
System.out.println(dec2.max(dec1)); // 456

final var dec1 = new BigDecimal("1.234");
final var dec2 = new BigDecimal("-1.234");

System.out.println(dec1.max(dec2)); // 1.234
System.out.println(dec2.max(dec1)); // 1.234

final var dec1 = new BigDecimal("2.00");
final var dec2 = new BigDecimal("2.0");

System.out.println(dec1.max(dec2)); // 2.00
System.out.println(dec2.max(dec1)); // 2.0

BigDecimal min (BigDecimal val)

Returns the minimum of this BigDecimal and val.

final var dec1 = new BigDecimal("123");
final var dec2 = new BigDecimal("456");

System.out.println(dec1.min(dec2)); // 123
System.out.println(dec2.min(dec1)); // 123

final var dec1 = new BigDecimal("1.234");
final var dec2 = new BigDecimal("-1.234");

System.out.println(dec1.min(dec2)); // -1.234
System.out.println(dec2.min(dec1)); // -1.234

final var dec1 = new BigDecimal("2.00");
final var dec2 = new BigDecimal("2.0");

System.out.println(dec1.min(dec2)); // 2.00
System.out.println(dec2.min(dec1)); // 2.0

BigDecimal movePointLeft (int n)

Returns a BigDecimal which is equivalent to this one with the decimal point moved n places to the left.

final var dec = new BigDecimal("1");
System.out.println(dec); // 1

System.out.println(dec.movePointLeft(0)); // 1
System.out.println(dec.movePointLeft(1)); // 0.1
System.out.println(dec.movePointLeft(2)); // 0.01
System.out.println(dec.movePointLeft(3)); // 0.001
System.out.println(dec.movePointLeft(4)); // 0.0001

final var dec = new BigDecimal("-1.234");
System.out.println(dec); // -1.234

System.out.println(dec.movePointLeft(0)); // -1.234
System.out.println(dec.movePointLeft(1)); // -0.1234
System.out.println(dec.movePointLeft(2)); // -0.01234
System.out.println(dec.movePointLeft(3)); // -0.001234
System.out.println(dec.movePointLeft(4)); // -0.0001234

BigDecimal movePointRight (int n)

Returns a BigDecimal which is equivalent to this one with the decimal point moved n places to the right.

final var dec = new BigDecimal("1");
System.out.println(dec); // 1

System.out.println(dec.movePointRight(0)); // 1
System.out.println(dec.movePointRight(1)); // 10
System.out.println(dec.movePointRight(2)); // 100
System.out.println(dec.movePointRight(3)); // 1000
System.out.println(dec.movePointRight(4)); // 10000

final var dec = new BigDecimal("-1.234");
System.out.println(dec); // -1.234

System.out.println(dec.movePointRight(0)); // -1.234
System.out.println(dec.movePointRight(1)); // -12.34
System.out.println(dec.movePointRight(2)); // -123.4
System.out.println(dec.movePointRight(3)); // -1234
System.out.println(dec.movePointRight(4)); // -12340

BigDecimal multiply (BigDecimal multiplicand)

Returns a BigDecimal whose value is (this × multiplicand), and whose scale is (this.scale() + multiplicand.scale()).

// 100 × 23
final var dec = new BigDecimal("100");
final var multiplicand = new BigDecimal("23");

final var ret = dec.multiply(multiplicand);
System.out.println(ret); // 2300

// 100 × -23
final var dec = new BigDecimal("100");
final var multiplicand = new BigDecimal("-23");

final var ret = dec.multiply(multiplicand);
System.out.println(ret); // -2300

// 0.123 × 0.1
final var dec = new BigDecimal("0.123");
final var multiplicand = new BigDecimal("0.1");

final var ret = dec.multiply(multiplicand);
System.out.println(ret); // 0.0123

BigDecimal multiply (BigDecimal multiplicand, MathContext mc)

Returns a BigDecimal whose value is (this × multiplicand), with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(4),
        new MathContext(3),
        new MathContext(2),
        new MathContext(1));

// 1234 × 2
final var dec = new BigDecimal("1234");
final var multiplicand = new BigDecimal("2");

for (final var mc : mcList) {
    final var ret = dec.multiply(multiplicand, mc);
    System.out.println("mc ( " + mc + " ) : ret = "
            + ret.toPlainString() + " : scale = " + ret.scale());
}

// Result
// ↓
//mc ( precision=4 roundingMode=HALF_UP ) : ret = 2468 : scale = 0
//mc ( precision=3 roundingMode=HALF_UP ) : ret = 2470 : scale = -1
//mc ( precision=2 roundingMode=HALF_UP ) : ret = 2500 : scale = -2
//mc ( precision=1 roundingMode=HALF_UP ) : ret = 2000 : scale = -3

BigDecimal negate ()

Returns a BigDecimal whose value is (-this), and whose scale is this.scale().

final var dec = new BigDecimal("1234");
System.out.println(dec.negate()); // -1234

final var dec = new BigDecimal("-1.234");
System.out.println(dec.negate()); // 1.234

final var dec = new BigDecimal("2.00");
System.out.println(dec.negate()); // -2.00

BigDecimal negate (MathContext mc)

Returns a BigDecimal whose value is (-this), with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

final var dec = new BigDecimal("12345");

for (final var mc : mcList) {
    final var ret = dec.negate(mc);
    System.out.println("mc ( " + mc + " ) : ret = "
            + ret.toPlainString() + " : scale = " + ret.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : ret = -12345 : scale = 0
//mc ( precision=4 roundingMode=HALF_UP ) : ret = -12350 : scale = -1
//mc ( precision=3 roundingMode=HALF_UP ) : ret = -12300 : scale = -2
//mc ( precision=2 roundingMode=HALF_UP ) : ret = -12000 : scale = -3

BigDecimal plus ()

Returns a BigDecimal whose value is (+this), and whose scale is this.scale().

final var dec = new BigDecimal("1234");
System.out.println(dec.plus()); // 1234

final var dec = new BigDecimal("-1.234");
System.out.println(dec.plus()); // -1.234

final var dec = new BigDecimal("2.00");
System.out.println(dec.plus()); // 2.00

BigDecimal plus (MathContext mc)

Returns a BigDecimal whose value is (+this), with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

final var dec = new BigDecimal("12345");

for (final var mc : mcList) {
    final var ret = dec.plus(mc);
    System.out.println("mc ( " + mc + " ) : ret = "
            + ret.toPlainString() + " : scale = " + ret.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : ret = 12345 : scale = 0
//mc ( precision=4 roundingMode=HALF_UP ) : ret = 12350 : scale = -1
//mc ( precision=3 roundingMode=HALF_UP ) : ret = 12300 : scale = -2
//mc ( precision=2 roundingMode=HALF_UP ) : ret = 12000 : scale = -3

BigDecimal pow (int n)

Returns a BigDecimal whose value is (thisn), The power is computed exactly, to unlimited precision.

final var dec = new BigDecimal("2");
System.out.println(dec.pow(0)); // 1
System.out.println(dec.pow(1)); // 2
System.out.println(dec.pow(2)); // 4
System.out.println(dec.pow(3)); // 8
System.out.println(dec.pow(4)); // 16
System.out.println(dec.pow(5)); // 32
System.out.println(dec.pow(6)); // 64

System.out.println(BigDecimal.ZERO.pow(0)); // 1

BigDecimal pow (int n, MathContext mc)

Returns a BigDecimal whose value is (thisn).

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

final var dec = new BigDecimal("2");

for (final var mc : mcList) {
    // 2^16
    final var ret = dec.pow(16, mc);
    System.out.println("mc ( " + mc + " ) : ret = "
            + ret.toPlainString() + " : scale = " + ret.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : ret = 65536 : scale = 0
//mc ( precision=4 roundingMode=HALF_UP ) : ret = 65540 : scale = -1
//mc ( precision=3 roundingMode=HALF_UP ) : ret = 65500 : scale = -2
//mc ( precision=2 roundingMode=HALF_UP ) : ret = 66000 : scale = -3

int precision ()

Returns the precision of this BigDecimal.

System.out.println(new BigDecimal("0").precision()); // 1
System.out.println(new BigDecimal("1").precision()); // 1
System.out.println(new BigDecimal("12345").precision()); // 5
System.out.println(new BigDecimal("-67890").precision()); // 5

System.out.println(new BigDecimal("0.123").precision()); // 3
System.out.println(new BigDecimal("1.234").precision()); // 4
System.out.println(new BigDecimal("12.3456").precision()); // 6

final var dec1 = new BigDecimal("12345");
System.out.println(dec1.toPlainString()); // 12345
System.out.println(dec1.scale()); // 0
System.out.println(dec1.precision()); // 5

final var dec2 = dec1.setScale(-3, RoundingMode.FLOOR);
System.out.println(dec2.toPlainString()); // 12000
System.out.println(dec2.scale()); // -3
System.out.println(dec2.precision()); // 2

BigDecimal remainder (BigDecimal divisor)

Returns a BigDecimal whose value is (this % divisor).

// 5 % 3
final var dec = new BigDecimal("5.0");
final var divisor = new BigDecimal("3");

final var ret = dec.remainder(divisor);
System.out.println(ret); // 2.0
System.out.println(ret.scale()); // 1

// 15 % -6
final var dec = new BigDecimal("15");
final var divisor = new BigDecimal("-6");

final var ret = dec.remainder(divisor);
System.out.println(ret); // 3
System.out.println(ret.scale()); // 0

// 10 % 0.03
final var dec = new BigDecimal("10");
final var divisor = new BigDecimal("0.03");

final var ret = dec.remainder(divisor);
System.out.println(ret); // 0.01
System.out.println(ret.scale()); // 2

BigDecimal remainder (BigDecimal divisor, MathContext mc)

Returns a BigDecimal whose value is (this % divisor), with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(3),
        new MathContext(2),
        new MathContext(1));

// 1000 ÷ 877 = 1 remainder 123
final var dec = new BigDecimal("1000");
final var divisor = new BigDecimal("877");

for (final var mc : mcList) {
    final var ret = dec.remainder(divisor, mc);
    System.out.println("mc ( " + mc + " ) : ret = "
            + ret.toPlainString() + " : scale = " + ret.scale());
}

// Result
// ↓
//mc ( precision=3 roundingMode=HALF_UP ) : ret = 123 : scale = 0
//mc ( precision=2 roundingMode=HALF_UP ) : ret = 123 : scale = 0
//mc ( precision=1 roundingMode=HALF_UP ) : ret = 123 : scale = 0

final var mcList = List.of(
        new MathContext(3),
        new MathContext(2),
        new MathContext(1));

// 100 ÷ 3 = 33 remainder 1
final var dec = new BigDecimal("100");
final var divisor = new BigDecimal("3");

for (final var mc : mcList) {
    try {
        final var ret = dec.remainder(divisor, mc);
        System.out.println("mc ( " + mc + " ) : ret = "
                + ret.toPlainString() + " : scale = " + ret.scale());
    } catch (ArithmeticException e) {
        System.out.println("mc ( " + mc + " ) : ArithmeticException!");
    }
}

// Result
// ↓
//mc ( precision=3 roundingMode=HALF_UP ) : ret = 1 : scale = 0
//mc ( precision=2 roundingMode=HALF_UP ) : ret = 1 : scale = 0
//mc ( precision=1 roundingMode=HALF_UP ) : ArithmeticException!

BigDecimal round (MathContext mc)

Returns a BigDecimal rounded according to the MathContext settings.

final var dec = new BigDecimal("1.2345");

final var ret1 = dec.round(new MathContext(4, RoundingMode.CEILING));
System.out.println(ret1); // 1.235
System.out.println(ret1.scale()); // 3

final var ret2 = dec.round(new MathContext(4, RoundingMode.FLOOR));
System.out.println(ret2); // 1.234
System.out.println(ret2.scale()); // 3

final var ret3 = dec.round(new MathContext(3, RoundingMode.FLOOR));
System.out.println(ret3); // 1.23
System.out.println(ret3.scale()); // 2

final var dec = new BigDecimal("12345");

final var ret1 = dec.round(new MathContext(4, RoundingMode.CEILING));
System.out.println(ret1.toPlainString()); // 12350
System.out.println(ret1.scale()); // -1

final var ret2 = dec.round(new MathContext(3, RoundingMode.FLOOR));
System.out.println(ret2.toPlainString()); // 12300
System.out.println(ret2.scale()); // -2

int scale ()

Returns the scale of this BigDecimal.

final var dec = new BigDecimal("1234");
System.out.println(dec); // 1234
System.out.println(dec.scale()); // 0

final var dec = new BigDecimal("1.234");
System.out.println(dec); // 1.234
System.out.println(dec.scale()); // 3

final var dec = new BigDecimal("12.3E+7");
System.out.println(dec.toPlainString()); // 123000000
System.out.println(dec.scale()); // -6

final var dec = new BigDecimal("12345", new MathContext(3));
System.out.println(dec.toPlainString()); // 12300
System.out.println(dec.scale()); // -2

BigDecimal scaleByPowerOfTen (int n)

Returns a BigDecimal whose numerical value is equal to (this * 10n).

final var dec = new BigDecimal("1234");
System.out.println(dec); // 1234
System.out.println(dec.scale()); // 0

final var ret1 = dec.scaleByPowerOfTen(1);
System.out.println(ret1.toPlainString()); // 12340
System.out.println(ret1.scale()); // -1

final var ret2 = dec.scaleByPowerOfTen(2);
System.out.println(ret2.toPlainString()); // 123400
System.out.println(ret2.scale()); // -2

final var dec = new BigDecimal("1.234");
System.out.println(dec); // 1.234
System.out.println(dec.scale()); // 3

final var ret1 = dec.scaleByPowerOfTen(-1);
System.out.println(ret1.toPlainString()); // 0.1234
System.out.println(ret1.scale()); // 4

final var ret2 = dec.scaleByPowerOfTen(-2);
System.out.println(ret2.toPlainString()); // 0.01234
System.out.println(ret2.scale()); // 5

BigDecimal setScale (int newScale)

Returns a BigDecimal whose scale is the specified value, and whose value is numerically equal to this BigDecimal's.

final var dec = new BigDecimal("1234");
System.out.println(dec); // 1234
System.out.println(dec.scale()); // 0

final var ret1 = dec.setScale(1);
System.out.println(ret1.toPlainString()); // 1234.0
System.out.println(ret1.scale()); // 1

final var ret2 = dec.setScale(2);
System.out.println(ret2.toPlainString()); // 1234.00
System.out.println(ret2.scale()); // 2

//dec.setScale(-1); // ArithmeticException: Rounding necessary

BigDecimal setScale (int newScale, int roundingMode)

Deprecated. The method setScale(int, RoundingMode) should be used in preference to this legacy method.

Deprecated.

BigDecimal setScale (int newScale, RoundingMode roundingMode)

Returns a BigDecimal whose scale is the specified value, and whose unscaled value is determined by multiplying or dividing this BigDecimal's unscaled value by the appropriate power of ten to maintain its overall value.

final var dec = new BigDecimal("1.2345");
System.out.println(dec); // 1.2345
System.out.println(dec.scale()); // 4

final var ret1 = dec.setScale(3, RoundingMode.CEILING);
System.out.println(ret1.toPlainString()); // 1.235
System.out.println(ret1.scale()); // 3

final var ret2 = dec.setScale(3, RoundingMode.FLOOR);
System.out.println(ret2.toPlainString()); // 1.234
System.out.println(ret2.scale()); // 3

final var dec = new BigDecimal("12345");
System.out.println(dec); // 12345
System.out.println(dec.scale()); // 0

final var ret1 = dec.setScale(-1, RoundingMode.HALF_UP);
System.out.println(ret1.toPlainString()); // 12350
System.out.println(ret1.scale()); // -1

final var ret2 = dec.setScale(-2, RoundingMode.HALF_UP);
System.out.println(ret2.toPlainString()); // 12300
System.out.println(ret2.scale()); // -2

short shortValueExact ()

Converts this BigDecimal to a short, checking for lost information.

Please see intValueExact() by replacing short.

int signum ()

Returns the signum function of this BigDecimal.

System.out.println(new BigDecimal("123").signum()); // 1
System.out.println(new BigDecimal("-456").signum()); // -1

System.out.println(new BigDecimal("1.23").signum()); // 1
System.out.println(new BigDecimal("-9.99").signum()); // -1

System.out.println(BigDecimal.ZERO.signum()); // 0

BigDecimal sqrt (MathContext mc)

Returns an approximation to the square root of this with rounding according to the context settings.

final var dec = new BigDecimal("2");

// √2
final var ret1 = dec.sqrt(new MathContext(10));
System.out.println(ret1.toPlainString()); // 1.414213562
System.out.println(ret1.scale()); // 9

final var ret2 = dec.sqrt(new MathContext(5));
System.out.println(ret2.toPlainString()); // 1.4142
System.out.println(ret2.scale()); // 4

final var ret = BigDecimal.ZERO.sqrt(new MathContext(10));
System.out.println(ret.toPlainString()); // 0

System.out.println(BigDecimal.ZERO.equals(ret)); // true

BigDecimal stripTrailingZeros ()

Returns a BigDecimal which is numerically equal to this one but with any trailing zeros removed from the representation.

final var dec = new BigDecimal("3.00");
System.out.println(dec.toPlainString()); // 3.00
System.out.println(dec.scale()); // 2

final var ret = dec.stripTrailingZeros();
System.out.println(ret.toPlainString()); // 3
System.out.println(ret.scale()); // 0

final var dec = new BigDecimal("123400");
System.out.println(dec.toPlainString()); // 123400
System.out.println(dec.scale()); // 0

final var ret = dec.stripTrailingZeros();
System.out.println(ret.toPlainString()); // 123400
System.out.println(ret.scale()); // -2

final var dec = new BigDecimal("1.2340");
System.out.println(dec.toPlainString()); // 1.2340
System.out.println(dec.scale()); // 4

final var ret = dec.stripTrailingZeros();
System.out.println(ret.toPlainString()); // 1.234
System.out.println(ret.scale()); // 3

BigDecimal subtract (BigDecimal subtrahend)

Returns a BigDecimal whose value is (this - subtrahend), and whose scale is max(this.scale(), subtrahend.scale()).

final var dec = new BigDecimal("100");
final var subtrahend = new BigDecimal("23");

final var ret = dec.subtract(subtrahend);
System.out.println(ret); // 77

final var dec = new BigDecimal("100");
final var subtrahend = new BigDecimal("-23");

final var ret = dec.subtract(subtrahend);
System.out.println(ret); // 123

final var dec = new BigDecimal("0.1");
final var subtrahend = new BigDecimal("0.023");

final var ret = dec.subtract(subtrahend);
System.out.println(ret); // 0.077

BigDecimal subtract (BigDecimal subtrahend, MathContext mc)

Returns a BigDecimal whose value is (this - subtrahend), with rounding according to the context settings.

final var mcList = List.of(
        new MathContext(5),
        new MathContext(4),
        new MathContext(3),
        new MathContext(2));

// 1.12345 - 1
final var dec = new BigDecimal("1.12345");
final var subtrahend = new BigDecimal("1");

for (final var mc : mcList) {
    final var ret = dec.subtract(subtrahend, mc);
    System.out.println("mc ( " + mc + " ) : ret = "
            + ret.toPlainString() + " : scale = " + ret.scale());
}

// Result
// ↓
//mc ( precision=5 roundingMode=HALF_UP ) : ret = 0.12345 : scale = 5
//mc ( precision=4 roundingMode=HALF_UP ) : ret = 0.1235 : scale = 4
//mc ( precision=3 roundingMode=HALF_UP ) : ret = 0.123 : scale = 3
//mc ( precision=2 roundingMode=HALF_UP ) : ret = 0.12 : scale = 2

BigInteger toBigInteger ()

Converts this BigDecimal to a BigInteger.

final var dec = new BigDecimal("12345");
System.out.println(dec); // 12345

final var ret = dec.toBigInteger();
System.out.println(ret); // 12345

final var dec = new BigDecimal("123.4567");
System.out.println(dec); // 123.4567

final var ret = dec.toBigInteger();
System.out.println(ret); // 123

final var dec = new BigDecimal("1234567890123456789012345678901234567890");
System.out.println(dec); // 1234567890123456789012345678901234567890

final var ret = dec.toBigInteger();
System.out.println(ret); // 1234567890123456789012345678901234567890

BigInteger toBigIntegerExact ()

Converts this BigDecimal to a BigInteger, checking for lost information.

final var dec = new BigDecimal("12345");
System.out.println(dec); // 12345

final var ret = dec.toBigIntegerExact();
System.out.println(ret); // 12345

final var dec = new BigDecimal("123.4567");
System.out.println(dec); // 123.4567

//dec.toBigIntegerExact(); // ArithmeticException: Rounding necessary

String toEngineeringString ()

Returns a string representation of this BigDecimal, using engineering notation if an exponent is needed.

Please see toString().

String toPlainString ()

Returns a string representation of this BigDecimal without an exponent field.

Please see toString().

String toString ()

Returns the string representation of this BigDecimal, using scientific notation if an exponent is needed.

final var dec = new BigDecimal("123456789");

System.out.println(dec.toPlainString()); // 123456789
System.out.println(dec.toString()); // 123456789
System.out.println(dec.toEngineeringString()); // 123456789

final var dec2 = dec.setScale(-2, RoundingMode.FLOOR);

System.out.println(dec2.toPlainString()); // 123456700
System.out.println(dec2.toString()); // 1.234567E+8
System.out.println(dec2.toEngineeringString()); // 123.4567E+6

BigDecimal ulp ()

Returns the size of an ulp, a unit in the last place, of this BigDecimal.

System.out.println(new BigDecimal("3").ulp()); // 1
System.out.println(new BigDecimal("3.0").ulp()); // 0.1
System.out.println(new BigDecimal("3.00").ulp()); // 0.01

System.out.println(new BigDecimal("30").ulp()); // 1
System.out.println(new BigDecimal("300").ulp()); // 1

final var dec1 = BigDecimal.valueOf(3, -1);
System.out.println(dec1.toPlainString()); // 30
System.out.println(dec1.scale()); // -1
System.out.println(dec1.ulp().toPlainString()); // 10

final var dec2 = BigDecimal.valueOf(3, -2);
System.out.println(dec2.toPlainString()); // 300
System.out.println(dec2.scale()); // -2
System.out.println(dec2.ulp().toPlainString()); // 100

BigInteger unscaledValue ()

Returns a BigInteger whose value is the unscaled value of this BigDecimal.

final var dec = new BigDecimal("1.234");
System.out.println(dec); // 1.234
System.out.println(dec.scale()); // 3

final var ret = dec.unscaledValue();
System.out.println(ret); // 1234

final var dec = BigDecimal.valueOf(1234, -3);
System.out.println(dec.toPlainString()); // 1234000
System.out.println(dec.scale()); // -3

final var ret = dec.unscaledValue();
System.out.println(ret); // 1234

static BigDecimal valueOf (double val)

Translates a double into a BigDecimal, using the double's canonical string representation provided by the Double.toString(double) method.

final double val = 0.1;

final var dec1 = BigDecimal.valueOf(val);
System.out.println(dec1); // 0.1

final var dec2 = new BigDecimal(val);
System.out.println(dec2); // 0.1000000000000000055511151231257827021181583404541015625

final double val = 0.1 + 0.2;

final var dec1 = BigDecimal.valueOf(val);
System.out.println(dec1); // 0.30000000000000004

final var dec2 = new BigDecimal(val);
System.out.println(dec2); // 0.3000000000000000444089209850062616169452667236328125

static BigDecimal valueOf (long val)

Translates a long value into a BigDecimal with a scale of zero.

final var dec1 = BigDecimal.valueOf(1234L);
System.out.println(dec1); // 1234

final var dec2 = BigDecimal.valueOf(-56789L);
System.out.println(dec2); // -56789

static BigDecimal valueOf (long unscaledVal, int scale)

Translates a long unscaled value and an int scale into a BigDecimal.

final var dec1 = BigDecimal.valueOf(1234L, 1);
System.out.println(dec1.toPlainString()); // 123.4
System.out.println(dec1.scale()); // 1

final var dec2 = BigDecimal.valueOf(1234L, 2);
System.out.println(dec2.toPlainString()); // 12.34
System.out.println(dec2.scale()); // 2

final var dec3 = BigDecimal.valueOf(1234L, 3);
System.out.println(dec3.toPlainString()); // 1.234
System.out.println(dec3.scale()); // 3

final var dec1 = BigDecimal.valueOf(1234L, -1);
System.out.println(dec1.toPlainString()); // 12340
System.out.println(dec1.scale()); // -1

final var dec2 = BigDecimal.valueOf(1234L, -2);
System.out.println(dec2.toPlainString()); // 123400
System.out.println(dec2.scale()); // -2

Methods declared in Number

byteValue, shortValue

Please see the link below.

Java API Examples : Number

API Examples
- Number
  - BigInteger
  - Byte
  - Double
  - Float
  - Integer
  - Long
  - Short
- NumberFormat
- Math
- MathContext
- RoundingMode
- StrictMath