All four of the newly introduced "xxxxxExact()" methods throw an ArithmeticException if the number contained in the BigInteger instance cannot be provided in the specified form (specified in the method's name) without loss of information. BigInteger already had methods intValue() and longValue() as well as inherited (from Number) methods shortValue() and byteValue(). These methods do not throw exceptions if the BigInteger value loses information in the presentation as one of these types. Although at first glance this may seem like an advantage, it means that code that uses the results of these methods uses values that are not accurate without any ability to know that information was lost. The new "xxxxxExact" methods throw an ArithmenticException rather than pretending to provide a result that has lost significant information.

The following simple code listing demonstrates the "legacy" methods that present wrong data in types byte, short, int, and long rather than throwing an exception. The same code also demonstrates use of the new "xxxxxExact" methods that throw an exception when information is lost rather than presenting a bad representation. The output of running this code follows the code and demonstrates how the methods behave differently when the BigInteger contains a value with more information than the returned byte, short, int, or long can represent.

BigIntegerDem.java output

Byte Max: 127
Byte Max: 127
Byte Max + 1: -128
java.lang.ArithmeticException: BigInteger out of byte range
at java.math.BigInteger.byteValueExact(BigInteger.java:4428)
at dustin.examples.jdk8.BigIntegerDemo.demonstrateBigIntegerByteValueExact(BigIntegerDemo.java:23)
at dustin.examples.jdk8.BigIntegerDemo.main(BigIntegerDemo.java:75)
Short Max: 32767
Short Max: 32767
Short Max + 1: -32768
java.lang.ArithmeticException: BigInteger out of short range
at java.math.BigInteger.shortValueExact(BigInteger.java:4407)
at dustin.examples.jdk8.BigIntegerDemo.demonstrateBigIntegerShortValueExact(BigIntegerDemo.java:36)
at dustin.examples.jdk8.BigIntegerDemo.main(BigIntegerDemo.java:84)
Int Max: 2147483647
Int Max: 2147483647
Int Max + 1: -2147483648
java.lang.ArithmeticException: BigInteger out of int range
at java.math.BigInteger.intValueExact(BigInteger.java:4386)
at dustin.examples.jdk8.BigIntegerDemo.demonstrateBigIntegerIntValueExact(BigIntegerDemo.java:49)
at dustin.examples.jdk8.BigIntegerDemo.main(BigIntegerDemo.java:93)
Long Max: 9223372036854775807
Long Max: 9223372036854775807
Long Max + 1: -9223372036854775808
java.lang.ArithmeticException: BigInteger out of long range
at java.math.BigInteger.longValueExact(BigInteger.java:4367)
at dustin.examples.jdk8.BigIntegerDemo.demonstrateBigIntegerLongValueExact(BigIntegerDemo.java:62)
at dustin.examples.jdk8.BigIntegerDemo.main(BigIntegerDemo.java:102)

As the above output demonstrates, the new BigInteger methods with "xxxxxExact" in their name will not present inaccurate representations when the returned type cannot hold the information in BigInteger instance. Although exceptions are generally not one of our favorite things, they are almost always going to be better than getting and using wrong data and not even realizing it is wrong.

Dustin Marx is a principal software engineer and architect at Raytheon Company. His previous published work for JavaWorld includes Java and Flex articles and "More JSP best practices" (July 2003) and "JSP Best Practices" (November 2001).