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

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:

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.

The leap second data is provided in a text file loaded from the classpath. Only whole leap seconds are handled, and data starts from 1972 by default. To replace the built in leap seconds file, create a file META-INF/org/threeten/extra/scale/LeapSeconds.txt. The content should have two columns as per this format.

See also the list of related projects.

Back to top

Version: 1.7.2. Last Published: 2022-12-18.

Reflow Maven skin.