If you have a few years of experience in the Java ecosystem and you'd like to share that with the community, have a look at our **Contribution Guidelines**.

# Guide to Java BigInteger

Last modified: November 9, 2022

## 1. Introduction

Java provides some primitives, such as *int *or *long*, to perform integer operations. But sometimes, we need to store numbers, which overflow the available limits for those data types.

In this tutorial, we'll look deeper into the *BigInteger* class. We'll check its structure by looking into the source code and answer the question – **h****ow is it possible to store large numbers outside the limit of available primitive data types?**

## 2. *BigInteger* Class

As we know, the *BigInteger* class is used for mathematical operations which involve very big integer calculations larger than the primitive *long* type. It **represents immutable arbitrary-precision integers**.

Before going further, let's remember that in Java all bytes are represented **in the two's-complement system using the big-endian notation**. It stores the most significant byte of a word at the smallest memory address (the lowest index). Moreover, the first bit of the byte is also a sign bit. Let's inspect example byte values:

*1000 0000*represents*-128**0111 1111*represents 127*1111 1111*represents*-1*

So now, let's check the source code and explain how it stores given numbers exceeding available primitives limits.

### 2.1. *int signum*

The *signum* property **determines the sign of the BigInteger**. Three integer values represent the value's sign:

*-1*for negative,

*0*for zero,

*1*for positive numbers:

```
assertEquals(1, BigInteger.TEN.signum());
assertEquals(-1, BigInteger.TEN.negate().signum());
assertEquals(0, BigInteger.ZERO.signum());
```

Let's be aware that *BigInteger.ZERO* **must have the signum of 0** due to the magnitude array. This value ensures that there is

**exactly one representation for each**.

*BigInteger*value### 2.2. *int[] mag*

All the magic of the *BigInteger *class starts with the *mag* property. It **stores the given value in an array using the binary representation**, which allows omitting primitive data types limits.

Moreover, the *BigInteger* **groups them in 32-bit portions** – a set of four bytes. Due to this, the magnitude inside the class definition is declared as the *int* array:

`int[] mag;`

This array **holds the magnitude of the given value in big-endian notation**. The zeroth element of this array is the most significant int of the magnitude. Let's check it using *BigInteger(byte[] bytes)*:

```
assertEquals(new BigInteger("1"), new BigInteger(new byte[]{0b1}))
assertEquals(new BigInteger("2"), new BigInteger(new byte[]{0b10}))
assertEquals(new BigInteger("4"), new BigInteger(new byte[]{0b100}))
```

This constructor translates a given byte array containing the two's-complement binary representation into the value.

Since there's a sign-magnitude variable (*signum*), we **don't use the first bit as a sign bit of the value**. Let's quickly check it:

```
byte[] bytes = { -128 }; // 1000 0000
assertEquals(new BigInteger("128"), new BigInteger(1, bytes));
assertEquals(new BigInteger("-128"), new BigInteger(-1, bytes));
```

We created two different values using the *BigInteger(int signum, byte[] magnitude)* constructor. It translates the sign-magnitude representation into the *BigInteger.* We reused the same bytes array, changing only a sign value.

We can also print the magnitude using the *toString(int radix)* method:

```
assertEquals("10000000", new BigInteger(1, bytes));
assertEquals("-10000000", new BigInteger(-1, bytes));
```

Notice that for the negative values, the minus sign is added.

Finally, **the magnitude's most significant int must be non-zero**. This implies that the

*BigInteger.ZERO*has a zero-length mag array:

```
assertEquals(0, BigInteger.ZERO.bitCount());
assertEquals(BigInteger.ZERO, new BigInteger(0, new byte[]{}));
```

For now, we'll skip inspecting other properties. They are marked as deprecated due to redundancy, used only as internal cache.

Let's now go straight to the more complex examples and check how the *BigInteger *stores numbers over the primitive data types.

## 3. *BigInteger* Larger Than* Long.MAX_VALUE.*

As we already know, **the long data type is a 64-bit two's complement integer**. The signed long has a minimum value of -2

^{63}

*(1000 0000 … 0000)*and a maximum value of 2

^{63}-1

*(0111 1111 … 1111).*To create a number over those limits, we need to use the

*BigInteger*class.

Let's now create a value larger by one than *Long.MAX_VALUE*, equal to 2^{63}. According to the information in the previous chapter, it needs to have:

- a
*signum*property set to 1, - a
*mag*array, with 64 bits total, where only the most significant bit set*(1000 0000 … 0000).*

Firstly, let's create a *BigInteger* using the *setBit(int n)* function:

```
BigInteger bi1 = BigInteger.ZERO.setBit(63);
String str = bi1.toString(2);
assertEquals(64, bi1.bitLength());
assertEquals(1, bi1.signum());
assertEquals("9223372036854775808", bi1.toString());
assertEquals(BigInteger.ONE, bi1.substract(BigInteger.valueOf(Long.MAX_VALUE)));
assertEquals(64, str.length());
assertTrue(str.matches("^10{63}$")); // 1000 0000 ... 0000
```

Remember that in the binary representation system, bits are ordered from right to left, starting from 0. While the *BigInteger.ZERO* has an empty magnitude array, setting the 63rd bit makes it at the same time the most significant – the zeroth element of the 64 length array. The *signum* is automatically set to one.

On the other hand, the same bit sequence is represented by the *Long.MIN_VALUE*. Let's transform this constant into *byte[]* array and create construct the *BigInteger:*

```
byte[] bytes = ByteBuffer.allocate(Long.BYTES).putLong(Long.MIN_VALUE).array();
BigInteger bi2 = new BigInteger(1, bytes);
assertEquals(bi1, bi2);
...
```

As we see, both values are equal, so the same pack of assertions applies.

Finally, we can inspect the internal *int[]* *mag* variable. Currently, Java doesn't provide API to get this value, but we can do it by evaluation tool in our debugger:

We store our value in the array using two integers, two packs of 32-bits. The zeroth element is equal to *Integer.MIN_VALUE* and the other is zero.

## 4. Conclusion

In this quick tutorial, we focused on the implementation details of the *BigInteger* class. We started by reminding some information about numbers, primitives, and the binary representation rules.

Then we inspected the source code of the *BigInteger.* We checked *signum* and *mag* properties. We also learned how the *BigInteger* stores the given value, allowing us to provide larger numbers than available primitive data types.

As always, we can find all code snippets and tests over on GitHub.