Understanding Time Zones

People who wrangle code for a living tend to think of time as a number. If you open the Developer Tools on this webpage, navigate to the Javascript console and type Date.now() it will return a number, which contributes to this abstraction mismatch. It encourages us to think, I can do math with this. You can, but only if you really understand how that number relates to the numbers you see on your clock. Thanks to our lifetime of experience reading clocks, we assume that’s all we need to know on the subject.

The notion of clock changes, let alone corrections rub that ideology the wrong way. If you think a Leap Second is bad, try coordinating something like the Julian or Gregorian reforms today. Sure, they solve different problems, but if you think time should be a linear, ever-increasing constant, you’re disagreeing with our understanding of relativity. Of course, by the time you need to worry about that, the next logical step from thinking time is a number is metric time, and if you think our system is problematic, imagine trying to convert years into units of 31.536 megaseconds.

While many programmers generally are aware of the Time Zone Database, in my experience few understand its relationship to the libraries they rely on. Like a lot of people, they think that because time seems simple and their lifetime of experience managing their calendar, they know what they need to know about it and never bother learning why their assumptions are bad.

The first thing you must understand about time zones is that they are a legal solution to the problem of coordination in a system of distributed humans. Like most legal solutions, they are an imperfect compromise reflecting the history and nature of the culture’s prevailing ruling caste. Like most legal solutions, they stem from political ideology, and fortunately it’s comparatively benign.

Before the locomotive and telegraph collapsed distance, the sun measured clock time: wherever you were, when a sundial said the sun was directly overhead, it was noon. The next town over might be a few minutes different, but getting there took a while, so it didn’t matter. Every town kept their own time. Thanks to axial tilt and the Earth’s elliptical orbit, the time of solar noon will vary throughout the year. You think time zones are bad? Imagine programming for that world.

Disruptive technologists came along and laid train tracks and telegraph wires, and suddenly travel got faster and communication got much faster. Distance collapsed. Trains were the first to use a coordinated clock time that didn’t track an exact solar time. They had a schedule to keep, and it was easier to measure against an arbitrary standard, called railway time.

Decades pass, and law enshrines the practice. Regions and nations draw boundaries, and in the rare case the next town over wasn’t setting their clock by the same standard as yours, it was exactly an hour different. The trains run on time, people coordinate their business by wire, and adjust to the new standard.

The second thing you must understand about time zones is that they aren’t going anywhere anytime soon. The sheer scale of coordination required to make it happen, the impact to people’s lives, is so large in scope, and will have so many unintended consequences it will be difficult to imagine. Imagine you’re the most influential programmer in the world:

You weren’t expecting the call from the United Nations, but they wanted to know: what one policy change would help software improve the world. They offered you an unprecedented level of political capital, but the decision was easy — convert the entire global economy to UTC. The recommendation passes, officials draw up a schedule, and every person on the planet has five years to prepare for the Conversion, as they’re calling it.

The Conversion proved to be a bigger deal than Y2K — it turns out this was far more involved than simply “change everyone’s local clock time to UTC”. Businesses have to update their hours, redraw tons of schedules, records and plans re-written. The cost is staggering, and no nation is ready to make the cut-over by the deadline except Iceland, who it turned out was already observing UTC year-round anyway and didn’t have to do anything.

Several nations try to back out of The Conversion, but they’re caught in a web of threatened sanctions, often by other nations that want to back out as well. Decades later, historians cited The Conversion as the cause for a war in the Middle East and the rise of authoritarian dictatorships in Southeast Asia. In continental Europe, the change of just one hour during winter and two during summer was enough to provoke riots and a hate group that smashes the fingers of programmers, calling themselves Ludd’s Children. They’ve abandoned clock time altogether in favor of meeting at the last light of the day and other such folksy malarkey.

In North America, people accepted The Conversion with less violence, but it turns out that communication between people with different daylight schedules still needs a context for understanding the phase of the day they’re in. On the west coast, they say they’re a thirdday behind, a subtle way of indicating to London colleagues that the meeting scheduled for Hour 13 is before sunrise.

NeoLudditism hasn’t caught on in the US the way it has in Europe, but after all the bugs caused by The Conversion — failures of traffic control and life support systems, years of chaos trying to get things right — things seem back to normal. Perhaps the best thing to come out of it is that no one wants to buy smart lightbulbs anymore.

There’s still about a century and a half of old legal records to convert. On the upside, a few corrupt corporations who were cooking their books no longer exist, but then there are horror stories of evidence in criminal trials thrown out, contracts mis-interpreted, and people who legally no longer exist. Half the relevant old records hadn’t been digitized yet, and a booming industry developed around helping businesses and municipalities comply with your clock time regulations.

You’ve caught a lot of flack for forcing this upon the world, and your name has become a curse. Bill Gates is busy working on malaria and the energy crisis and isn’t returning your calls anymore. People who used to be your friends asked Why time zones? Why not climate change or human trafficking? Why not economic disparity, genocide, religious fundamentalism, or any of a dozen other problems people consider more worthy of that kind of worldwide herculean coordination?

It was worth it you tell yourself, because programmers no longer have to think about time localities except when working on juicy contracts for legacy systems.

My dystopian story may be hyperbolic, but any proposal to abandon local clock time is ludicrously complex and will create greater problems than the one it aims to solve. This is why when otherwise reasonable people say things like local time is arbitrary, people can just have different schedules based on where they are in the world or abolishing time zones would make our lives so much easier, I say they act entitled. What I hear them say is: seven billion other people should radically change their lives so I don’t have learn a few things and think too hard about problems I’m being paid gobs of money to solve. The people who say, Well I can retrain my brain to get up at 11pm and go to bed at 3, so everyone else can too! also tend to think they’re much smarter than everyone else. They’re not.

If you work in software and think the world serves to make your life easier, please consider a different career. The world and the people who pay you will remind you time and again that you serve to make other peoples lives easier, not the other way around. You’re treating a human problem like a math problem, and by doing so, creating subtle bugs in your work that will at best frustrate your users. If they’re lucky, no one will come to their BBQ because everyone thought it was in the middle of the night. If they’re not lucky, you’ll kill them. It’s no wonder people have started to use programmers as scapegoats.

If it’s your thing, campaign to repeal daylight savings time. There’s a lot of bang for the buck in that. But you have a lot of legal entities to convince of this before the problem goes away, and it will only ever go away for the timekeeping of the future. Personally, I believe there are greater problems in the world deserving of attention. If you understand the domain of local clock time well and program defensively, you’ll get daylight saving time handling almost for free.

The third thing you need to know about time zones is they are fundamentally a locale problem.

In the United States, we write the date 3/31/2018 where most of the rest of the world writes 31/3/2018 instead. Some countries use a 12 hour clock while others use 24 hours, while some start counting at midnight, others start counting at dawn, and a few use times past 24 hours. But Time zones aren’t about formatting time — they are a locale-dependent method for representing UTC time as a clock time, so that Thur Mar 15 2018 00:00:00 GMT becomes Wed Mar 14 2018 17:00:00 GMT-0700 (PDT). There are already a lot of tools at our disposal for thinking about locale formatting, but understanding clock time and time zones as a locale problem makes thinking about them a lot simpler.

The fourth thing you need to know about time zones is the domain terminology. The terms and their meanings are straightforward, but I’ve met a lot of people with strongly held misconceptions about what means what.

When I refer to clock time, I’m talking about the time and date you see on the timekeeping device you use to know if you’re running late. It doesn’t matter where you live, if the device is synced to anything, or how accurate the clock is. It’s conveying a meaning you understand as a point in time.

UTC stands for Coordinated Universal Time. The abbreviation is a compromise against the French Temps Universel Coordonné so that the abbreviation is the same in English and French. UTC is the global standard for referencing a particular point in time. Time specified in UTC is the only time you should perform numerical arithmetic on. Unless you have a good reason, you should store time in UTC.

UTC is not equivalent to GMT. It is the successor to GMT, which is no longer precisely defined for scientific purposes. GMT can vary from UTC by up to 0.9 seconds. I have never heard someone use GMT when they did not mean to use UTC instead. Records in GMT before 1925 follow historical astronomic convention and treat noon as hour 0 and midnight as hour 12. Greenwich itself observes Western European Time, which includes British Summer Time.

The number commonly known as unix time is the number of seconds since midnight, January 1st, 1970, UTC, which we commonly call the Epoch. This is the only time that you can rightly do non-calendar arithmetic with. Unix time is generally the easiest way to reference a particular point in time, especially if you don’t care about the locality associated with the referenced point in time.

A UTC Offset is the difference from UTC in hours and minutes a place observes local clock time for a particular date and that’s it. For any given location, the offset could change throughout the year, and the rules for describing when the offset changes could change as well.

UTC Offsets are not time zones. If you have a local clock time and its offset, you may cast that time into UTC with the offset and then do math on it in UTC — but you may not then re-use the same offset to re-cast it to local clock time, unless you don’t mind the occasional subtle bug that will drive you and your users mad.

UTC Offsets may exceed twelve hours, and may be at intervals other than per-hour or half-hour. If you need to check a UTC-provided offset is valid, there is a canonical list, though it will change over time. Checking for half-hour intervals between -12:00 and +12:00 will fail valid UTC offsets.

There are a handful of islands with UTC offsets greater than +12:00, the furthest east of which are the Line Islands at +14:00, observing the same clock time as Hawai’i but one day ahead, and a part of the nation of Kiribati which is mostly on the other side of 180 degrees longitude. Nepal has the offset of +5:45, one of only three with a forty-five minute offset.

Standard Time is the setting of a local clock time to a particular offset from UTC. Because of the close relationship between time and longitude, it is possible to line up standard times on a map and pretend Daylight Saving Time doesn’t exist.

A time zone is a geographic area that observes a standard time, by culture, custom, or law. It is only by knowing an event’s time zone that you can reliably do timestamp math on it to arrive at an accurately different point in time.

Colloquially, people talk about time zones by their common names such as Eastern Time, but in a global context this is ambiguous. The time zone which includes New York City has different properties and history than does the one which includes Toronto, though their clocks read the same most of the year.

For precision, you should refer to timezones using their names from the IANA TZ Database (or TZDB), that is America/New_York and America/Toronto instead of Eastern Time or EST. If you look at the TZDB list and blanche, I can’t blame you. Its size is largely the result of legacy.

Abbreviations are no less ambiguous. While in the United States, you can reliably convey meaning with CST and CDT, the prior can refer to Cuba Standard Time and China Standard Time, and the latter Cuba Daylight Time. These are used for localization when you are displaying time to people who can interpret them unambiguously with context. You shouldn’t use them without localization.

Because time zones are political creations, both their geographic boundaries and rules for observing local clock time are subject to change through process of law. Thankfully, most of these changes trend towards simplification: consolidating multiple time zones into one, or simplifying daylight saving time rules.

If you’re not concerned with historical records, the distinction between America/Indiana/Indianapolis and most other America/Indiana/ -prefixed time zones won’t concern you. Before the Uniform Time Act of 1966 in the United States, municipalities defined their own rules for observing daylight saving time. The People’s Republic of China had 7 time zones, each of which now officially observe Beijing Time.

The Time Zone Database I mentioned above attempts to record all historical time zones and civil changes to time zones since the Unix Epoch. It defines a time zone as a geographic area where local clocks have all agreed since Epoch, and records the changes to the rules for determining a UTC offset for that zone. This is how the Javascript interpreter on your computer knows that in the United States, new Date(2018, 2, 15) is in Daylight Saving time, but new Date(2003, 2, 15) is in Standard Time.

Daylight Saving Time is the practice of setting the clock ahead during summer months to accommodate the fact that most people hate getting up early, and want to make the most of ample sunlight.

These days, most of the changes to time zones affect when or if daylight saving time is observed by that time zone. For example, in the United States, the Energy Policy Act of 2005 extended daylight saving time by five weeks in 2007. If you think that’s bad, Argentina decides annually if it should observe daylight saving time, and provinces may opt-out of the federal decision.

The daylight saving transition is the clock time lost or gained by observing daylight saving time. For the fall transition when we set the clock backward, if you want to be precise when rendering clock time around these times, you must include some indicator of offset in your display. For example, here in America/Los_Angeles, on November 1, 2015, 02:59:00 PDT is two minutes before 02:01:00 PST.

As of this writing, in 2018 the Spring Daylight Saving Transition (setting the clock forward) is observed:

• March 11th in The USA, Canada, parts of Mexico, Central America, and Thule Air Base in Greenland

• March 18th at Troll Station, Antarctica

• March 23rd in Israel

• March 24th in most of Greenland

• March 25th in most of Europe, Northern Africa, and Ittoqqortoormiit, Greenland

• March 30th in Syria

• March 31st in the Palestinian Territories

• April 1st in most of Mexico

• August 11th on Easter Island

• August 12th in most of Chile

• September 30th in New Zealand and parts of Antarctica

• October 7th in Australia

• November 4th in Brazil

If you want to see the Fall transition back, check the list. There is a clear takeaway from this list: DST changes happen regionally. In the United States, the transition happens when the previous clock time reads 2am — but other countries do this at different times. Brazil transitions at midnight, such that during the spring forward transition there is legally no precise point we typically call midnight.

If you noted with some dread my use of the phrase as of this writing, here’s another takeaway: It is impossible to reliably convert a future clock time to UTC in a manner that will remain precise until that moment passes, because the rules for converting that clock time to UTC might change by process of law.

A day in civilian terms is the period of time between the earliest point in the day — most often 00:00:00 — and the latest point in the day, typically 23:59:59.999 as measured by local clock time.

A day containing a daylight saving transition may contain 23 or 25 hours. Unless you’re dealing only with UTC time, you can’t just hard-code 86400 seconds as a magic number and call it a day. Remember — arithmetic with numbers on dates must be done in UTC. Most people understand that a month is not always 30 days, or that a year is not always 365 days, and they act accordingly. You should not treat days this way, either.

Since we often talk about spans of time such as two weeks from now, it is useful to talk about some concepts which seem to have different names in every programming library.

Sometimes called a Range or an Interval is the notion of two precise points in time separated by some distance. For example, when I say that I was on a phone call from 3:05pm to 3:24pm, March 11th, 2018, I am referring to two precise(-ish) points in time and the span between them.

Sometimes called a Period or a Duration is the notion of some length of clock time, such as two hours, or five months, two weeks, and six days. Earlier I said you can only do arithmetic on time when in UTC, but you can do math with clock time and these lengths. When you juxtapose this length of time to a fixed point in time, by saying something like I was employed there for three years, until yesterday then you can realize that length into a fixed range as described above.

Sometimes called an Interval or a Period is the notion of some repeating length of clock time, such as a day, a month, or a billing cycle.

If you’re working with other people on a project where these concepts are important, it’s worth agreeing on and documenting the terms you’ll use for these concepts. You can make a strong case for using the same terminology as the library code used by your project, but keep in mind that if you need to coordinate front- and back-end development, libraries may use different terminology.

When I first started this piece some time ago, I planned to lay out some practical tips for solving a few real problems. That kept expanding in scope and belongs in a separate article, which I can hopefully publish soon.

These concepts can be confusing because we often never learn them properly, and they can behave contrary to our expectations. Unless you spend a lot of time working with problems involving time, it can still be confusing. I didn’t even touch on the many, many problems that occur with the behavior of computers dealing with time in a distributed system.

Since my referenced tweet over five years ago, I’ve built scheduling, reporting, and query systems involving complex time manipulations. Each of these projects required me to improve my understanding of working with time as both humans and computers understand it. I still double-check myself often to make sure I understand what I want to accomplish.

What I don’t do anymore is complain about how hard the problem is. Dealing with it is part of the job, and understanding what I’m dealing with helps avoid frustration.