Merge pull request #109 from bxparks/develop

merge 2.1.1 into master

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
 
 * Unreleased
+* 2.1.1 (2023-02-02, TZDB version 2022g)
+    * `ZonedExtra`
+        * Add `ZonedExtra::forComponents()` factory method, for consistency with
+          `ZonedDateTime` class.
+    * `examples/AutoBenchmark`
+        * Add `ZonedExtra` benchmarks.
+    * `README.md`
+        * Update `AceTimeValidation` validation years to `[2000,2100)`.
+        * Update memory and cpu benchmarks.
 * 2.1.0 (2023-01-29, TZDB version 2022g)
     * There are a handful API breaking changes in this release in the pursuit of
       simpler and cleaner code. See the following for more info:

README.md

@@ -18,7 +18,7 @@ valid from the years `[2000,10000)`. By adjusting the `currentEpochYear()`, the
 library will work across any 100 year interval across the 8000 year range of the
 TZ database.
 
-**Version**: 2.1.0 (2023-01-29, TZDB 2022g)
+**Version**: 2.1.1 (2023-02-02, TZDB 2022g)
 
 **Related Documents**:
 
@@ -1519,6 +1519,10 @@ class ZonedExtra {
     static const uint8_t kTypeOverlap = 3;
 
     static ZonedExtra forError();
+    static ZonedExtra forComponents(
+        int16_t year, uint8_t month, uint8_t day,
+        uint8_t hour, uint8_t minute, uint8_t second,
+        const TimeZone& tz, uint8_t fold = 0);
     static ZonedExtra forEpochSeconds(
         acetime_t epochSeconds, const TimeZone& tz);
     static ZonedExtra forLocalDateTime(
@@ -1533,13 +1537,17 @@ class ZonedExtra {
         int16_t reqDstOffsetMinutes,
         const char* abbrev);
 
-    bool isError() const {
-    uint8_t type() const { return mType; }
+    bool isError() const;
+    uint8_t type() const;
 
+    TimeOffset timeOffset() const; // stdOffset + dstOffset
     TimeOffset stdOffset() const;
     TimeOffset dstOffset() const;
+
+    TimeOffset reqTimeOffset() const; // reqStdOffst + reqDstOffset
     TimeOffset reqStdOffset() const;
     TimeOffset reqDstOffset() const;
+
     const char* abbrev() const;
 };
 
@@ -1550,7 +1558,9 @@ The `ZonedExtra` instance is usually created through the 2 static factory
 methods on the `ZonedExtra` class:
 
 * `ZonedExtra::forEpochSeconds(epochSeconds, tz)`
-* `ZonedExtra::forLocalDateTime(ldt, tz)`
+* `ZonedExtra::forComponents(int16_t year, uint8_t month, uint8_t day,
+   uint8_t hour, uint8_t minute, uint8_t second, const TimeZone& tz,
+   uint8_t fold = 0)`
 
 Often the `ZonedDateTime` will be created first from the epochSeconds, then the
 `ZonedExtra` will be created to access additional information about the time zone at that particular epochSeconds (e.g. abbreviation):
@@ -1578,8 +1588,9 @@ The `ZonedExtra::dstOffset()` is the DST offset that pertains to the given
 time instant. For example, for `America/Los_Angeles` this will return `01:00`
 during summer DST, and `00:00` during normal times.
 
-Note that the total UTC offset corresponding to `ZonedDateTime::timeOffset()` is
-equal to `stdOffset() + dstOffset()`.
+The `ZonedExtra::timeOffset()` is a convenience method that returns the sum of
+`stdOffset() + dstOffset()`. This value is identical to the total UTC offset
+returned by `ZonedDateTime::timeOffset()`.
 
 The `ZonedExtra::abbrev()` is the short abbreviation that is in effect at the
 given time instant. For example, for `America/Los_Angeles`, this returns "PST"
@@ -1589,8 +1600,8 @@ the life of the `ZonedExtra` object.
 
 The `ZonedExtra::reqStdOffset()` and `ZonedExtra::reqDstOffset()` are relevant
 and different from the corresponding `stdOffset()` and `dstOffset()` only if the
-`type()` is `kTypeGap`. This occurs only if the `getZonedExtra(LocalDateTime&)`
-overloaded version is used. Following the algorithm described in [Python PEP
+`type()` is `kTypeGap`. This occurs only if the `ZonedExtra::forComponents()`
+factory method is used. Following the algorithm described in [Python PEP
 495](https://www.python.org/dev/peps/pep-0495/), the provided localDateTime is
 imaginary during a gap so must be mapped to a real local time using the
 `LocalDateTime::fold` parameter. When `fold=0`, the transition line before the
@@ -1788,8 +1799,8 @@ zone name:
 ```C++
 ExtendedZoneProcessorCache<CACHE_SIZE> zoneProcessorCache;
 ExtendedZoneManager zoneManager(
-    zonedbx::kZoneRegistrySize,
-    zonedbx::kZoneRegistry,
+    zonedbx::kZoneAndLinkRegistrySize,
+    zonedbx::kZoneAndLinkRegistry,
     zoneProcessorCache);
 
 void someFunction() {
@@ -1807,8 +1818,8 @@ could be done more efficiently using the `createForZoneInfo()` like this:
 ```C++
 ExtendedZoneProcessorCache<CACHE_SIZE> zoneProcessorCache;
 ExtendedZoneManager zoneManager(
-    zonedbx::kZoneRegistrySize,
-    zonedbx::kZoneRegistry,
+    zonedbx::kZoneAndLinkRegistrySize,
+    zonedbx::kZoneAndLinkRegistry,
     zoneProcessorCache);
 
 void someFunction() {
@@ -1844,8 +1855,8 @@ corresponding to the given `zoneId`:
 ```C++
 ExtendedZoneProcessorCache<CACHE_SIZE> zoneProcessorCache;
 ExtendedZoneManager zoneManager(
-    zonedbx::kZoneRegistrySize,
-    zonedbx::kZoneRegistry,
+    zonedbx::kZoneAndLinkRegistrySize,
+    zonedbx::kZoneAndLinkRegistry,
     zoneProcessorCache);
 
 void someFunction() {
@@ -2207,8 +2218,8 @@ Here are some examples taken from
 ```C++
 ExtendedZoneProcessorCache<1> zoneProcessorCache;
 ExtendedZoneManager extendedZoneManager(
-    zonedbx::kZoneRegistrySize,
-    zonedbx::kZoneRegistry,
+    zonedbx::kZoneAndLinkRegistrySize,
+    zonedbx::kZoneAndLinkRegistry,
     zoneProcessorCache);
 TimeZone tz = extendedZoneManager.createForZoneInfo(
     &zonedbx::kZoneAmerica_Los_Angeles);
@@ -2517,9 +2528,12 @@ canonical entry (e.g. `US/Pacific` which points to `America/Los_Angeles`).
 Prior to v2.1, AceTime treated Links slightly differently than Zones, providing
 4 different implementations over several version. After v2.1, Links are
 considered to be identical to Zones, because the TZDB considers both of them to
-be first-class citizens. Following this merger, the `kZoneAndLinkRegistry` has
-been merged into the `kZoneRegistry` and the 2 registries are identical.
+be first-class citizens. For most 32-bit processors with enough flash memory,
+the `kZoneAndLinkRegistry` should be used. The `kZoneRegistry` containing
+only the Zone entries is maintained mostly for backwards compatibility and
+testing purposes.
 
+Most methods on the `TimeZone` class apply to both Zone and Link time zones.
 There are 2 methods on the `TimeZone` class which apply only to Links:
 
 ```C++
@@ -2546,10 +2560,10 @@ the time zone `US/Pacific` (which is a Link to `America/Los_Angeles`):
 #### Custom Zone Registry
 
 On small microcontrollers, the default zone registries (`kZoneRegistry` and
-`kZoneAndLinkRegistry`, which are now identical) may be too large. The
-`ZoneManager` can be configured with a custom zone registry. It needs to be
-given an array of `ZoneInfo` pointers when constructed. For example, here is a
-`BasicZoneManager` with only 4 zones from the `zonedb::` data set:
+`kZoneAndLinkRegistry`) may be too large. The `ZoneManager` can be configured
+with a custom zone registry. It needs to be given an array of `ZoneInfo`
+pointers when constructed. For example, here is a `BasicZoneManager` with only 4
+zones from the `zonedb::` data set:
 
 ```C++
 #include <AceTime.h>

USER_GUIDE.md

@@ -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         = 2.1.0
+PROJECT_NUMBER         = 2.1.1
 
 # 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/doxygen.cfg

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceTime
-   &#160;<span id="projectnumber">2.1.0</span>
+   &#160;<span id="projectnumber">2.1.1</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database.</div>
   </td>
@@ -128,8 +128,8 @@
 <div class="line"><a name="l00066"></a><span class="lineno">   66</span>&#160;<span class="preprocessor">#include &quot;ace_time/ace_time_utils.h&quot;</span></div>
 <div class="line"><a name="l00067"></a><span class="lineno">   67</span>&#160; </div>
 <div class="line"><a name="l00068"></a><span class="lineno">   68</span>&#160;<span class="comment">// Version format: xxyyzz == &quot;xx.yy.zz&quot;</span></div>
-<div class="line"><a name="l00069"></a><span class="lineno">   69</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION 20100</span></div>
-<div class="line"><a name="l00070"></a><span class="lineno">   70</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION_STRING &quot;2.1.0&quot;</span></div>
+<div class="line"><a name="l00069"></a><span class="lineno">   69</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION 20101</span></div>
+<div class="line"><a name="l00070"></a><span class="lineno">   70</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION_STRING &quot;2.1.1&quot;</span></div>
 <div class="line"><a name="l00071"></a><span class="lineno">   71</span>&#160; </div>
 <div class="line"><a name="l00072"></a><span class="lineno">   72</span>&#160;<span class="preprocessor">#endif</span></div>
 <div class="ttc" id="acommon_2common_8h_html"><div class="ttname"><a href="common_2common_8h.html">common.h</a></div><div class="ttdoc">Identifiers used by implementation code which need to be publically exported.</div></div>

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">2.1.0</span>
+   &#160;<span id="projectnumber">2.1.1</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database.</div>
   </td>

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">2.1.0</span>
+   &#160;<span id="projectnumber">2.1.1</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">2.1.0</span>
+   &#160;<span id="projectnumber">2.1.1</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">2.1.0</span>
+   &#160;<span id="projectnumber">2.1.1</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">2.1.0</span>
+   &#160;<span id="projectnumber">2.1.1</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database.</div>
   </td>