Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Date and Time

The ChronoUnit enum

Reference for java.time.temporal.ChronoUnit: measure the gap between two dates or times with between(), add and truncate values, and avoid common unit mistakes.

ChronoUnit is an enum in java.time.temporal that names the standard units of the calendar and the clock: NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF_DAYS, DAYS, WEEKS, MONTHS, YEARS, DECADES, CENTURIES, MILLENNIA, ERAS and FOREVER. It implements the TemporalUnit interface, which is what the date and time classes accept wherever they need "an amount of what".

Its most useful method is between(start, end). It counts how many whole units fit between two temporal values, which makes it the simplest way to answer "how many days until...?" or "how many months since...?".

Java
long days = ChronoUnit.DAYS.between(LocalDate.of(2026, 1, 1), LocalDate.of(2026, 3, 1));
// 59

Try it

Java Counting whole units between two dates

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Times, truncation and unsupported units

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
long between(Temporal temporal1Inclusive, Temporal temporal2Exclusive)
Member Description
between(start, end) Whole units from start to end; negative if end is earlier.
getDuration() The estimated Duration of one unit (months and years are averages).
isDateBased() true for DAYS and larger units.
isTimeBased() true for units smaller than DAYS.
isDurationEstimated() true for units whose length varies (DAYS and larger).
addTo(temporal, amount) Adds an amount of this unit; what plus(amount, unit) calls.

Parameters of between: the start is included, the end is excluded; both must be compatible types. If the second argument is a different type, it is converted to the first one's type when possible.

Returns: a long count of complete units, truncated toward zero.

Throws: UnsupportedTemporalTypeException when the unit is not supported by the type (hours between two LocalDate values), and DateTimeException when the second value cannot be converted to the first one's type.

Usage notes

  • Whole units only. between truncates: 59 days between two dates is 8 weeks, not 8.43. For a mixed result (years, months and days) use Period; for hours, minutes and seconds use Duration.
  • Month math follows the calendar. MONTHS.between counts complete calendar months, so 31 January to 30 April is 2 months, because the third month is not yet complete on the 30th.
  • Equivalent forms. start.until(end, ChronoUnit.DAYS) does the same as ChronoUnit.DAYS.between(start, end). Pick the one that reads better.
  • Unit and type must match. DAYS and larger work on LocalDate; HOURS and smaller need a time. Mixing them throws UnsupportedTemporalTypeException, a runtime exception, so test it.
  • Zones matter for ZonedDateTime. Days between two zoned values are computed on the local date-time fields, so a daylight saving change can make "one day" differ from 24 hours. Use HOURS if you really mean elapsed time.
  • FOREVER and ERAS exist for completeness. You will rarely use them.
  • The enum is immutable and thread-safe. Use == or switch to compare units.