What Every Developer Should Know About Time

Introduction

How to handle time is one of those tricky issues where it is all too easy to get it wrong. So let's dive in.

First off, using UTC (also known as Greenwich Mean Time) is many times not the correct solution. Yet many programmers think that if they store everything that way, then they have it covered. (This mistake is why several years ago, when Congress changed the start of DST in the U.S., you had to run a hotfix on Outlook for it to adjust reoccurring events.)

What is Time

So let's start with the key question – what do we mean by time? When users says they want something to run at 7:00 am, what do they mean? In most cases, they mean 7:00 am where they are located – but not always. In some cases, to accurately compare say web server statistics, they want each "day" to end at the same time, unadjusted for DST. At the other end, someone who takes medicine at certain times of the day and has that set in their calendar, will want that to always be on local time so a 3:00pm event is not 3:00am when they have travelled half way around the world.

So we have three main use cases here (there are some others, but they can generally be handled by the following):

1. The same absolute (for lack of a better word) time.
2. The time in a given time zone, shifting when DST goes on/off (including double DST which occurs in some regions).
3. The local time.

The first is trivial to handle – you set it as UTC. By doing this every day of the year will have 24 hours. (Interesting note, UTC only matches the time in Greenwich during standard time. When it is DST there, Greenwich and UTC are not identical.)

The second requires storing a time and a time zone. However, the time zone is the geographical zone, not the present offset (offset is the difference with UTC). In other words, you store "Mountain Time," not "Mountain Standard Time" or "Mountain Daylight Savings Time." So 7:00 am in "Mountain Time" will be 7:00 am in Colorado regardless of the time of year.

The third is similar to the second in that it has a time zone called "Local Time." However, it requires knowing what time zone it is in in order to determine when it occurs.

Putting it to Use

Ok, so how do you handle this? It's actually pretty simple. Every time needs to be stored one of two ways:

1. As UTC. Generally when stored as UTC, you will still set/display it in local time.
2. As a datetime plus a geographical timezone (which can be "local time").

Now the trick is knowing which to use. Here are some general rules. You will need to figure this out for additional use cases, but most do fall into these categories.

1. When something happened – UTC. This is a singular event and regardless of how the user wants it displayed, when it occurred is unchangeable.
2. When the user selects a timezone of UTC – UTC.
3. An event in the future where the user wants it to occur in a timezone – datetime plus a timezone. Now it might be safe to use UTC if it will occur in the next several months (changing timezones generally have that much warning - although sometimes it's just 8 days), but at some point out you need to do this, so you should do it for all cases. In this case, you display what you stored.
4. For a scheduled event, when it will next happen – UTC. This is a performance requirement where you want to be able to get all "next events" where their runtime is before now. Much faster to search against dates than recalculate each one. However, this does need to recalculate all scheduled events regularly in case the rules have changed for an event that runs every quarter.
5. For events that are on "local time", the recalculation should occur anytime the user's timezone changes. And if an event is skipped in the change, it needs to occur immediately.

Browser Pain

The one thing we have not figured out is how to know a user's location if they are using a browser to hit our web application. For most countries, the locale can be used to determine the timezone – but not for the U.S. (6 zones), Canada, or Russia (11 zones). So you have to ask users to set their timezone – and to change it when they travel. If anyone knows of a solution to this, please let me know.

Update: I received the following from Justin Bonnar (thank you):

<input id="timezone_offset" type="hidden" name="timezone_offset" value="">
<script type="text/javascript">
document.getElementById('timezone_offset').value = new Date().getTimezoneOffset();
</script>

Using that plus the suggestion of the geo location for the IP address mentioned below will get you close. But it's not 100%. The time offset does not tell you if you for example if you are in Arizona (they & Hawaii do not observe daylight savings time) vs Pacific/Mountain (depending on DST) time zone. You also depend on JavaScript being on although that is true for 99% of the users out there today.

The geo location based on IP address is also iffy. I was at a hotel in D.C. when I got a report of our demo download form having a problem. We pre-populate the form with city, state, & country based on the geo of the IP address. It said I was in Cleveland, OH. So again, usually right but not always.

My take is we can use the offset, and for cases where there are multiple timezones with that offset (on that given day), follow up with the geo of the IP address. But I sure wish the powers that be would add a tz= to the header info sent with an HTML request.

Resources

• Original article (with screenshots of how Outlook handles this well)

History

• 18^th February, 2011: Initial post