Merge pull request #98 from bxparks/develop

merge 1.11.4 into master

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
 * Unreleased
+* 1.11.4 (2022-08-13, TZDB 2022b)
+    * Add `ace_time::daysUntil(localDate, month, day)` utility function that
+      returns the number of days until the next (month, day) date. Useful for
+      calculating the number of days until the next Christmas for example.
+    * Upgrade to TZDB 2022b.
+        * https://mm.icann.org/pipermail/tz-announce/2022-August/000071.html
+            * Chile's DST is delayed by a week in September 2022.
+            * Iran no longer observes DST after 2022.
+            * Rename Europe/Kiev to Europe/Kyiv.
+            * Finish moving duplicate-since-1970 zones to 'backzone'.
+        * zonedb
+            * Number of zones decreases from 258 to 237.
+            * Number of links increases from 193 to 215.
+        * zonedbx
+            * Number of zones decreases from 377 to 356.
+            * Number of links increases from 217 to 239.
 * 1.11.3 (2022-03-20, TZDB 2022a)
     * Update to TZDB 2022a.
         * https://mm.icann.org/pipermail/tz-announce/2022-March.txt

README.md

@@ -53,7 +53,7 @@ This library can be an alternative to the Arduino Time
 (https://github.com/PaulStoffregen/Time) and Arduino Timezone
 (https://github.com/JChristensen/Timezone) libraries.
 
-**Version**: 1.11.3 (2022-03-20, TZDB version 2022a)
+**Version**: 1.11.4 (2022-08-13, TZDB version 2022b)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 

USER_GUIDE.md

@@ -4,7 +4,7 @@ The primary purpose of AceTime classes is to convert between an integer
 representing the number of seconds since the AceTime Epoch (2000-01-01T00:00:00
 UTC) and the equivalent human-readable components in different timezones.
 
-**Version**: 1.11.3 (2021-03.20, TZDB 2022a)
+**Version**: 1.11.4 (2022-08-13, TZDB 2022b)
 
 **Related Documents**:
 
@@ -1869,6 +1869,11 @@ epochSeconds which can correspond to the given LocalDateTime. The `fold`
 parameter is an *input* parameter to the `forComponents()` in both cases.
 The impact of the `fold` parameter is as follows:
 
+**Normal**: Not a gap or overlap. The `forComponents()` method ignores the
+`fold` parameter if there is no ambiguity about the local date-time components.
+The returned `ZonedDateTime` object will contain a `fold()` value that preserves
+the input `fold` parameter.
+
 **Overlap**: If `ZonedDateTime::forComponents()` is called with during an
 overlap of `LocalDateTime` (e.g. 2:30am during a fall back from 2am to 3am), the
 factory method uses the user-provided `fold` parameter to select the following:
@@ -1896,20 +1901,26 @@ the following, and perhaps counter-intuitive, manner:
     * Which becomes normalized to the *later* ZonedDateTime which has the
       *later* UTC offset.
     * So 02:30 is interpreted as 02:30-08:00, which is normalized to
-      03:30-07:00, and the `fold` after normalization is set to 0.
+      03:30-07:00, and the `fold` after normalization is set to 1 to indicate
+      that the later transition was selected.
 * `fold==1`
     * Selects the *later* Transition element, extended backward to apply to the
       given LocalDateTime,
     * Which maps to the *earlier* UTC/epochSeconds,
     * Which becomes normalized to the *earlier* ZonedDateTime which has the
       *earlier* UTC offset.
     * So 02:30 is interpreted as 02:30-07:00, which is normalized to
-      01:30-08:00, and the `fold` after normalization is set to 0.
+      01:30-08:00, and the `fold` after normalization is set to 0 to indicate
+      that the earlier transition was selected.
 
 The time shift during a gap seems to be the *opposite* of the shift during an
 overlap, but internally this is self-consistent. Just as importantly, this
 follows the same logic as PEP 495.
 
+Note that the `fold` parameter flips its value (from 0 to 1, or vise versea) if
+`forComponents()` is called in the gap. Currently, this is the only publicly
+exposed mechanism for detecting that a given date-time is in the gap.
+
 <a name="SemanticChangesWithFold"></a>
 #### Semantic Changes with Fold
 
@@ -1945,8 +1956,8 @@ A more subtle, but important semantic change, is that the `fold` parameter
 preserves information during gaps and overlaps. This means that we can do
 round-trip conversions of `ZonedDateTime` properly. We can start with
 epochSeconds, convert to components, then back to epochSeconds, and get back the
-same epochSeconds. With the `fold` parameter, this round-trip was not guaranteed
-during an overlap.
+same epochSeconds. Without the `fold` parameter, this round-trip was not
+guaranteed during an overlap.
 
 <a name="ResourceConsumptionWithFold"></a>
 #### Resource Consumption with Fold
@@ -2046,8 +2057,8 @@ in the `transformer.py` script and summarized in
 * the UNTIL time suffix can only be 'w' (not 's' or 'u')
 * there can be only one DST transition in a single month
 
-As of version v1.11.3 (with TZDB 2022a), this database contains 258 Zone entries
-and 193 Link entries, supported from the year 2000 to 2049 (inclusive).
+As of version v1.11.4 (with TZDB 2022b), this database contains 237 Zone entries
+and 215 Link entries, supported from the year 2000 to 2049 (inclusive).
 
 <a name="ExtendedZonedbx"></a>
 #### Extended zonedbx
@@ -2063,8 +2074,8 @@ are:
 * the AT and UNTIL fields are multiples of 1-minute
 * the LETTER field can be arbitrary strings
 
-As of version v1.11.3 (with TZDB 2022a), this database contains all 377 Zone
-entries and 217 Link entries, supported from the year 2000 to 2049 (inclusive).
+As of version v1.11.4 (with TZDB 2022b), this database contains all 356 Zone
+entries and 239 Link entries, supported from the year 2000 to 2049 (inclusive).
 
 <a name="TzDatabaseVersion"></a>
 #### TZ Database Version

docs/doxygen.cfg

@@ -38,7 +38,7 @@ PROJECT_NAME           = "AceTime"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.11.3
+PROJECT_NUMBER         = 1.11.4
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

docs/html/AceTime_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceTime
-   &#160;<span id="projectnumber">1.11.3</span>
+   &#160;<span id="projectnumber">1.11.4</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database.</div>
   </td>
@@ -124,12 +124,13 @@
 <div class="line"><a name="l00062"></a><span class="lineno">   62</span>&#160;<span class="preprocessor">#include &quot;<a class="code" href="zoned__date__time__mutation_8h.html">ace_time/zoned_date_time_mutation.h</a>&quot;</span></div>
 <div class="line"><a name="l00063"></a><span class="lineno">   63</span>&#160;<span class="preprocessor">#include &quot;ace_time/TimePeriod.h&quot;</span></div>
 <div class="line"><a name="l00064"></a><span class="lineno">   64</span>&#160;<span class="preprocessor">#include &quot;<a class="code" href="time__period__mutation_8h.html">ace_time/time_period_mutation.h</a>&quot;</span></div>
-<div class="line"><a name="l00065"></a><span class="lineno">   65</span>&#160; </div>
-<div class="line"><a name="l00066"></a><span class="lineno">   66</span>&#160;<span class="comment">// Version format: xxyyzz == &quot;xx.yy.zz&quot;</span></div>
-<div class="line"><a name="l00067"></a><span class="lineno">   67</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION 11103</span></div>
-<div class="line"><a name="l00068"></a><span class="lineno">   68</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION_STRING &quot;1.11.3&quot;</span></div>
-<div class="line"><a name="l00069"></a><span class="lineno">   69</span>&#160; </div>
-<div class="line"><a name="l00070"></a><span class="lineno">   70</span>&#160;<span class="preprocessor">#endif</span></div>
+<div class="line"><a name="l00065"></a><span class="lineno">   65</span>&#160;<span class="preprocessor">#include &quot;ace_time/ace_time_utils.h&quot;</span></div>
+<div class="line"><a name="l00066"></a><span class="lineno">   66</span>&#160; </div>
+<div class="line"><a name="l00067"></a><span class="lineno">   67</span>&#160;<span class="comment">// Version format: xxyyzz == &quot;xx.yy.zz&quot;</span></div>
+<div class="line"><a name="l00068"></a><span class="lineno">   68</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION 11104</span></div>
+<div class="line"><a name="l00069"></a><span class="lineno">   69</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION_STRING &quot;1.11.4&quot;</span></div>
+<div class="line"><a name="l00070"></a><span class="lineno">   70</span>&#160; </div>
+<div class="line"><a name="l00071"></a><span class="lineno">   71</span>&#160;<span class="preprocessor">#endif</span></div>
 </div><!-- fragment --></div><!-- contents -->
 <div class="ttc" id="atime__period__mutation_8h_html"><div class="ttname"><a href="time__period__mutation_8h.html">time_period_mutation.h</a></div></div>
 <div class="ttc" id="azoned__date__time__mutation_8h_html"><div class="ttname"><a href="zoned__date__time__mutation_8h.html">zoned_date_time_mutation.h</a></div></div>

docs/html/BasicBrokers_8cpp_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceTime
-   &#160;<span id="projectnumber">1.11.3</span>
+   &#160;<span id="projectnumber">1.11.4</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database.</div>
   </td>

docs/html/BasicBrokers_8h.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceTime
-   &#160;<span id="projectnumber">1.11.3</span>
+   &#160;<span id="projectnumber">1.11.4</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database.</div>
   </td>

docs/html/BasicBrokers_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceTime
-   &#160;<span id="projectnumber">1.11.3</span>
+   &#160;<span id="projectnumber">1.11.4</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database.</div>
   </td>

docs/html/BasicZoneProcessor_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceTime
-   &#160;<span id="projectnumber">1.11.3</span>
+   &#160;<span id="projectnumber">1.11.4</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database.</div>
   </td>

docs/html/BasicZone_8cpp_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceTime
-   &#160;<span id="projectnumber">1.11.3</span>
+   &#160;<span id="projectnumber">1.11.4</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database.</div>
   </td>