Updated Examples and Recipes (markdown)

Examples-and-Recipes.md

@@ -15,6 +15,7 @@ This page contains examples and recipes contributed by community members. Feel f
 - [Convert a time zone abbreviation into a time zone](#convert_by_timezone_abbreviation)
 - [Find all instances when a daylight savings shift is not 1 hour](#tz_search)
 - [How many timezones are using daylight saving?](#tz_daylight)
+- [What is the epoch difference between Unix Time and GPS time?](#unix_gps_epoch_diff)
 
 ***
 
@@ -704,6 +705,50 @@ This code loops over a wide range of years, and then for each year, loops over a
 The results of this program are plotted below (the plotting code is not part of the above program).
 
 ![Plot of daylight saving use by year](https://github.com/HowardHinnant/HowardHinnant.github.io/blob/master/tz_year.jpg)
+
+<a name="unix_gps_epoch_diff"></a>
+### What is the epoch difference between Unix Time and GPS time?
+(by [Howard Hinnant](https://github.com/HowardHinnant))
+
+This question is interesting because it has more than one answer.  And the reason it has more than one answer is because there are more than one measures.  You can blame it all on leap seconds.  But hopefully this library can help clarify the situation for you.
+
+[Unix Time](https://en.wikipedia.org/wiki/Unix_time) is what `sys_time` measures.  This is a count of _non-leap-seconds_ since 1970-01-01.  This measure is helpful because it provides an efficient vehicle for converting between field types such as `{year, month, day, hours, minutes, seconds}` and `{count_of_seconds}`.  It is what is measured by `std::chrono::system_clock`, `gettimeofday`, `std::time`, etc.  Unfortunately this solution is not without its problems.  One of them is that there exists no [Unix Time](https://en.wikipedia.org/wiki/Unix_time) which represents inserted leaps seconds in `utc_time` (and subsequently, even some seconds in `tai_time` and `gps_time`).
+
+This all means that subtracting two `sys_time` time points can give a different result than subtracting two time points of type `utc_time`, `tai_time`, or `gps_time`, and this example highlights that difference.
+
+First of all we need to get the `gps_time` epoch and the `sys_time` epoch.  We do not even need to know the dates of these epochs.  We can just use `0`:
+
+    auto gps_epoch  = gps_seconds{0s};  // 1980-01-06 00:00:00 UTC
+    auto unix_epoch = sys_seconds{0s};  // 1970-01-01 00:00:00 UTC
+
+These are both `std::chrono::time_point`s, but if we try to subtract them we will get a compile-time error because they refer to different clocks.  So to subtract them we must convert one to the other prior to subtracting.  Here is one way to do this:
+
+    std::cout << (gps_epoch - to_gps_time(unix_epoch)).count() << "s\n";
+
+This converts the `sys_time` to a `gps_time`, does the subtraction, and outputs:
+
+    315964809s
+
+In `gps_time`, there are 315,964,809 seconds between these two epochs.
+
+Here is another way:
+
+    std::cout << (to_sys_time(gps_epoch) - unix_epoch).count() << "s\n";
+
+which outputs:
+
+    315964800s
+
+In `sys_time`, there are 315,964,800 seconds between these two epochs.
+
+Why the 9s difference?  Because there were 9 leap seconds inserted between these two epochs, and `sys_time` does not count those 9 seconds, `gps_time` does.
+
+If you were to do this same experiment but using `utc_time` and `gps_time`, both measures would result in `315964809s` because both take leap seconds into account.
+
+Now wait a second, doesn't `gps_time` ignore leap seconds?!  Yes, but it does so by rolling its conversion to the civil calendar forward by one second.  Thus it doesn't ignore the physical second.  It ignores the time of day.  `sys_time` on the other hand, ignores the physical second's existence in the first place, thus keeping the mapping to the civil calendar the same as UTC.
+
+You can discover all kinds of neat subtleties by playing with `sys_time`, `utc_time`, `tai_time`, and `gps_time`.
+
 ***
 
 ![CC BY Logo](http://mirrors.creativecommons.org/presskit/buttons/80x15/svg/by.svg) _This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/)._