LocalTime Class in Java

Post author:Noel Kamphoa
Post published:May 5, 2024
Post category:Core Java Tutorials / Java Entry Level / Text, Date, Time, and Numeric Objects

1. Introduction

Java 8 introduced, through JSR 310, a complete overhaul of the Date/Time API by providing new, more advanced classes for Date processing. LocalTime is one such class that we will focus on in this article.

2. What is a LocalTime?

LocalTime is a class from the java.time package. The class represents a time in terms of time fields (hour, minute, second, nanosecond), without any date or time-zone information. The LocalDate and LocalDateTime classes are covered in separate articles.

The main particularity of LocalTime is that it is immutable and thread-safe.

3. Creating a LocalTime

There are two main ways of creating a LocalTime in Java. The first way is by using the LocalTime.now() methods and the second way is with the LocalTime.of() methods.

3.1. Using `LocalTime.now()` Methods

You can create a LocalTime object with the current time in this way:

        LocalTime now = LocalTime.now();//13:29:16.162023300

This will query the system clock in the default timezone.
Optionally, you can provide a custom Clock to the now() method:

        Clock clock = Clock.systemDefaultZone();
        LocalTime now = LocalTime.now(clock);

It is a best practice to pass a Clock into any method that requires the current instant. This has the advantage of making your code more testable.

Furthermore, if you need to construct a time object for a specific TimeZone, you can pass a ZoneId object to the now() method:

        ZoneId zoneId = ZoneId.of("Europe/Paris");
        LocalTime now = LocalTime.now(zoneId);

3.2. Using `LocalTime.of()` Methods

You can also create a LocalTime object by providing values for the hour, minute, and second:

        LocalTime time = LocalTime.of(13,30,5);//13:30:05

This will set the nanosecond field to zero. You can also pass only the hour and minute fields:

        LocalTime time = LocalTime.of(13,30);//13:30

The second and nanosecond fields are set to zero. Of course, you can still pass all the four fields:

        LocalTime time = LocalTime.of(13,30,10,30);//13:30:10.000000030

All these factory methods will throw a DateTimeException if the value of any field is out of range.

4. Formatting a LocalTime

By default, the LocalTime is formatted using the ISO-8601 24-hour time format. You can use a different format by passing a DateTimeFormatter object to the format() method:

        LocalTime time = LocalTime.of(13, 30);// 13:30
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("hh:mm a");
        String formattedTime = time.format(formatter);// 01:30 PM

5. Parsing from String to LocalTime

Assuming that you have a time in ISO-8601 time format and want to build a LocalTime out of it, you can use the parse() method in this way:

        String myTime = "13:30";// ISO-8601 time format
        LocalTime time = LocalTime.parse(myTime);// 13:30

Moreover, if the time is in a different format, you can pass a custom DateTimeFormatter to the parse() method:

        String myTime = "01:30 PM";//Custom format
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("hh:mm a");
        LocalTime time = LocalTime.parse(myTime,formatter);// 13:30

Java will throw a DateTimeParseException if it is not able to parse the String with the given time format.

6. Operating on a LocalTime

6.1. Comparing two LocalTime objects

You can use isAfter() and isBefore() methods to compare two LocalTime objects:

        LocalTime time1 = LocalTime.of(13,30);
        LocalTime time2 = LocalTime.of(13,28);
        LocalTime time3 = LocalTime.of(13,32);
        LocalTime time4 = LocalTime.of(13,30);
        boolean test1 = time1.isAfter(time2);//true
        boolean test2 = time1.isBefore(time3);//true
        boolean test3 = time1.isEqual(time4);//true

Since the LocalTime class implements the Comparable<E> interface, you may also use the compareTo() method:

        LocalTime time1 = LocalTime.of(13,30);
        LocalTime time2 = LocalTime.of(13,28);
        LocalTime time3 = LocalTime.of(13,32);
        int test1 = time1.compareTo(time2);// A positive number
        int test2 = time1.compareTo(time3);// A negative number

Lastly, you should know that the LocalTime class also overrides the equals() method and provides a convenient way to check the equality of two LocalTime objects:

        LocalTime time1 = LocalTime.of(13,30);
        LocalTime time2 = LocalTime.of(13,28);
        LocalTime time3 = LocalTime.of(13,30);
        boolean test1 = time1.equals(time2);// false
        boolean test2 = time1.equals(time3);// true

6.2. Temporal Arithmetic with LocalTime objects

The LocalTime class provides plusXXX() and minusXXX() methods to increment and decrement the object field values. Since the LocalTime is immutable, all these methods return a copy of the original object with the given fields updated.

        LocalTime time = LocalTime.of(13,30,10);//13:30:10
        LocalTime nextHour = time.plusHours(1);//14:30:10
        LocalTime previousHour = time.minusHours(1);//12:30:10
        LocalTime nextMinute = time.plusMinutes(1);//13:31:10
        LocalTime previousMinute = time.minusMinutes(1);//13:29:10
        LocalTime nextSecond = time.plusSeconds(1);//13:30:11
        LocalTime previousSecond = time.minusSeconds(1);//13:30:09