With all the shiny things (lambda expressions, streams, Optional, the new Date/Time API, etc.) to distract my attention that came with JDK 8, I did not pay much attention to the addition of the method Math.toIntExact(). However, this small addition can be pretty useful in its own right.
The Javadoc documentation for Math.toIntExact(long) states, "Returns the value of the long argument; throwing an exception if the value overflows an int." This is particularly useful in situations where one is given or already has a Long and needs to call an API that expects an int. It's best, of course, if the APIs could be changed to use the same datatype, but sometimes this is out of one's control. When one needs to force a Long into an int there is potential for integer overflow because the numeric value of the Long may have a greater magnitude than the int can accurately represent.
If one is told that a given Long will never be larger than what an int can hold, the static method Math.toIntExact(Long) is particularly useful because it will throw an unchecked ArithmeticException if that "exceptional" situation arises, making it obvious that the "exceptional" situation occurred.
When Long.intValue() is used to get an integer from a Long, no exception is thrown if integer overflow occurs. Instead, an integer is provided, but this value will rarely be useful due to the integer overflow. In almost every conceivable case, it's better to encounter a runtime exception that alerts one to the integer overflow than to have the software continue using the overflow number incorrectly.
As a first step in illustrating the differences between Long.intValue() and Math.toIntExact(Long), the following code generates a range of Long values from 5 less than Integer.MAX_VALUE to 5 more than Integer.MAX_VALUE.
Generating Range of Longs that Includes Integer.MAX_VALUE
/**
* Generate {@code Long}s from range of integers that start
* before {@code Integer.MAX_VALUE} and end after that
* maximum integer value.
*
* @return {@code Long}s generated over range includes
* {@code Integer.MAX_VALUE}.
*/
public static List<Long> generateLongInts()
{
final Long maximumIntegerAsLong = Long.valueOf(Integer.MAX_VALUE);
final Long startingLong = maximumIntegerAsLong - 5;
final Long endingLong = maximumIntegerAsLong + 5;
return LongStream.range(startingLong, endingLong).boxed().collect(Collectors.toList());
}
The next code listing shows two methods that demonstrate the two previously mentioned approaches for getting an int from a Long.
Using Long.intValue() and Math.toIntExact(Long)
/**
* Provides the {@code int} representation of the provided
* {@code Long} based on an invocation of the provided
* {@code Long} object's {@code intValue()} method.
*
* @param longRepresentation {@code Long} for which {@code int}
* value extracted with {@code intValue()} will be returned.
* @return {@code int} value corresponding to the provided
* {@code Long} as provided by invoking the method
* {@code intValue()} on that provided {@code Long}.
* @throws NullPointerException Thrown if the provided long
* representation is {@code null}.
*/
public static void writeLongIntValue(final Long longRepresentation)
{
out.print(longRepresentation + " => Long.intValue() = ");
try
{
out.println(longRepresentation.intValue());
}
catch (Exception exception)
{
out.println("ERROR - " + exception);
}
}
/**
* Provides the {@code int} representation of the provided
* {@code Long} based on an invocation of {@code Math.toIntExact(Long)}
* on the provided {@code Long}.
*
* @param longRepresentation {@code Long} for which {@code int}
* value extracted with {@code Math.toIntExact(Long)} will be
* returned.
* @return {@code int} value corresponding to the provided
* {@code Long} as provided by invoking the method
* {@code Math.toIntExact)Long} on that provided {@code Long}.
* @throws NullPointerException Thrown if the provided long
* representation is {@code null}.
* @throws ArithmeticException Thrown if the provided {@code Long}
* cannot be represented as an integer without overflow.
*/
public static void writeIntExact(final Long longRepresentation)
{
out.print(longRepresentation + " => Math.toIntExact(Long) = ");
try
{
out.println(Math.toIntExact(longRepresentation));
}
catch (Exception exception)
{
out.println("ERROR: " + exception);
}
}
When the above code is executed with the range of Longs constructed in the earlier code listing (full code available on GitHub), the output looks like this:
2147483642 => Long.intValue() = 2147483642 2147483642 => Math.toIntExact(Long) = 2147483642 2147483643 => Long.intValue() = 2147483643 2147483643 => Math.toIntExact(Long) = 2147483643 2147483644 => Long.intValue() = 2147483644 2147483644 => Math.toIntExact(Long) = 2147483644 2147483645 => Long.intValue() = 2147483645 2147483645 => Math.toIntExact(Long) = 2147483645 2147483646 => Long.intValue() = 2147483646 2147483646 => Math.toIntExact(Long) = 2147483646 2147483647 => Long.intValue() = 2147483647 2147483647 => Math.toIntExact(Long) = 2147483647 2147483648 => Long.intValue() = -2147483648 2147483648 => Math.toIntExact(Long) = ERROR: java.lang.ArithmeticException: integer overflow 2147483649 => Long.intValue() = -2147483647 2147483649 => Math.toIntExact(Long) = ERROR: java.lang.ArithmeticException: integer overflow 2147483650 => Long.intValue() = -2147483646 2147483650 => Math.toIntExact(Long) = ERROR: java.lang.ArithmeticException: integer overflow 2147483651 => Long.intValue() = -2147483645 2147483651 => Math.toIntExact(Long) = ERROR: java.lang.ArithmeticException: integer overflow
The highlighted rows indicate the code processing a Long with value equal to Integer.MAX_VALUE. After that, the Long representing one more than Integer.MAX_VALUE is shown with the results of attempting to convert that Long to an int using Long.intValue() and Math.toIntExact(Long). The Long.intValue() approach encounters an integer overflow, but does not throw an exception and instead returns the negative number -2147483648. The Math.toIntExact(Long) method does not return a value upon integer overflow and instead throws an ArithmeticException with the informative message "integer overflow."
The Math.toIntExact(Long) method is not as significant as many of the features introduced with JDK 8, but it can be useful in avoiding the types of errors related to integer overflow that can sometimes be tricky to diagnose.
No comments:
Post a Comment