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...?".
long days = ChronoUnit.DAYS.between(LocalDate.of(2026, 1, 1), LocalDate.of(2026, 3, 1)); // 59
Try it
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.
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
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.
betweentruncates: 59 days between two dates is 8 weeks, not 8.43. For a mixed result (years, months and days) usePeriod; for hours, minutes and seconds useDuration. - Month math follows the calendar.
MONTHS.betweencounts 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 asChronoUnit.DAYS.between(start, end). Pick the one that reads better. - Unit and type must match.
DAYSand larger work onLocalDate;HOURSand smaller need a time. Mixing them throwsUnsupportedTemporalTypeException, 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. UseHOURSif you really mean elapsed time. FOREVERandERASexist for completeness. You will rarely use them.- The enum is immutable and thread-safe. Use
==orswitchto compare units.
Related
LocalDate,Duration,Period,DayOfWeekandMonth- Lessons: Dates and times