ThreeTen-Extra – User guide

User guide

ThreeTen-Extra is a small library that builds on the Java SE 8 java.time package.

Value types

The additional value types operate exactly as per similar classes in Java SE 8. These include:

DayOfMonth - a day-of-month without month or year
DayOfYear - a day-of-year without year
AmPm - before or after midday
Quarter - the four quarters, Q1, Q2, Q3 and Q4
YearQuarter - combines a year and quarter, 2014-Q4
YearWeek - combines a week-based-year and a week, 2014-W06
OffsetDate - combines LocalDate and ZoneOffset
Seconds - an amount of time measured in seconds
Minutes - an amount of time measured in minutes
Hours - an amount of time measured in hours
Days - an amount of time measured in days
Weeks - an amount of time measured in weeks
Months - an amount of time measured in months
Years - an amount of time measured in years
Interval - an interval between two instants
LocalDateRange - a range between two dates
PeriodDuration - combines Period and Duration

Additional fields and units

Temporals provides additional utilities for working with Temporal objects. This includes adjusters, queries, parsing helpers, converters and comparators.

TemporalFields provides additional fields and units. These include day-of-half, half-of-year and half-years.

Note that due to a design flaw in the JDK, methods should be invoked on TemporalAccessor or Temporal rather than on TemporalField or TemporalUnit. For example, these two methods are supposed to return the same result, but they do not:

 YearQuarter yq = YearQuarter.of(2014, Quarter.Q4);
 
 boolean supportedA = yq.isSupported(IsoFields.QUARTER_OF_YEAR);   // true
 boolean supportedB = IsoFields.QUARTER_OF_YEAR.isSupportedBy(yq); // false!!
 
 long quarterA = yq.get(IsoFields.QUARTER_OF_YEAR);     // 4
 long quarterB = IsoFields.QUARTER_OF_YEAR.getFrom(yq); // throws UnsupportedTemporalTypeException!!

When TemporalField was designed, it was thought that there could be perfect symmetry between these two methods. However, in reality the design only works if the method on the temporal is viewed as the primary method, and the method on the field is viewed as a framework-level method, that should not be invoked directly by callers.

Period/Duration formatting

The JDK does not provide a mechanism to format periods or durations beyond ISO-8601. A simple mechanism is provided here in AmountFormats:

 Period period = Period.of(1, 6, 5);
 String str = AmountFormats.wordBased(period, Locale.ENGLISH);
 // output: "1 year, 6 months and 5 days"

Translations are provided for bg, ca, cs, da, de, en, es, fa, fi, fr, it, ja, nb, nl, nn, pl, pt, ro, ru, sv, tr. Feel free to raise PRs for other languages.

Calendar systems

The additional calendar systems operate exactly as per similar classes in Java SE 8. These include:

Accounting calendar system
British Cutover calendar system
Coptic calendar system
Discordian calendar system
Ethiopic calendar system
International Fixed calendar system
Julian calendar system
Pax calendar system
Symmetry010 calendar system
Symmetry454 calendar system

Time scales

The JDK operates exclusively using the Java time-scale, defined in Instant. That time-scale eliminates leap seconds using UTC-SLS, although the JDK implementation is typically based on a POSIX-like clock (and thus relatively undefined around leap seconds).

ThreeTen-Extra provides the additional classes that were rejected from JDK 8. They were not included as they were deemed to be too specialized for the JDK.

Use TaiInstant if you need an instant using the TAI time-scale.

Use UtcInstant if you need an instant using the UTC time-scale.