1. Overview
When working with time and duration calculations in Java, the TimeUnit enum provides a convenient way to perform time conversions between different units.
Whether we want to convert seconds to minutes, milliseconds to hours, or perform any other time unit conversion, we can use TimeUnit to simplify the code, get accurate results, and make things more readable.
In this tutorial, we’ll look at using TimeUnit to convert time in Java.
2. Understanding TimeUnit
TimeUnit is an enum, included in the java.util.concurrent package, that represents various units of time, ranging from nanoseconds to days. It provides a set of predefined constants, each corresponding to a specific unit of time, including:
- DAYS
- HOURS
- MINUTES
- SECONDS
- MILLISECONDS
- MICROSECONDS
- NANOSECONDS
These constants serve as the basis for time conversions.
3. Converting Time Using TimeUnit
To perform a time conversion, we need to have a value representing the duration we want to convert and specify the target unit we wish to convert to. TimeUnit offers several methods for converting time between units, such as convert() or toXXX(), where XXX represents the target unit.
3.1. Using the convert() Method
First, let’s look at the convert(long sourceDuration, TimeUnit sourceUnit) method, which converts the given time duration in a given unit to the unit specified by the enum value.
Let’s convert a simple integer to minutes:
long minutes = TimeUnit.MINUTES.convert(60, TimeUnit.SECONDS);
assertThat(minutes).isEqualTo(1);
In this example, we start with a value of 60 seconds and then convert it to minutes. We specify the source time unit as the second argument. The output unit is always determined by the enum value.
Let’s check out another example, where we do the reverse conversion:
long seconds = TimeUnit.SECONDS.convert(1, TimeUnit.MINUTES);
assertThat(seconds).isEqualTo(60);
As we see, the convert() method converts time between different units.
3.2. Using the toXXX() Method
Let’s now explore the toXXX(long sourceDuration) methods. Here the XXX in the signature specifies the target unit.
We can choose units with toNanos(), toMicros(), toMillis(), toSeconds(), toMinutes(), toHours(), and toDays().
Now let’s rewrite both previous snippets using the toXXX() methods:
long minutes = TimeUnit.SECONDS.toMinutes(60);
assertThat(minutes).isEqualTo(1);
As before, we’ve just converted 60 seconds to minutes.
And we can convert the other way:
long seconds = TimeUnit.MINUTES.toSeconds(1);
assertThat(seconds).isEqualTo(60);
As expected, the above examples produce the same result as before, so both signatures are equivalent. But unlike convert(), when we use the toXXX() methods, the enum value represents the source time unit.
4. Specific Use Cases
Now that we know how to convert time using the TimeUnit methods, let’s explore some more detailed scenarios.
4.1. Negative Inputs
Firstly, let’s check if the converting methods support negative input values:
long minutes = TimeUnit.SECONDS.toMinutes(-60);
assertThat(minutes).isEqualTo(-1);
The given example shows that negative inputs are also handled by the converting methods, and the returned result is still correct.
4.2. Rounding Handling
Let’s now check what happens if we convert a smaller unit to a larger one, expecting a target non-integer result. We know that all methods only declare long as a return type, so decimal results cannot be returned.
Let’s test the rounding rule by converting seconds to minutes:
long positiveUnder = TimeUnit.SECONDS.toMinutes(59);
assertThat(positiveUnder).isEqualTo(0);
long positiveAbove = TimeUnit.SECONDS.toMinutes(61);
assertThat(positiveAbove).isEqualTo(1);
Then, let’s check the negative inputs:
long negativeUnder = TimeUnit.SECONDS.toMinutes(-59);
assertThat(negativeUnder).isEqualTo(0);
long negativeAbove = TimeUnit.SECONDS.toMinutes(-61);
assertThat(negativeAbove).isEqualTo(-1);
As we see, all conversions are handled without any errors.
We should note that all methods implement a rounding toward zero rule that truncates the decimal part.
4.3. Overflow Handling
As we know, all primitives have their value limits which cannot be exceeded. But what happens if the result overflows the limit?
Let’s check the result of converting the minimum and maximum long values of days to milliseconds:
long maxMillis = TimeUnit.DAYS.toMillis(Long.MAX_VALUE);
assertThat(maxMillis).isEqualTo(Long.MAX_VALUE);
long minMillis = TimeUnit.DAYS.toMillis(Long.MIN_VALUE);
assertThat(minMillis).isEqualTo(Long.MIN_VALUE);
The above code executes without throwing any exceptions. We should note that the result isn’t valid, because the overflow results are always truncated to minimum or maximum values defined by the long primitive.
5. Converting to the Finest Unit
Sometimes, we may need to convert a duration to the finest unit available in TimeUnit, such as converting seconds to the appropriate combination of hours, minutes, and leftover seconds. Unfortunately, there’s no method for this. This is because all the conversion methods always return the total number of whole periods within a given duration.
To convert the input to the finest unit, we need to implement a custom function. Let’s use the value of 3672 seconds and fetch an appropriate combination of time units – we expect the value of 1 hour, 1 minute, and 12 seconds.
To extract hours we can use:
long inputSeconds = 3672;
long hours = TimeUnit.SECONDS.toHours(inputSeconds);
assertThat(hours).isEqualTo(1);
Now, if we want to extract the remaining minutes, we should subtract the sum of seconds contained in hours from the input value, and then use this value for further operations:
long secondsRemainingAfterHours = inputSeconds - TimeUnit.HOURS.toSeconds(hours);
long minutes = TimeUnit.SECONDS.toMinutes(secondsRemainingAfterHours);
assertThat(minutes).isEqualTo(1);
We’ve just successfully calculated the hours and minutes based on the input data. Finally, we need to retrieve the remaining seconds.
To do this, we repeat the subtraction logic, remembering to adjust the parameters:
long seconds = secondsRemainingAfterHours - TimeUnit.MINUTES.toSeconds(minutes);
assertThat(seconds).isEqualTo(12);
In the example, we’ve just converted 3672 milliseconds to the finest unit representation, which includes hours, minutes, and seconds.
6. Conclusion
In this article, we explored various ways to convert time using the TimeUnit enumeration in Java.
The TimeUnit enum provides a convenient and efficient way to convert between different units using convert() and toXXX() methods.
In addition, it also handles negative inputs and returns correct results. We can easily convert durations, regardless of whether we’re converting from a smaller to a larger unit or vice versa, with rounding toward zero. It also implements basic overflow protection by trimming the result to borderline values.
If we want to convert a source duration to the appropriate combination of other units (such as days, hours, minutes, and seconds), we can easily implement additional logic. All converters return the total number of specified periods within a specified duration.
As always, the source code for the examples is available over on GitHub.