Durations, periods, formatting

Written Explanation

Duration: an exact amount of time

A Duration measures time in seconds and nanoseconds. The Javadoc calls it a fixed length of time. Use it for hours, minutes and seconds.

Duration d = Duration.between(LocalTime.of(8, 30), LocalTime.of(17, 45));
System.out.println(d);                  // PT9H15M
System.out.println(d.toHours());        // 9   (whole hours)
System.out.println(d.toMinutes());      // 555 (the whole duration in minutes)
System.out.println(d.toMinutesPart());  // 15  (the minutes left after the hours)

PT9H15M is the standard text form: P for period, T before the time part, 9 hours and 15 minutes. Two similar-looking families of methods matter:

• toHours(), toMinutes(), toSeconds() convert the whole duration to that unit.
• toHoursPart(), toMinutesPart(), toSecondsPart() give the part of that unit within the next larger one, which is what you display as 9:15.

Create durations with Duration.ofMinutes(135), Duration.ofHours(2), and so on. The result of between is negative when the end is before the start; call abs() for the size. Duration.between needs types that hold a time: it works for LocalTime, LocalDateTime, Instant and ZonedDateTime, but not for LocalDate, which has no seconds:

Unsupported unit: Seconds

A Duration treats a day as exactly 24 hours. Duration.ofDays(2) prints as PT48H, never as days.

Period: a calendar amount

A Period is years, months and days. Its real length depends on the dates it is applied to, because months differ.

Period p = Period.between(LocalDate.of(2025, 11, 20), LocalDate.of(2026, 3, 15));
System.out.println(p + " " + p.getMonths() + " " + p.getDays());   // P3M23D 3 23

P3M23D is three months and 23 days. Notice that Period keeps the parts separate: it does not convert months into days. Period.of(0, 1, 40) stays P1M40D. If you need the total number of days, use ChronoUnit.

ChronoUnit: one number in one unit

ChronoUnit.DAYS.between(a, b) counts the complete days between two values and returns a long:

long days = ChronoUnit.DAYS.between(LocalDate.of(2026, 3, 15), LocalDate.of(2026, 12, 31));
// 291

Other units exist: HOURS, MONTHS, YEARS, and so on. Pick ChronoUnit when you want a single total; pick Period when you want "3 months and 23 days"; pick Duration for exact elapsed time.

Days versus 24 hours across daylight saving

ZonedDateTime offers both kinds of addition. Date units (plusDays) work on the local calendar; time units (plusHours) work on the exact timeline. The Javadoc says so, and it matters on the spring change day in New York (8 March 2026):

ZonedDateTime s = ZonedDateTime.of(2026, 3, 7, 12, 0, 0, 0, ZoneId.of("America/New_York"));
s.plusDays(1);     // 2026-03-08T12:00-04:00[America/New_York]  same wall clock, a 23-hour gap
s.plusHours(24);   // 2026-03-08T13:00-04:00[America/New_York]  24 real hours later

So plusDays(1) means "tomorrow, same clock time" and plusHours(24) means "exactly 24 hours later". Likewise Period.ofDays(1) follows the calendar and Duration.ofDays(1) is 24 hours. Choose by meaning: a daily 09:00 meeting uses days; a 24-hour cache expiry uses hours.

Formatting and parsing with DateTimeFormatter

A DateTimeFormatter turns a date-time into text (format) and text into a date-time (parse) using a pattern.

DateTimeFormatter f = DateTimeFormatter.ofPattern("dd MMM yyyy", Locale.ENGLISH);
LocalDate date = LocalDate.of(2026, 3, 15);
System.out.println(f.format(date));                                           // 15 Mar 2026
System.out.println(date.format(DateTimeFormatter.ofPattern("dd/MM/yyyy")));   // 15/03/2026
LocalDate back = LocalDate.parse("15/03/2026", DateTimeFormatter.ofPattern("dd/MM/yyyy"));

Common pattern letters, from the Javadoc:

Case matters. MM is month and mm is minute. Writing yyyy-mm-dd compiles and runs, and silently prints the minute where the month should be (for 15 March 2026 at 09:05 it printed 2026-05-15). The same goes for HH:MM, which put the month 03 where the minutes belong.

Year letter. For ordinary dates yyyy works as expected; the Javadoc describes y as year-of-era and u as the proleptic year. For modern dates they give the same text, but uuuu is safer when you use strict parsing (see below).

Text depends on locale. MMM and a produce words, and the words depend on the Locale. ofPattern(pattern) uses the machine's default; ofPattern(pattern, Locale.ENGLISH) gives the same output everywhere. Pass a locale whenever the pattern has words.

Formatters are immutable and thread-safe, so keep them in a private static final constant instead of building one for each call.

Not every field exists in every type. Formatting a LocalDate with a time pattern throws:

Unsupported field: HourOfDay

Parsing: errors and leniency

LocalDate.parse(text, formatter) throws DateTimeParseException when the text does not match, with a message such as Text '2026-03-15' could not be parsed at index 2.

A surprise: with a default formatter built with yyyy, the text 31/02/2026 does not fail. It silently becomes 2026-02-28. The default resolver style is SMART, which adjusts a day of month up to 31 to the last valid day. If you want invalid dates rejected, use uuuu and .withResolverStyle(ResolverStyle.STRICT); then the message is Text '31/02/2026' could not be parsed: Invalid date 'FEBRUARY 31'. A day of 32 fails in either mode.

DateTimeFormatter strict = DateTimeFormatter.ofPattern("dd/MM/uuuu")
        .withResolverStyle(ResolverStyle.STRICT);