Friends Never Let Friends Implement Date Libraries

April 19, 2016

As a software engineer, I’m sure you have experienced a frustrating problem or two in your time. There’s one problem that every time I have to deal with it, it frustrates me like no other issue: calendars, dates, times and time zones. 

Friends never let friends implement date libraries

Let’s start with some terminology. A calendar is defined by Wikipedia as:



The Warren Field Calendar

The world’s oldest known calendar is called the Warren Field Calendar. This calendar is an arrangement of stone pits and an arc that was found at Warren Field in Aberdeenshire, Scotland, and it’s roughly 10,000 years old. While investigating these pits, researchers think the stones appeared to represent the phases of the moon going from waxing to waning along the arc and corresponding to the months of the year. There is also evidence that this calendar was calibrated every year and kept in good time to align with the midwinter solstice.

There’s one big problem with the Warren Field Calendar though: nobody knows exactly what it was used for. You see, experts believed it was created by a Mesolithic group. The Mesolithics were a transition group of stone age people who were able to adapt to a fishing, hunting and gathering economy.

One thing we can say for certain as software engineers is that this is where our problems began and certainly not where they end.

Let’s talk about a calendar most of us know well: the Gregorian calendar. The Catholic church invented the calendar in 1582. The date as decreed by the first council of Nicaea had drifted from the actual date of the spring equinox. Just so you’re up to speed, the Julian calendar loses about 18 hours every century.

The reason for the calendar is clear: a religious holiday wasn’t at the right time anymore. Uh-oh.

So what was the Catholic world like in 1582? Pope Gregory XIII was the head of the church, and Catholicism was the official religion in a large number of European countries. Phillip II of Spain was the leader of Spain and Portugal, as well as a large chunk of Italy, and decreed the change from the Julian to Gregorian calendars. He wasn’t alone. Anna Jagiellon ruled the Polish-Lithuanian commonwealth and made the switch to the Gregorian calendar in 1582 along with the Papal states. The Spanish colonies made the switch when enough time had passed to transit the Atlantic to deliver the news. One slight problem though…


This means that if you pick a random day in 1582, there’s a pretty good chance that day doesn’t exist in at least one European country. But what about the other religions that eventually moved to the Gregorian calendar? Well you see, this involves a series of stories.

Let’s take the Protestant states first. They moved to the Gregorian calendar around 1700 – that’s 120 years later for those of you keeping count. It also wasn’t as smooth as you’d expect a calendar switch to be.

Feb1712.jpgSwedish calendar in 1712

Take a look at Sweden; someone had the bright idea to, instead of making the switch to the Gregorian calendar by skipping a bunch of days, entirely exclude leap years until the two calendars caught up with one another. Seems reasonable. Until you realize that they planned to spend 40 years with their own unique notion of the date. A notion that meant their version of the date wouldn’t line up with either the Julian or Gregorian calendars.

The story doesn’t end here. Consider the idea that they didn’t even stick with it. In 1700, they skipped the leap year, according to plan, but due to the Great Northern War, they didn’t skip the next two. Twelve years later, they realized their system was totally bonkers and abandoned the entire idea. They spent 8 of those years not doing what their system told them to.

Is this the end of the Swedish story? Of course not! Instead of just skipping the days to line up with everyone else, they decided to move back to the Julian calendar and introduce February 30, 1712. Special note: This is the only year where February 30th is a legal Julian date, but ONLY in Sweden.

Time passes…

…more time passes…

Then finally 50 years later, Sweden moved onto the Gregorian calendar by jumping forward and skipping a bunch of days.  Coincidentally, this was approximately the same (but not the same) time as Britain.

While we’re on the subject of days that only exist in certain countries, let’s be equal opportunists and talk about Samoa. In 2011, Samoa skipped December 30th, 2011, when they switched sides of the international date line for economic reasons. Samoa went directly from December 29th to December 31st.

On March 30, 1867, the United States bought Alaska from Russia for $7.2 million. Not only did they get a giant chunk of land in the deal, but they also got the Julian calendar. Keep in mind at this time, the U.S. had already been on the Gregorian calendar, so this wouldn’t do. Alaska moved onto the Gregorian calendar on October 6th, 1867. But here’s where we encounter another screwy bit of information; due to the move across the international date line, Alaska didn’t skip the 12 days they were supposed to, but instead only skipped 11 and repeated October 18th, 1867.

Russia? Oh yeah, almost forgot. Russia didn’t move onto the Gregorian calendar until 1918. BUT, they later changed to the Soviet calendar in 1929 and then changed back to the Gregorian calendar in 1940.

Speaking of countries that switched calendars multiple times, let’s talk about China. You see, the Chinese switched to the Gregorian calendar after overthrowing the imperial monarchy in 1912. However, the Gregorian calendar was only used for official Chinese business. The rest of the population continued to use the traditional Chinese calendar. Between 1916 and 1921, various warlords were in control at different times and decided to use whatever calendar they thought was best.

From 1921 to 1928, the fight for northern China was still ongoing between various warlords. But in southern China, the Gregorian calendar was reinstated in 1921. The North moved back to the Gregorian calendar in 1928. Not only did China move on to the Gregorian calendar twice, but the second time they switched to the Gregorian calendar, they did it in only half the country. Then a number of years later, they switched to the Gregorian calendar in the other part of the country.

There are still countries on the planet that still don’t use the Gregorian calendar. Iran is a good example of a country that rejects it entirely, but there are other countries with their own exceptions. Israel, for instance, uses Gregorian, but only alongside the Hebrew calendar. Then there’s Taiwan, they use the Gregorian calendar, but they’ve got their own personal edits.

Let’s just say you can take into account all of these exceptions and all the times the calendars changed from one to the other and back again. You should be fine, right? Not really. For many countries, the year didn’t start on January 1st. The Roman calendar didn’t have January or February, so the year started on March 1st. Remember that the Gregorian calendar is based on the Roman calendar, in part.

A special case deserves a mention here: the Republic of the Seven United Netherlands, aka Holland. They didn’t decide to have their year start on January 1st until a year after they moved to the Gregorian calendar. Most other countries, however, do begin their year on January 1st.

So, sometimes the year starts on March 1st and sometimes on January 1st. Even if you can handle that, and let’s say you can narrow it down well enough to do so, then you have other cases to consider… North Korea.


The Juche Calendar in North Korea

Yes, the Democratic People’s Republic of Korea. In the DPRK, they use the Gregorian calendar, but with one major edit. They didn’t observe normal reckoning. Their calendar is called the Juche calendar and all years are based on Kim Il-sung’s date of birth, April 15th, 1912. The first year on the Juche calendar is actually 1912 in the Gregorian calendar. However, until 1997, the Gregorian calendar was the official calendar of the DPRK. From a programming point of view, this one’s fairly easy; just subtract 1911 if the year is after 1912. If it’s before 1912, then you don’t have to worry, there’s no concept of years less than 1 in the Juche calendar. Time started in 1912.

Time zones are fun too. Let’s not forget that a good portion of the world does a dance twice every year (usually) with daylight savings time. I say ‘usually’ because there are cases where countries just stopped or observed it twice. Consider Britain during World War II. They observed DST twice during the war years, making the timezone in Britain GMT+2 hours. All this despite being the place where the Royal Observatory in Greenwich is located; where GMT got its name, Greenwich Mean Time. It wasn’t until 1945 that they corrected this discrepancy.

Another special note is Libya. In 2013, Libya changed from observing DST to not observing, with only two days notice. How very nice of them. If I weren’t a programmer, I’d consider cutting them a little slack given that they were in the heart of a civil war at the time. But I am a programmer, and that’s a toss your hands in the air crazy amount of lead time to adjust our code.

Time zones change regularly. So regularly that there are sites that actually notify you when times are going to change with official messages from the respective government. This data is used to update the code on your operating system. This system works well enough when given enough time to react. Two days, however, is not enough. Shame on you Libya.

But, enough about time zones. Let’s just say that each year, several time zones change, sometimes more than once.

One thing to consider is in Universal Coordinated Time, we have this notion of leap seconds. Occasionally, the International Earth Rotation and Reference Systems Service gives you about six months notice when these events are going to happen. Sometimes however, like in 2015, we receive only 28 days notice that a leap second will be added on to June 30th, at 23:59:60. Yes, 11:59:60 PM. You might ask, 61 seconds in a minute, how’s that possible? Well you see, this is exactly what a leap second is. We add an extra second to a minute. Sometimes people refer to this as “replaying a second.”

Please take my message with you, don’t implement a date and time library. None of them are 100% correct. If you have it, you’re better off with your platform’s native support or figuring out exactly what you’re able to live with. Once you’ve got that nailed down, pick the most mature and widely used option. Save your own headaches, and the headaches of third party developers everywhere – don’t write your own!

Published April 19, 2016


Leave a Reply
