I have been building a time zone database library which uses the IANA Time Zone Database for the gleam programming language. When you start working with programming and time zones you realize that time is strangely complicated for computers. What seems simple to us—hours, days, years—is built on a foundation of physics, astronomical quirks, and human convention that creates enormous complexity. This post is a little context for a new time zone library I’m creating.

Physics Time vs. Human Time

From a physics perspective, if we ignore time dialation, time is straightforward. It’s a dimension we use to determine when events happen. We can pick a unit, the second, and measure the interval between any two events. If this were all we needed, we’d be done. We could simply count the number of seconds since a starting point (an “epoch”) and know exactly when anything occurred. For computers, this epoch is often midnight on January 1, 1970.

But we don’t live our lives in seconds-from-an-epoch. We organize our society around recurring natural cycles: the day and the year. We schedule meetings, open stores, and plan our lives based on concepts like “8:00 AM tomorrow.” This is where it starts to get complicated.

The Problem with the Earth’s Motion

Our primary cycle is the day: the time it takes for the sun to go from its highest point in the sky back to that same point. This period is approximately 86,400 seconds.

I say “approximately” because the Earth’s orbit around the sun is not a perfect circle; it’s an ellipse. This means the length of an apparent solar day (the actual time from one solar noon to the next) can vary by up to 30 seconds from the average. To smooth this out, we use the mean solar day, which is exactly 86,400 seconds.

To make this useful, we divide the day into 24 hours, hours into 60 minutes, and minutes into 60 seconds. This system, based on the position of the sun, is what we use for our daily lives.

The Rise of Time Zones

This system worked well enough until travel became fast. When every town set its clock by its own local solar noon, the time could differ by several minutes from the next town over. This was fine when travel was by horse, but it became a logistical nightmare for scheduling trains. A 30-minute train ride could result in a 22-minute time shift in one direction and a 38-minute shift in the other.

The solution was to coordinate. The world was divided into 24 time zones, each theoretically spanning 15 degrees of longitude and differing by one hour from its neighbors. Everyone within a zone would agree to use the same time.

Of course, political and geographic boundaries don’t follow neat longitude lines. Countries, states, and municipalities chose which time zone to belong to, creating the irregular, jagged time zone map we have today. To make things even more complex:

• Some regions, like India and parts of Australia, are on a 30-minute offset from their neighbors.
• A few places are even on 15 or 45-minute offsets.

Daylight Saving Time

Another layer of complexity is Daylight Saving Time (DST). Because the length of a day changes with the seasons, some regions decided to shift their clocks forward by an hour in the summer. The goal was to better align waking hours with daylight hours.

This means that twice a year, time abruptly shifts by an hour. But not everyone participates. Many countries near the equator don’t observe it, and even within the United States, states like Arizona and parts of Indiana opt out. This adds another set of rules to an already complicated system.

Leap Seconds

Here is the final, and most technical, wrinkle. The idea that a mean solar day is exactly 86,400 seconds is also just an approximation. The Earth’s rotation is not perfectly regular; it’s gradually slowing down, but in an unpredictable way.

To keep our civil time (Coordinated Universal Time, or UTC) in sync with the Earth’s actual rotation, the International Earth Rotation Service occasionally inserts an extra second into the clock. This is called a leap second. Since 1970, 27 days have actually been 86,401 seconds long.

Most computer systems, including Unix time, ignore this. They assume every day is exactly 86,400 seconds long. This makes calculating the duration between two dates simple, but it means the clock is not a true measure of the seconds that have passed in the physical world. For applications that require that level of precision, you must account for these leap seconds. The official time zone database (the IANA database) includes special time zones (prefixed with right/, like right/UTC) that correctly account for every leap second ever inserted.

Conclusion

So, measuring time requires us to reconcile a precise, atomic unit (the second) with a messy, irregular planet and universe. We deal with:

• The difference between mean and apparent solar time.
• Irregular, politically-defined time zones.
• Twice-yearly shifts for Daylight Saving Time, which aren’t universally applied.
• The unpredictable insertion of leap seconds to align our clocks with the Earth’s wobbly rotation.

Hopefully, this gives you a new appreciation for the complexity hidden behind something as simple as looking at a clock—and why a robust software library is necessary to manage it all.

Note: This entry was written with the assistance of a large language model. I provided a 20 minute audio file of what I wanted to present, and the language model transcribed the recording and organized it into an article which I subsequently edited.