`java.math.BigDecimal`

class represents “Immutable, arbitrary-precision signed decimal numbers” (with some limits), and has methods to operate on those numbers. Its use although is not so immediate and it is easy to do errors.

In this article I’ll try to put some light on this topic, in the hope of seeing a lowering in the amount of bugs related to code using `BigInteger`

and `BigDecimal`

.

### What is it

The package `java.math`

contains two classes targeted at “arbitrary precision math”: `BigInteger`

and `BigDecimal`

. Both handle numbers whose magnitude overcome the limits imposed by standard Java types such as `int`

, `long`

, `double`

, `float`

, ecc.

`java.math.BigInteger`

This class handles **immutable**, integer numbers of arbitrary length; the maximum amount of usable digits is Integer.MAX_VALUE.

`java.math.BigDecimal`

This class handles **immutable**, decimal numbers of arbitrary length; as above, the amount of usable digits is limited by the available memory. It is composed of two parts:

*unscaled value*: it is a`BigInteger`

object holding the number representation withouts the decimal symbol.*scale*: an`int`

number indicating how many decimal digits we have.

So the value of a `BigDecimal`

number is: `unscaled / 10^<sup>scale</sup>`

### What is its purpose?

Floating-point math has some serious drawbacks that makes it impossible to use them in some kind of calculations, especially the financial ones (although some still uses them…you understand my rage now…). Countless bank software are using *fixed point math* to do their calculations: they are simply integer numbers on which is applied a fixed amount of decimal places (even very high). This approach can help mitigate *some* of the anomalies of floating-point math (IEEE 754), but at the price of a more difficult handling.

*java.math. BigDecimal* aim to solve these kind of problems, but they even go further with many useful rounding methods and an impressive high precision.

### How is it used

A fundamental characteristic of `BigInteger`

and `BigDecimal`

is that their instances are **immutable**: all their methods return a **new object** holding the result of the operation. Even methods like `setScale()`

, `movePointLeft() / movePointRight()`

or `negate()`

, that sounds like they’re modifying the object, return a new instance with the result.

Some examples:

```
package org.megadix.math;
import java.math.BigDecimal;
public class BigDecimalTest1 {
public static void main(String[] args) {
BigDecimal n1 = new BigDecimal("1000.123482248908085303458975309348");
System.out.println("n1 = " + n1);
BigDecimal n2 = new BigDecimal("2000.122837345398340801010291390210252");
System.out.println("n2 = " + n2);
BigDecimal resultAdd = n1.add(n2);
System.out.println("n1 + n2 = " + resultAdd);
BigDecimal resultMultiply = n1.multiply(n2);
System.out.println("n1 * n2 = " + resultMultiply);
BigDecimal resultDivide = n1.divide(n2, BigDecimal.ROUND_HALF_UP);
System.out.println("n1 / n2 = " + resultDivide);
}
}
```

Output:

```
n1 = 1000.123482248908085303458975309348
n2 = 2000.122837345398340801010291390210252
n1 + n2 = 3000.246319594306426104469266699558252
n1 * n2 = 2000369.817011446171094293893027628836590866233492522879727390461035696
n1 / n2 = 0.500031029882290273171404981367
```

Things to note:

- use of the
`BigDecimal(String)`

constructor. This constructoraccepts an english-like notation: sign, integer part, fraction and exponent. For the detail visit the official documentation (Javadoc); - the result of any operation is a new instance of
`BigDecimal`

; - the
`BigDecimal.toString()`

method is two-way compatible with`BigDecimal(String)`

constructor.

### Formatting

Decimal numbers formatting is a complicated matter:

- language and location: for example in GB or USA commas are used to separate thousands and dots to separate decimals, but in Italy and France it is the opposite;
- alphabet: characters used to represent numbers can vary, think about western, ebraic, arab, hindi…);
- leading/trailing zeroes: “.1”, “0.1”, “.10”, “0.1000”, …
- presence or not of sign symbols (+/-);
- scientific notation;
- …isn’t it enough?

Here is a simple example of formatting that sets language and number of decimal places:

```
package org.megadix.math;
import java.math.BigDecimal;
import java.text.NumberFormat;
import java.util.Locale;
public class BigDecimalTestFormat {
public static void main(String[] args) {
BigDecimal n = new BigDecimal("1000" +
"." +
"00000000000000000000000000000000000000000000000000" +
"1" +
"000");
NumberFormat fmt_EN = NumberFormat.getNumberInstance(Locale.ENGLISH);
fmt_EN.setMaximumFractionDigits(1000);
NumberFormat fmt_IT = NumberFormat.getNumberInstance(Locale.ITALIAN);
fmt_IT.setMaximumFractionDigits(1000);
System.out.println(fmt_EN.format(n));
System.out.println(fmt_IT.format(n));
}
}
```

Output:

```
1,000.000000000000000000000000000000000000000000000000001
1.000,000000000000000000000000000000000000000000000000001
```

Things to note

- the format string has been split into multiple rows for better readability;
- we leveraged the methods of
`java.text.NumberFormat`

for formatting; - we used the
`NumberFormat(java.util.Locale)`

constructor.

### Developments

These article has given you the basics to operate on `BigDecimal`

; anyway, you are strongly encouraged to read the official Java documentation.