education-2022/selected/time.md

# Time

Time is a very deceptive topic for programmers. "I know how time works", they all think. "After all, I use a calendar and clock every day!" Unfortunately, human civilizations have been measuring time for a long time<sup>[citation needed]</sup>, and even our modern systems carry centuries of historical baggage. This article will attempt to give you a broad working knowledge of time, and how it pertains to the computer systems you will work on in your lifetime.

There are two major (and largely separate) concerns related to time: *when things happen* (instants in time), and *how long things take* (durations). We will cover each of them in turn.

No matter how confused you may become as you read this article, never forget that time always moves forward at the same rate everywhere. Nothing you do (switching timezones, changing clocks, etc.) can change this fact, and any confusion is simply the result of human notations for time. Unless you have to deal with relativity—in that case, god help you.

## When things happen: instants in time

The first major aspect of time for a programmer is the study of *when things happen*. This is the realm of calendars and clocks.

A first important distinction is the difference between *dates* and *times*.

- A *date* represents a particular day on a calendar. For example: May 21, 2022. The calendar you are primarily familiar with is the Gregorian calendar, although other calendar systems exist and have some limited use, particularly for holidays and other religious reasons.
- A *time* on its own represents a *time of day*—hours, minutes, seconds, and perhaps more depending on precision. For example: 7:45:00 PM.

Combining a *date* and a *time* gives you an precise instant in time, and is commonly called a *datetime* or *timestamp*. However, one more ingredient is needed to remove ambiguity: time zones.

Learning resources:

- TODO: uh is there really anything good to link here

### Time zones

You are already casually familiar with time zones. They reflect the very real fact that different locations on Earth experience the start and end of a day at different times. They are a major source of consternation for programmers, however, because they involve lots of human ambiguity and politics.

From a programmer's perspective, a time zone can be thought of as a bundle of the following:

- A *time offset* from UTC
- Rules for how this offset changes over time

The former is relatively easy to handle; the latter is fraught with politics and annoying edge cases, and will be discussed in the next section.

The time offset removes ambiguity by anchoring the time to UTC (Coordinated Universal Time), an international standard time that is continuous and unaffected by regional policy. A *timestamp* or *datetime* is thus a combination of date, time, and time zone or time offset. These three ingredients represent a fully-qualified, unambiguous instant in time.

It is worth noting that the time offset may not always be in increments of one hour. There are several time zones in current use that are offset by 30 or 45 minutes from the typical one-hour interval, and historical timezones that predate modern timekeeping may be offset by any arbitrary amount.

Resources:

- TODO: Definition of UTC
- https://www.timeanddate.com/time/time-zones-interesting.html (not a super great resource? find a better one?)

#### Aside: UTC and the International Date Line

Broadly speaking, UTC (Coordinated Universal Time) is the date and time at the prime meridian (zero degrees longitude), and is not subject to daylight savings or other discontinuities.

You may have also heard of GMT (Greenwich Mean Time). GMT is also centered at the prime meridian, but is UK-centric and therefore subject to some historical nonsense. UTC is the internationally standard successor, and the one appropriate for computer use.

The existence of the prime meridian necessitates a date cutoff point at roughly 180 degrees longitude. This is the International Date Line, the point at which you cross from UTC-12 to UTC+12 or vice versa, changing the date as necessary.

You might think that the International Date Line ensures that no two locations on earth have a time difference greater than 24 hours. But naturally, there are in fact time zones whose time offset is greater than 12 hours from UTC. Rules are made to be broken.

Resources:

- TODO: Definition of GMT and how it relates to BST and other British politics
- TODO: Definition of the IDL

### Daylight saving time and locations

Many locations on Earth observe regular changes to their timekeeping, shifting their clocks forward or backward by one hour to put sunrise and sunset in a different place relative to their working day. Many people, especially programmers, think this is stupid, but we programmers are stuck with it until every government on Earth decides to abolish this practice.

The most important implication of daylight saving time is that **you must not assume that a day is 24 hours long.** A calendar day may be 23 or 25 hours long, depending on the direction of the transition. The visible impact of this is that the day will either repeat or skip an hour, and this change may occur at different times of day depending on the location.

For example, time in Chicago on March 14, 2021 proceeded directly from 1:59:59 CST (Central Standard Time) to 3:00:00 CDT (Central Daylight Time). Likewise, on November 7, 2021, time proceeded directly from 1:59:59 CDT to 1:00:00 CST. Note that when repeating an hour, the time zone resolves the ambiguity.

To help you deal with daylight saving time, you may have heard mnemonics such as "spring forward, fall back", or the terms "gain an hour" and "lose an hour". These terms are unfortunately confusing and appear at times to be in conflict, so here is a cheat sheet:

| Coming from | Going to | Occurs in | Clock adjustment | Lived experience | Analogous to   |
| ----------- | -------- | --------- | ---------------- | ---------------- | -------------- |
| Standard    | DST      | Spring    | "Spring forward" | "Lose an hour"   | Traveling east |
| DST         | Standard | Fall      | "Fall back"      | "Gain an hour"   | Traveling west |

A useful gut-check for all this is to remember that the Sun rises in the east and sets in the west. Traveling west would thus mean traveling with the Sun and experiencing more daylight—hence, "gaining an hour", and having to adjust your clock _backward_ to account for the extra time in your day.

> Aside: there are many conflicting explanations for who originally proposed the practice of daylight saving time, why governments actually chose to adopt this practice, and why it has continued to this day. This article does not attempt to clarify any of this, but the author chooses to believe that all this is Benjamin Franklin's greatest prank of all time.

Resources:

- TODO

### Leap days and leap seconds
    - Within your lifetime, leap seconds will begin occurring about once a year - a very practical concern! 
    - Negative leap seconds possible
### Date representations, the Unix epoch, and the year 2038 problem
    - RFC 3339 and its pitfalls
    - Other profiles (ISO8601)
    - IANA tzdb

## How long things take: durations

Computer clocks

---

TODO:

- Style check:
    - em dashes
    - "Earth" and "Sun" are always capitalized
    - "time zone" is two words
    - "daylight saving time", not "daylight savings time"

---

EVERYTHING BELOW HERE IS OUR INITIAL BRAINSTORM

This will be our article three. Ben will get to this when he has time, unless someone else wants to jump in and lead the content of this.

- Timezones
    - They are not always on the hour
    - Difference time offset and timezone
        - (locale stuff, formatting, DST transition dates, etc.)
- Daylight savings
    - Days can be 23 or 25 hours long
    - Countries change their DST rules all the time
- Dates, times, datetimes
    - Maybe you don't actually want to store full timestamps for literally everything
- Time math is tricky
    - Adding 24 hours != adding one day (leap days / seconds)
- Calendars
    - Historical calendars are very weird (kings just removing or adding days when they felt like it)
    - The calendar we use, and its extensions: Gregorian calendar, proleptic Gregorian calendar
    - Other calendars: Jewish calendar, Chinese lunar calendar (?), Hijiri, Japanese calendar (?)
        - Primarily used for establishing holidays, but not really for common use any more (with the exception of China...?)
- Computer clocks
    - CPU time vs. wall time
    - Monotonic clocks
        - Two kinds on Linux: one that smears forward, one that does not
    - Jiffies
- Atomic clocks
- NTP / chrony
- Useful specs:
    - RFC3339: https://datatracker.ietf.org/doc/html/rfc3339
    - iCal: https://icalendar.org/RFC-Specifications/iCalendar-RFC-5545/
    - Recurrence rules (RRULE): https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html
- NOBODY USES ISO8601 STOP SAYING THAT THEY DO
    - NO ONE KNOWS WHAT IT IS
    - RFC3339 IS THE ONLY ONE ANYONE SHOULD USE
- Accuracy of onboard clocks
    - Quartz oscillators - subject to drift
    - How to correct inaccurate clocks
- Time smearing
- Presentation and formatting?
- The UNIX epoch, and the year 2038 problem
- ISO "week date" (does this matter to anyone)
- Falsehoods I think are actually important
    - "Always store time in UTC"
    - "Always store fully-qualified timestamps" i.e. datetimes with timezone, not just dates
    - "The smallest unit of time is X" (i.e. store the start and end of your time ranges precisely, never store 11:59:59)

You get a time you trust - then you work with it in some way (???)

- https://infiniteundo.com/post/25326999628/falsehoods-programmers-believe-about-time
- https://engineering.fb.com/2021/08/11/open-source/time-appliance/
- https://github.com/opencomputeproject/Time-Appliance-Project/tree/master/Open-Time-Server/
- https://lettier.github.io/posts/2016-04-26-lets-make-a-ntp-client-in-c.html
- https://audiogramii.wordpress.com/2018/03/31/time-smearing/
- https://docs.ntpsec.org/latest/leapsmear.html
- https://aws.amazon.com/blogs/aws/look-before-you-leap-the-coming-leap-second-and-aws/
- https://sudonull.com/post/29903-Writing-a-Simple-NTP-Client
- https://www.oreilly.com/library/view/linux-device-drivers/9781785280009/4041820a-bbe4-4502-8ef9-d1913e133332.xhtml
- https://www.youtube.com/watch?v=-5wpm-gesOY
- Official timezone database: https://www.iana.org/time-zones
    - Lots of excellent information and links here: https://data.iana.org/time-zones/tz-link.html
    - https://data.iana.org/time-zones/tz-how-to.html
    - "When Alaska was purchased from Russia in 1867, the Date Line moved from the Alaska/Canada border to the Bering Strait; and the time in Alaska was then 24 hours earlier than it had been. <aside>(6 October in the Julian calendar, which Russia was still using then for religious reasons, was followed by a second instance of the same day with a different name, 18 October in the Gregorian calendar. Isn’t civil time wonderful? 8-))</aside>"

## How to use dates and times

## Time accuracy / how to get accurate times

## Fun tangents

East Asian countries treat birthdays differently: https://en.wikipedia.org/wiki/East_Asian_age_reckoning. In particular, Koreans (and others??) all celebrate their birthday on January 1, and start counting at 1 instead of 0.