Dates

It’s quite extraordinary how difficult it can be to get things right when writing a computer program which cares about dates and or times, even if you’re just talking about the Gregorian calendar ( the one most people use, certainly in a business context ). The purpose of this post is to explain the issues when handing Gregorian dates and times, and to discuss how different languages/libraries tackle them, and what to do to get things working properly if you are forced to use a combination of different tools/apis.The additional complexities of support for other calendrical systems can wait for another time.

There is a lot of misinformation out there, and even when articles are accurate, they are seldom focused on what you need to know. So let’s dive in.

Months

If I give the date as 3/5/2015, then if I’m an American, I probably mean 5th March, but otherwise I probably mean 3rd May. If I give it as 3rd May 2015, I’m unambiguous, but might not be understood by a non-english speaker. The one safe approach is 2015-05-03, which also has the advantage of sorting correctly in a list.

Am/Pm

Let’s add a time of day. If I tell you it’s 2015-07-22 11:20, then you probably think it’s mid morning. But some parts of the world still use am and pm and don’t always bother to say which. So 11:20 might mean 23:20. This ambiguity is particularly awkward as there is no way to tell for sure that a time specified as just 11:20 is using the 24 hour clock. However, there’s very little choice but to work on the assumption that if the hour is between 1 and 12 and no am or pm is specified that we are using the 24 hour clock. And certainly, in anything we produce, we should only ever use a 24 hour clock.

Timezones

So now if I tell you that it’s 2015-07-22 07:34, you might think that you know what time I mean. But of course, that depends on where in the world we each are. I need to provide you with a timezone too. There are several ways I might do that:

• I can specify the precise offset in hours and minutes between my time and UTC (UTC is the official name for what is often called GMT ). In this case I’m actually writing this in France in August, so the offset is +2:00 ( one hour for France and another for summer time ).
• I can specify a base timezone and whether there is a summer time adjustment (+1h + DST)
• I can specify my location and jurisdiction ( France ) and let you look up the timezone and DST rules in some authoritative list.

Although in theory each of the three approaches above should work, as we go down the list, we have more work to do and more room for error.

• DST rules and even timezones change.
• Different systems differ as to the exact textual name they use for timezones. For example, a timezone choice in windows and the same timezone in Linux will have completely different names. A human being might find it easy to tell which is which, but a computer probably can’t.

Oh, and if the date we are specifying is one on which the clocks go back, then a time like 02:00 France could mean either midnight or 01:00 in UTC…. This can be a real problem for timed 24 hour events even if no travel is involved.

ISO standard

There is an international standard ISO8601 which specifies a format for writing dates and resolving the ambiguities above: So using ISO8601 we would specify: 2015-07-22T07:22:00+02:00 which in UTC is 2015-07-22T05:22:00+00:00 which we can shorten to 2015-07-22T05:22:00Z

The ISO standard is unambiguous when used in this way. So our rule 1 is:

• Whenever a point in time needs to be transmitted across a connection between computers it must be formatted using iSO8601

Fun with calendars

So that’s all there is to it? Not quite! Thanks to the ISO standard, we can safely describe a point in time unambiguously, and furthermore do so in a way which retains a timezone offset. But sometimes, we really do need to specify a timezone in the legal sense.

Suppose we are writing a calendar application, and we want to support repeating appointments and be able to invite people from across the world to a regular conference call. We are based in France and specify the call to take place at 13:00 every Wednesday with the first call on 2015-01-07. Some of our participants are in London, or New York, some in Arizona and some in Sydney Australia. If the call remains at 13:00 in France, then what happens when any of the countries involves moves to or from daylight saving?

The Brits will be fine because the UK uses the same DST rules as France. So when France moves to DST at the end of March, so does the UK. So on 1st April, the call will take place an hour earlier in UTC terms, but at the same clock time in both France and the UK. Using ISO dates, in March the call takes place at 13:00+01:00 = 12:00Z which corresponds to 12:00+00:00 in the UK, while in April it is at 13:00+02:00 = 13:00Z which corresponds to 12:00+01:00 in the UK.

But for the US, things are not so rosy. By 11th March, New York has already moved to DST. So a call which was at 08:00 local time on 4th March will be at 09:00 local time on 11th March, and then return to 08:00 local time on 1st April.

Arizona doesn’t have DST, so in its case the call will remain at 06:00 until April, and then be at 05:00 for the summer.

And Sydney moves from DST on 5th April ( Southern hemisphere end of summer time ). So in March, the call will be at 1am on Thursday mornings. The first call in April will take place at midnight on Thursday April 2 local time, and the next at 11pm on Weds April 8th.

From the above, it should be obvious that in order to implement this kind of calendar, we have no choice but to have at our disposal detailed information as to how to calculate the correct timezone offset for any relevant date at any relevant location.

Dates without time

Our next issue is how to interpret a date without a time, something like 2015-06-03. The problem here is that depending on the use to which the date is put, the rules for how to interpret it in other places will vary. For example, if my birthday is 29th March, because I was born on that date in London, I would probably still choose to celebrate it on 29th March locally even if I happened to be in Hawaii, where the exact moment of my birth was on 28th March in that timezone. But if I’m trying to book a colleague into a hotel in New Zealand on 3rd December and I’m in Hawaii, I’d better remember that most of 3rd December in New Zealand is still 2nd December in Hawaii.

Web confusion

The issues above have been around for a long time, in fact most of them existed before computers did. But one particular issue has really only become significant since the web became ubiquitous.

Suppose I am running a web service from my datacentre in London, and a user, who is usually based in Paris, logs in from New York. It’s almost inevitable that my application will care about dates and times to some extent, but what should my user see? – dates and times which reflect the fact that this is a London based system? – dates and times which reflect the fact that this is a Paris based user? – dates and times which reflect the fact that the session is taking place in New York? – dates and times which reflect the fact that the computer being used is a borrowed laptop set to San Francisco time? – dates and times in a timezone which the user can choose for themself, and change on demand.

Here, there’s no right answer. But what is important is that whichever of the above answers you want, your platform allows you to implement it. Unfortunately, that’s not at all easy, as we’ll see when we come to discuss how various common environments deal with dates and times.