1. Overview
Efficient time manipulation is necessary in many applications. We need methods to retrieve, format, and perform maths on time-representing variables. In this tutorial, we’ll learn how to use long arithmetic for date and time in Java.
2. The Instant Class
Since the introduction of Java 8, we can use the Instant class to express and manipulate dates and times. The lapse of time is measured since midnight January 1st, 1970, with a 24-hour period divided into 86400 seconds. As a good approximation, this Java time scale corresponds to a common civil time.
2.1. To Milliseconds and Back
We can use the Instant‘s toEpochMilli() method to obtain the number of milliseconds from 1970-01-01T00:00:00Z. The function returns a long number. So, let’s find the number of milliseconds corresponding to the current date and time obtained by the now() function:
long nowLong = Instant.now().toEpochMilli();
We can reverse this transformation with the help of the ofEpochMilli() function:
long someDayLong = 1_753_610_399_076L;
Instant someDay = Instant.ofEpochMilli(someDayLong);
Note the underscore ‘_’ character in the initialization of the long variable. We can put it wherever we want; here, we use it as a thousand separator.
2.2. Adding long to Instant
The Instant class offers a bunch of methods to perform arithmetic with long.
First, let’s examine the plus() method.
We need to provide the time amount as a long value and an object to represent the time unit. Let’s calculate 30 days from now:
long expirationPeriod = 2_592_000_000L; // 30 days in milliseconds
Instant now = Instant.now();
Instant expirationTime = now.plus(expirationPeriod, ChronoUnit.MILLIS);
By applying ChronoUnit.MILLIS constant we ask to interpret the long value as milliseconds.
If we don’t want to specify the time unit directly, we can pick the plusMillis() method, which accepts a long value:
Instant expirationTime = Instant.now().plusMillis(2_592_000_000L);
We use the plusNanos() and plusSeconds() methods to add nanoseconds and seconds, respectively.
2.3. Subtracting long From Instant
Next, let’s take a look at subtraction. We have the minus() function, syntax identical to plus(). So let’s move back in time by one day:
Instant aDayAgo = now.minus(86_400_000L, ChronoUnit.MILLIS); // one day in milliseconds
In addition, we have specialized functions to subtract nanoseconds, milliseconds, and seconds as long numbers. They are minusNanos(), minusMillis(), and minusSeconds(), respectively.
Finally, we can use the ‘plus’ set of functions as well, passing a negative time lapse as an argument:
Instant aDayAgo = now.plus(-86_400_000L, ChronoUnit.MILLIS);
3. Moving to long
With the Instant API, we have a comfortable set of methods to deal with data-time variables. It also provides a high level of clarity in interpreting the numbers it operates on. However, Instant is a value-based class. This means that its objects are immutable, and each operation creates a copy of the object the method is called on.
On the other hand, long is a primitive type, so we can work with long numbers without the overhead of creating extra objects.
So, let’s perform operations on time using long numbers and apply the Instant class methods only to retrieve and display the formatted time. The drawback is that we need to keep track of what the number represents (e.g., milliseconds, seconds, or hours) on our own.
Let’s rewrite our example of the 30-day expiration period:
long expirationPeriod = 30 // number of days
* 24 // hours in one day
* 3600 // seconds in one hour
* 1000L;// from seconds to milliseconds
long nowLong = Instant.now().toEpochMilli();
long expirationTimeLong = nowLong + expirationPeriod;
4. Conclusion
In this article, we learned how to perform arithmetic operations on data and time. We discussed the Instant class to convert the Java time into a long number and vice versa. Then, we performed addition and subtraction on Instant class objects and numbers. Finally, we moved the math operations to long numbers to reduce the burden of creating and removing Instant objects.
As always, the code for the examples is available over on GitHub.
