Do You Know What Time It Is?

At what time does the Scandinavian Airlines plane from Oslo to Athens arrive on Monday? Why are questions that seem so easy in day to day life, so difficult in programming? Time should be simple, just seconds passing, something a computer is very good at measuring:

System.currentTimeMillis() = 1570964561568

Although correct, “1570964561568” is not what we want, when we ask what time it is. We prefer “1:15pm, October 13th 2019”.

It turns out that time is two separate things. On the one hand, we have seconds passing. On the other, we have an unhappy marriage between astronomy and politics. Answering the question “What time is it?” depends on the location of the sun in the sky relative to your position along with the political decisions made in that region up to that point in time.

Many of the problems we have with date and time in code come from mixing these two concepts. Using the latest java.time library (or Noda Time in .NET) will help you. Here there are three main concepts to help you reason correctly about time: LocalDateTime, ZonedDateTime, and Instant.

LocalDateTime refers to the concept “1:15pm, October 13th 2019”. There can be any number of these on the timeline.

Instant refers to a specific point on the timeline. It is the same in Boston as in Beijing. To get from a LocalDateTime to an Instant, we need a TimeZone, which comes with UTC offsets and daylight savings time (DST) rules at the time.

ZonedDateTime is a LocalDateTime with a TimeZone.

Which ones do you use? There are so many pitfalls. Let me show you a few:

Let’s say you’re writing software to organize an international conference. Will this work?

public class PresentationEvent {
  final Instant start;
  final Instant end;
  final String title;
}

Nope.

While we need to represent a particular point in time, for future events, even when we know the time and the time zone, we cannot know the instant ahead of time, because DST rules or UTC offsets might change between now and then. We need a ZonedDateTime.

How about regularly occurring events? Like a flight. Will this work?

public class Flight {
  final String flightReference;
  final ZonedDateTime departure;
  final ZonedDateTime arrival;
}

Nope.

This can fail twice a year. Imagine a flight leaving Saturday at 10pm, arriving Sunday at 6am. What happens when we move the clock back an hour because of daylight savings? Unless the aircraft circles uselessly during the extra hour, it’s going to land at 5am, not 6am. When we move ahead one hour, it’ll arrive at 4am. For recurring events with duration, we cannot fix both the start and end. We need:

public class Flight {
  final String flightReference
  final ZonedDateTime departure;
  final Duration duration;
}

What about events that start 2:30am? Which one? There may be two, or it might not exist at all. In Java, the following methods handle the autumnal DST transition:

ZonedDateTime.withEarlierOffsetAtOverlap()
ZonedDateTime.withLaterOffsetAtOverlap()

In Noda Time you would specify both DST transitions explicitly with Resolvers.

I have only scratched the surface of potential issues, but as they say “Good tools are half the work”. Use java.time (or Noda Time) and you’ve saved yourself a lot of errors.