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 yearDayOfYear
- a day-of-year without yearAmPm
- before or after middayQuarter
- the four quarters, Q1, Q2, Q3 and Q4YearQuarter
- combines a year and quarter, 2014-Q4YearWeek
- combines a week-based-year and a week, 2014-W06OffsetDate
- combinesLocalDate
andZoneOffset
Seconds
- an amount of time measured in secondsMinutes
- an amount of time measured in minutesHours
- an amount of time measured in hoursDays
- an amount of time measured in daysWeeks
- an amount of time measured in weeksMonths
- an amount of time measured in monthsYears
- an amount of time measured in yearsInterval
- an interval between two instantsLocalDateRange
- a range between two datesPeriodDuration
- combinesPeriod
andDuration
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.
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.
Related projects
See also the list of related projects.