17.3 Using Temporal Units and Temporal Fields
Temporal units and temporal fields allow temporal objects to be accessed and manipulated in a human-readable way.
For temporal units and temporal fields supported by the Period and Duration classes, see §17.5, p. 1057, and §17.6, p. 1064, respectively.
Temporal Units
The java.time.temporal.TemporalUnit interface represents a unit of measurement, rather than an amount of such a unit—for example, the unit years to qualify that an amount of time should be interpreted as number of years. The java.time.temporal.ChronoUnit enum type implements this interface, defining the temporal units by constant names to provide convenient unit-based access to manipulate a temporal object. Constants defined by the ChronoUnit enum type include the following temporal units, among others: SECONDS, MINUTES, HOURS, DAYS, MONTHS, and YEARS.
The output from Example 17.4 shows a table with all the temporal units defined by the ChronoUnit enum type. It is not surprising that not all temporal units are valid for all types of temporal objects. The time units, such as SECONDS, MINUTES, and HOURS, are valid for temporal objects that are time-based, such as LocalTime, LocalDateTime, and Instant. Likewise, the date units, such as DAYS, MONTHS, and YEARS, are valid units for temporal objects that are date-based, such as LocalDate, LocalDateTime, and ZonedDateTime.
A ChronoUnit enum constant can be queried by the following selected methods:
Duration getDuration()
Gets the estimated duration of this unit in the ISO calendar system. For example, ChronoUnit.DAYS.getDuration() has the duration PT24H (i.e., 24 hours).
boolean isDateBased()
boolean isTimeBased()
Check whether this unit is a date unit or a time unit, respectively. For example, ChronoUnit.HOURS.isDateBased() is false, but ChronoUnit.SECONDS.isTimeBased() is true.
boolean isSupportedBy(Temporal temporal)
Checks whether this unit is supported by the specified temporal object. For example, ChronoUnit.YEARS.isSupportedBy(LocalTime.MIDNIGHT) is false.
static ChronoUnit[] values()
Returns an array containing the unit constants of this enum type, in the order they are declared. This method is called at (2) in Example 17.4.
The temporal classes provide the method isSupported(unit) to determine whether a temporal unit is valid for a temporal object. In Example 17.4, this method is used at (3), (4), and (5) to determine whether each temporal unit defined by the ChronoUnit enum type is a valid unit for the different temporal classes.
The following methods of the temporal classes all accept a temporal unit that qualifies how a numeric quantity should be interpreted:
- minus(amount, unit) and plus(amount, unit), (p. 1040)
LocalDate date = LocalDate.of(2021, 10, 23);
System.out.print(“Date ” + date);
date = date.minus(10, ChronoUnit.MONTHS).minus(3, ChronoUnit.DAYS);
System.out.println(” minus 10 months and 3 days: ” + date);
// Date 2021-10-23 minus 10 months and 3 days: 2020-12-20
LocalTime time = LocalTime.of(14, 15);
System.out.print(“Time ” + time);
time = time.plus(9, ChronoUnit.HOURS).plus(70, ChronoUnit.MINUTES);
System.out.println(” plus 9 hours and 70 minutes is ” + time);
// Time 14:15 plus 9 hours and 70 minutes is 00:25
- until(temporalObj, unit), (p. 1040)
LocalDate fromDate = LocalDate.of(2021, 3, 1);
LocalDate xmasDate = LocalDate.of(2021, 12, 25);
long tilChristmas = fromDate.until(xmasDate, ChronoUnit.DAYS);
System.out.println(“From ” + fromDate + “, days until Xmas: ” + tilChristmas);
// From 2021-03-01, days until Xmas: 299