From 21e33b0a6fef95eb830389faeb2b5af48e4c0d63 Mon Sep 17 00:00:00 2001
From: HowardHinnant <howard.hinnant@gmail.com>
Date: Tue, 22 Mar 2016 20:34:26 -0400
Subject: [PATCH] Updated Examples and Recipes (markdown)

---
 Examples-and-Recipes.md | 56 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/Examples-and-Recipes.md b/Examples-and-Recipes.md
index d60ba72..3169a20 100644
--- a/Examples-and-Recipes.md
+++ b/Examples-and-Recipes.md
@@ -10,6 +10,7 @@ This page contains examples and recipes contributed by community members. Feel f
 - [Working with the ISO week-based year](#iso_week)
 - [2Gs Birthday](#birthday2gs)
 - [Calculating Ordinal Dates](#year_day)
+- [Find all instances when a daylight savings shift is not 1 hour](#tz_search)
 
 ***
 
@@ -359,6 +360,61 @@ An [ordinal date](https://en.wikipedia.org/wiki/Ordinal_date) consists of a year
        assert(ymd == year_month_day{day_point{year/jan/0} + year_day});
     }
 
+<a name="tz_search"></a>
+### Find all instances when a daylight savings shift is not 1 hour
+(by [Howard Hinnant](https://github.com/HowardHinnant))
+
+Let's say you want to search the globe, and all time, for time zones when the daylight savings shift was not 1 hour.  Sound strange?  Maybe, but this code teaches you how to _efficiently_ iterate over **all** timezone transitions and inspect their characteristics.  So you can use this code for all kinds of searches over time zones.
+
+    #include "tz.h"
+    #include <iostream>
+
+    int
+    main()
+    {
+        using namespace date;
+        using namespace std::chrono_literals;
+        auto& db = get_tzdb();
+        for (auto const& z : db.zones)
+        {
+            auto begin = day_point{jan/1/year::min()} + 0s;
+            auto end   = day_point{jan/1/2035} + 0s;
+            do
+            {
+                auto info = z.get_info(begin, tz::utc);
+                if (info.save != 0h && info.save != 1h)
+                {
+                    std::cout << z.name() << " has an daylight savings offset of "
+                              << info.save.count() << "min from " << info.begin
+                              << " UTC to " << info.end << " UTC with the abbreviation "
+                              << info.abbrev << '\n';
+                }
+                begin = info.end;
+            } while (begin < end);
+        }
+    }
+
+You first get a reference to the tz database, then iterate over each zone in the database.  For each zone, set a range of time points to search over.  In this example I start searching as far back as possible, and search forward to the year 2035.
+
+Starting at the beginning of time, get an `Info` for that UTC `time_point`.  An `Info` looks like this:
+
+    struct Info
+    {
+        second_point         begin;
+        second_point         end;
+        std::chrono::seconds offset;
+        std::chrono::minutes save;
+        std::string          abbrev;
+    };
+
+Each time zone transition happens at `begin` (UTC).  The total offset from UTC for this timezone and period is `offset`.  This `offset` will be in effect until `end` (UTC).  The difference between this period's "normal" `offset`, and this `offset` is `save`.  And this period's timezone abbreviation is `abbrev`.
+
+For this example, we are looking for those periods when the `save` is neither 0 minutes, nor 60 minutes.  When we find one, just print it out.
+
+To increment the loop, set the local variable `begin` to `info.end`, and look up a new `Info`.
+
+It is really remarkably simple to search the globe and and all time for interesting chronological events related to timezone transitions.
+
 ***
 
 ![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/)._
\ No newline at end of file