As a software engineer, I'm sure you have experienced many a frustrating problem or two in your time. There's one problem that every time I have to deal with it, frustrates me like no other issue. Calendars, dates, times, and timezones. I don't meant to traumatize you, but we've gotta have a long talk.
Let's start with some terminology. A calendar is defined, by Wikipedia as
A system of organizing days for social, religious, commercial or administrative purposes. This is done by giving names to periods of time, typically days, weeks, months, and years.
The world's oldest known is called the Warren Field Calendar and is an arrangement of stone pits and an arc that was found in Warren Field, Aberdeenshire, Scotland. It's been dated to roughly 10,000 years old. Investigating these pits, researchers think the stones appear to represent the phases of the moon, going from waxing to waning along the arc, corresponding to the months of the year. They also see evidence that this calendar was calibrated every year and kept in good time, to align with the midwinter solstace.
There's one big problem with the Warren Field Calendar though, nobody knows exactly what it was used for. You see, the experts believe it was created by a Mesolithic group. The Mesolithics were a transition group of stone aged peoples who were able to adapt to a fishing and gathering economy, in addition to hunting.
One thing we can say for certain, as software engineers, this is where our problems began, but certainly not where they end.
So getting a little more modern, let's talk about a calendar most of us know well; the Gregorian calendar. Invented in 1582 by the Catholic church because Easter on the Julian calendar, as decreed by the first council of Nicaea, had drifted from the actual date of the spring equanox. Just so you're up to speed, the Julian calendar loses about 18 hours every century.
So the reason for the calendar is clear, a religous holiday wasn't at the right time anymore. Uh-oh.
So what was the Catholic world like in 1582? Pope Gregory XIII was head of the church, and the church was the official religion in quite a number of European countries, just to get started. Phillip II of Spain was 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 though. Anna Jagiellon was ruling the Polish—Lithuanian commonwealth, and made the switch in 1582 as well as the Papal states. The Spanish colonies made the switch as enough time passed to transit the Atlantic to deliver the news. One slight problem though…
THEY DIDN'T ALL PICK THE SAME DAY TO SKIP ABOUT 10 DAYS FORWARD!
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.
So what about the other religions that eventually moved onto the Gregorian calendar? Well you see, this involves a series of stories. Let's take the Protestant states first. They moved onto the Gregorian calendar around about 1700—That's 120 years later, for those of you keeping count. It also wasn't as smooth as you'd expect something like this to happen, or maybe better put: As ugly as you'd expect a calendar switch to be.
Not that I'll just gloss over all of the ugliness. Let's take a look at Sweden. Someone had the bright idea that instead of making the switch to the Gregorian calendar by skipping a bunch of days, they'd just not have leap years for a while, until the two calendars caught up with one another. Seems reasonable? Maybe 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. But, the story doesn't end here. Consider 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. 12 years later, they realized their system was totally bonkers, and abandoned the whole 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 to introduce a 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. This coincidentally, was approximately the same (but not the same) time as Britian.
While we're on the subject of days that only exist in certain countries, let's be equal opportunity 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.
Meanwhile, on March 30, 1867, the United States of America, 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 United States 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 had 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. Buuuuuut then they 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, China. You see, they switched to the Gregorian calendar after overthrowing the imperial monarchy in 1912. However, the Gregorian calendar was only used for official China business. The rest of the population continued to use the traditional Chinese calendar. Between 1916 and 1921 though, various warlords were in control at various 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 the south of China, Gregorian was reinstated in 1921. The north moved back onto the Gregorian calendar in 1928. Not only did China move onto the Gregorian calendar twice, but, the second time they switched to the Gregorian calendar, they did so in only half the country, then a number of years later, in the other part of the country.
Now, 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 others exceptions. Israel, for instance, uses Gregorian, but only along side the Hebrew calendar. Then there's Taiwan, they use the Gregorian calendar, but they've got their own little edits.
Ok, but let's say you can take into account all these exceptions, and all the times the calendars changed from one to the other and back again. You should be fine, right? Not really. You see, for many countries, the year didn't start on January 1. The Roman calendar didn't have January or February, so the year started on March 1. Remember, that the Gregorian calendar is based on the Roman calendar, in part.
A special case deserves mention here: The Republic of the Seven United Netherlands, aka Holland. They didn't move their year to start on January 1st, until a year after they moved onto the Gregorian calendar. Most other countries however, do start their year on January 1st.
So ok, sometimes the year starts on March 1st, sometimes January 1st. Even if you 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.
Yes, the Democratic Peoples Republic of Korea. In the DPRK, they use the Gregorian calendar, but with one major edit. They don'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. Juche year 1 is 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 chunk of the world does a dance twice every year (usually) with daylight savings time. I say usually, because there are cases where they just stopped, or observed it twice. Consider Britian during world war 2. They observed DST twice during the war years, making the timezone in Britian GMT+2 hours, 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 the corrected this discrepency.
Another special note, is Libya. In 2013, Libya changed from observing DST, to not, with only 2 days notice. How very nice of them. If I weren't a programmer, I'd consider giving 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. Often enough that there are sites that notify you when times are going to change with official messages from the governments involved. This data is used to update the code on your operating system. This system works well enough, when given enough time to react. 2 days, however, is not enough. Shame on you Libya.
I'm not going to talk more about time zones, as this blog post would never end. Let's just say, each year, several time zones change, sometimes more than once.
One thing to consider is that, in Universal Coordinated Time, we have this notion of leap seconds. Occasionally, the International Earth Rotation and Reference Systems Service usually gives you about 6 months notice of when these events are going to happen. Sometimes however, like in 2015, when we got 28 days notice that a leap second was to be added 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".
If you're still reading, let me salute you. Please take my message with you, don't implement a date and time library. None of them are 100% correct. You're often better off with your platform's native support, if it has it; or to figure out exactly what you're able to live with. Once you've got that nailed out, 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!