How do libraries in different programming languages handle Date & Time, Timestamps & Durations, Leapseconds & -years, DSTs & Timezones, ...?

Question

Is there a standard body or a specific normative way how time-related things should be implemented in practice (like ICU for Unicode-related tasks) or is this currently a "best-effort", depending on how much effort, time and money language and library implementers want to spend?

Is there a specific and complete implementation which could serve as a example for how time-related things should be handled?

Which existing library would you consider as a bad, a decent or a good example?

Answer 1

I'll try to give an answer to the second and third question using the Java library which might become part of Java 7.

javax.time.* (JSR 310)

These classes are a complete rewrite of JodaTime trying to fix the design flaws of util.Date/util.Time as well as JodaTime.

JSR 310 tries to provide a comprehensive model for date and time, which is type-safe and self-documenting. It is interoperable with existing classes, but also considers XML- and DBMS-based use-cases. The classes are final, immutable, thread-safe and cannot be modified after construction. Instances are created via a rich set of Factory methods which can cache things in the background.

LocalDate dateToday     = LocalDate.of(2010, 9, 14); LocalDate oneMonthLater = dateToday.with(OCTOBER); LocalDate oneYearLater  = dateToday.withYear(2011); 

The API has some "machine-oriented" classes and some "human-oriented" classes:

Machine-oriented

Instant

For a point of time comparable to an Unix or Java timestamp. Actually there are Instant, TAIInstant and UTCInstant which enable people to exactly choose which definition of time they need i. e. "day-based", "linear, without leap seconds" etc.

Duration

A time range not necessarily associated with a specific Date or Calendar.

Human-oriented

There is a rich collection of classes handling different use-cases like Date-only, Time-only, Time and Date, with and without Timezones, with and without DST.

DateProvider

OffsetDate, LocalDate (, java.sql.Date compatibility)

TimeProvider

OffsetTime, LocalTime (, java.sql.Time compatibility)

DateTimeProvider

ZonedDateTime, OffsetDateTime, LocalDateTime (, java.util.GregorianCalendar compatibility)

InstantProvider

Instant, ZonedDateTime, OffsetDateTime (, java.util.Date compatibility)

Period

Periods represent a time span like "5 days" that can be added and subtracted from a date/time.

Matcher

Matchers enable queries like "is this date in the year 2006?" or "is this day the last day of this year".

Adjuster

Adjusters come to the rescue if you have want to make more complex changes, like "Give me the last day of the month!" or "The second Tuesday after Christmas, please!".

Resolver

Resolvers allow users to define what should happen if a certain date is not valid, like February 31st 2010:

DateResolver previous = DateResolvers.previousValid(); LocalDate date = date(2010, 2, 30, previous); // date = 2010-02-28 

Working with Timezone and DST data

It is possible to serialize these classes and deserialize them using either the current timezone data or the timezone data when they were serialized. Additionally, rules from different timezones can be compared: It is possible to find out if DST rules have changed, e. g. between version 2010e and 2010f for Dates in London or Moscow and decide what should be done if a Time is in a gap or overlap.

Calendar systems

Although everything is based on ISO-8601, simple calendars for Hebrew, Hijrah, Japanese, ThaiBuddist, etc. time systems are provided.

Formatting and Parsing

toString() returns ISO8601 and patterns like those in SimpleDateFormat and more advanced are supported.

Integration

• Databases
• JodaTime
• Legacy JDK classes (java.util.*)
• XML

---

References:

• https://jsr-310.dev.java.net/nonav/doc-2010-06-22/index.html
• JavaZone 2010 - Stephen Colebourne: Time to fix it! - JSR-310 Date and Time API