Merge pull request #108 from bxparks/develop

merge 2.1.0 into master

Author: bxparks

.github/workflows/aunit_tests.yml

@@ -19,13 +19,13 @@ jobs:
         sudo apt update
         sudo apt install -y libcurl4-openssl-dev
         cd ..
-        git clone https://github.com/HowardHinnant/date
-        git clone https://github.com/bxparks/EpoxyDuino
-        git clone https://github.com/bxparks/AceRoutine
-        git clone https://github.com/bxparks/AUnit
-        git clone https://github.com/bxparks/AceCommon
-        git clone https://github.com/bxparks/AceWire
-        git clone https://github.com/bxparks/AceSorting
+        git clone --depth 1 https://github.com/HowardHinnant/date
+        git clone --depth 1 https://github.com/bxparks/EpoxyDuino
+        git clone --depth 1 https://github.com/bxparks/AceRoutine
+        git clone --depth 1 https://github.com/bxparks/AUnit
+        git clone --depth 1 https://github.com/bxparks/AceCommon
+        git clone --depth 1 https://github.com/bxparks/AceWire
+        git clone --depth 1 https://github.com/bxparks/AceSorting
 
     - name: Verify examples
       run: |

.github/workflows/validation.yml

@@ -26,15 +26,15 @@ jobs:
     - name: Checkout Additional Repos
       run: |
         cd ..
-        git clone https://github.com/bxparks/EpoxyDuino
-        git clone https://github.com/bxparks/AUnit
-        git clone https://github.com/bxparks/AceCommon
-        git clone https://github.com/bxparks/AceSorting
-        git clone https://github.com/bxparks/AceTimeTools
-        git clone https://github.com/bxparks/AceTimePython
-        git clone https://github.com/bxparks/AceTimeValidation
+        git clone --depth 1 https://github.com/bxparks/EpoxyDuino
+        git clone --depth 1 https://github.com/bxparks/AUnit
+        git clone --depth 1 https://github.com/bxparks/AceCommon
+        git clone --depth 1 https://github.com/bxparks/AceSorting
+        git clone --depth 1 https://github.com/bxparks/AceTimeTools
+        git clone --depth 1 https://github.com/bxparks/AceTimePython
+        git clone --depth 1 https://github.com/bxparks/AceTimeValidation
+        git clone --depth 1 https://github.com/HowardHinnant/date
         git clone https://github.com/eggert/tz
-        git clone https://github.com/HowardHinnant/date
 
     - name: Set up Python 3.7
       uses: actions/setup-python@v2

CHANGELOG.md

@@ -1,6 +1,52 @@
 # Changelog
 
 * Unreleased
+* 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:
+        * [Migrating to v2.1](MIGRATING.md#MigratingToVersion210)
+        * [ZonedExtra](USER_GUIDE.md#ZonedExtra) in the User Guide
+        * [Unified Links](USER_GUIDE.md#UnifiedLinks) in the User Guide
+    * **Potentially Breaking**: zonedb,zonedbx
+        * Rename `kPolicyXxx` to `kZonePolicyXxx` for consistency. These are
+          expected to be used only internally, so shouldn't cause external
+          breakage.
+    * **Breaking**: `TimeZone.h`
+        * Replace 3 separate extraction methods in `TimeZone` with a new
+          `ZonedExtra` class
+        * Removed: `TimeZone::getUtcOffset()`
+            * Replaced by: `ZonedExtra::timeOffset()`
+        * Removed: `TimeZone::getDeltaOffset()`
+            * Replaced by: `ZonedExtra::dstOffset()`
+        * Removed `TimeZone::getAbbrev()`
+            * Replaced by: `ZonedExtra::abbrev()`
+            * `ZonedExtra::abbrev()` returns pointer to a local string buffer
+              instead of a transient buffer deep inside `Transition` object.
+            * `TimeZone` becomes closer to being thread-safe
+    * **New Class**: `ZonedExtra.h`
+        * `ZonedExtra::forEpochSeconds(epochSeconds, tz)`
+            * Create instance from epochSeconds and time zone.
+        * `ZonedExtra::forLocalDateTime(ldt, tz)`
+            * Create instance from LocalDateTime and time zone.
+    * **Potentially Breaking**: Unified Links
+        * Links are now first-class citizens, exactly the same as Zones.
+        * Unify "fat links" and "symbolic links" into a single implementation.
+        * Remove "thin links" to simplify the code.
+        * `TimeZone` class simplified
+            * Removed `followLink` flag on various methods.
+            * Only 2 methods apply to Links: `isLink()` and
+              `printTargetNameTo()`.
+    * Simplify ZoneProcessors
+        * `ZoneProcessor.h`, `ExtendedZoneProcessor.h`, `BasicZoneProcessor.h`
+        * Remove: `getUtcOffset()`, `getDeltaOffset()`, `getAbbrev()`
+        * Replaced by: `findByLocalDateTime()`, `findByEpochSeconds()`
+        * These are internal helper methods not intended for public consumption.
+    * Unit tests
+        * Migrate most unit tests to use the smaller, testing zone databases at
+          `testing/tzonedb/` and `testing/tzonedbx/`.
+            * Reduces maintenance cost of various hand-crafted ZoneInfo and
+              ZonePolicy entries for unit tests.
+            * Can test against real timezones with predictable behavior.
 * 2.0.1 (2022-12-04, TZDB 2022g)
     * Prevent `ExtendedZoneProcssor::generateStartUntilTimes()` from
       dereferencing uninitialized memory if there are no matching transitions.
@@ -38,7 +84,7 @@
     * Extend `untilYear` of [zonedb](src/ace_time/zonedb) and
       [zonedbx](src/ace_time/zonedbx) databases to 10000
         * databases now valid over the years `[2000,10000)`
-        * `zonedbx` adds 75 additional Rules for `kPolicyMorocco` (e.g.
+        * `zonedbx` adds 75 additional Rules for `kZonePolicyMorocco` (e.g.
           zone "Africe/Casablanca") due to the precalculated DST shifts which
           are listed in the IANA TZ DB up to the year 2087.
         * `zonedb` remains unchanged

DEVELOPER.md

@@ -185,7 +185,7 @@ Arduino controllers:
 
 An entry in `zone_info.cpp` may refer to a zone policy defined in
 `zone_policies.h`. For example, the `kZoneAmerica_Los_Angeles` has a pointer
-to a `kPolicyUS` data structure which is defined in `zone_policies.h`.
+to a `kZonePolicyUS` data structure which is defined in `zone_policies.h`.
 
 Each policy entry starts with a comment secion that contains some metadata
 about the policy. For example:
@@ -304,16 +304,16 @@ The call stack of the first method looks like this:
 ```
 ZoneDateTime::forComponents()
   -> TimeZone::getOffsetDateTime(LocalDateTime&)
-    -> ExtendeZoneProcessor::getOffsetDateTime(LocalDateTime&)
+    -> ExtendeZoneProcessor::findByLocalDateTime(LocalDateTime&)
       -> TransitionStorage::findTransitionForDateTime(LocalDateTime&)
 ```
 
 The call stack of the second method looks like this:
 
 ```
 ZoneDateTime::forEpochSeconds(acetime_t)
-  -> TimeZone::getUtcOffset(acetime_t)
-    -> ExtendedZoneProcessor::getUtcOffset(acetime_t)
+  -> TimeZone::getOffsetDateTime(acetime_t)
+    -> ExtendedZoneProcessor::findByEpochSeconds(acetime_t)
       -> TransitionStorage::findTransitionForSeconds(acetime_t)
 ```
 
@@ -352,7 +352,7 @@ the prior year after the correct UTC offset is calculated, so we need to pick up
 Transitions in the prior year. Similarly, a local date time of Dec 31 could land
 in the following year after correcting for UTC offset.
 
-A `MatchingEra` is a wrapper around a `ZoneEra`, with its startDateTimea and
+A `MatchingEra` is a wrapper around a `ZoneEra`, with its startDateTime and
 untilDateTime truncated to be within the 14-month interval of interest.
 
 <a name="Step2CreateTransitions"></a>

MIGRATING.md

@@ -2,6 +2,9 @@
 
 ## Table of Contents
 
+* [Migrating to v2.1.0](#MigratingToVersion210)
+    * [Unified Links](#UnifiedLinks)
+    * [ZonedExtra](#ZonedExtra)
 * [Migrating to v2.0.0](#MigratingToVersion200)
     * [High Level](#HighLevel200)
     * [Details](#Details200)
@@ -15,6 +18,89 @@
     * [Migrating the DS3231Clock](#MigratingTheDS3231Clock)
     * [Migrating to LinkManagers](#MigratingToLinkManagers)
 
+<a name="MigratingToVersion210"></a>
+## Migrating to v2.1
+
+<a name="UnifiedLinks"></a>
+### Unified Links
+
+Over the years, I implemented 4 different versions of the Link entries:
+
+* Ghost Links (`< v1.5`)
+* Fat Links (`>= v1.5`)
+* Thin Links (`>= v1.6`)
+* Symbolic Links (`>= v1.11`)
+
+I had mistakenly assumed that TZDB Link entries were somehow less important
+than the Zone entries. Often Link entries were old spellings of
+zones which were replaced by new zone names (e.g. "Asia/Calcutta" replaced by
+"Asia/Kolkata"), or zones using an older naming convention pre-1993 (e.g.
+"UTC" replaced by "Etc/UTC").
+
+The code in AceTime reflected my assumption of the second-class status of Link
+entries. Recently however the IANA TZDB project has aggressively merged
+unrelated Zones (in different countries) into a single zone if they all happen
+to have the same DST transition rules since 1970. The duplicate zones become
+Link entries to the "canonical" zone (e.g. "Arctic/Longyearbyen",
+"Europe/Copenhagen", "Europe/Oslo", "Europe/Stockholm", "Atlantic/Jan_Mayen" are
+all links to "Europe/Berlin").
+
+It is now more clear the Link entries should be considered first-class entries,
+just like Zone entries. The v2.1 release implements this change in semantics.
+All previous implementations of Links are now merged into a single
+implementation which treats Links equal to Zones, and all the usual operations
+on Zones are also valid on Links.
+
+1) The "Thin Link" feature has been removed, along with the Link Manager
+   classes. The code was too complex, and did not provide enough value.
+    * `LinkManager`
+    * `BasicLinkManager`
+    * `ExtendedLinkManager`.
+2) The `followLink` parameter on various `TimeZone` and `ZoneProcessor` methods
+   has been removed.
+3) The `zonedb` and `zonedbx` databases no longer contain the link registries:
+    * `basic::kLinkRegistry`
+    * `extended::kLinkRegistry`
+4) The `kZoneRegistry` is still generated for historical reasons.
+    * This registry contains the minimum complete dataset of the IANA timezones.
+    * Most applications should use `kZoneAndLinkRegistry` which contains the
+      Link entries.
+
+Most application code are expected to treat Links and Zones equally. There are
+only 2 methods which apply only to Link time zones:
+
+* `TimeZone::isLink()`
+    * Returns true if the current time zone is a Link.
+* `TimeZone::printTargetZoneNameTo()`
+    * Prints the name of the target Zone if the current zone is a link.
+    * It prints nothing is `isLink()` is false.
+
+<a name="ZonedExtra"></a>
+### ZonedExtra
+
+The `ZonedExtra` class was created to replace 3 ad-hoc query methods on the
+`TimeZone` object:
+
+* Removed: `TimeZone::getUtcOffset()`
+* Removed: `TimeZone::getDeltaOffset()`
+* Removed: `TimeZone::getAbbrev()`
+
+Once the `ZonedExtra` object has been objected for a particular point in time,
+the following methods on `ZonedExtra` are the replacements for the above:
+
+* `ZonedExtra::timeOffset()`
+* `ZonedExtra::dstOffset()`
+* `ZonedExtra::abbrev()`
+
+The `ZonedExtra` object will normally be created through 2 factory methods:
+
+* `ZonedExtra::forEpochSeconds(epochSeconds, tz)`
+* `ZonedExtra::forLocalDateTime(ldt, tz)`
+
+The `ZonedExtra` object provides access to other meta-information about the time
+zone at that particular time. See the [ZonedExtra](USER_GUIDE.md#ZonedExtra)
+section in the `USER_GUIDE.md` for more detailed information about this class.
+
 <a name="MigratingToVersion200"></a>
 ## Migrating to v2.0
 

README.md

@@ -52,15 +52,14 @@ This library can be an alternative to the Arduino Time
 (https://github.com/PaulStoffregen/Time) and Arduino Timezone
 (https://github.com/JChristensen/Timezone) libraries.
 
-**Breaking Changes in v2.0**: 1) The default AceTime epoch is shifted forward
-from 2000-01-01 (v1) to 2050-01-01 (v2). This extends the validity of most
-timezone related functions from `[2000,2050)` to `[2000,2100)`. 2) The epoch
-year is now an adjustable parameter using the `Epoch::currentEpochYear(year)`
-function. 3) The zoneinfo databases (`zonedb` and `zonedbx`) are now valid from
-`[2000, 10000)`, independent of the current epoch year. See the [Migrating to
-v2.0.0](MIGRATING.md#MigratingToVersion200) section for more details.
+**Breaking Changes in v2.1**: Links are now first-class citizens compared to
+Zones and should be treated exactly the same. Fat link and symbolic link
+implementations have been unified. The `kZoneRegistry` and
+`kZoneAndLinkRegistry` are identical. Only 2 methods are special to Link time
+zones: `TimeZone::isLink()` and `TimeZone::printTargetNameTo()`. See [Migrating
+to v2.1.0](MIGRATING.md#MigratingToVersion210) section for more details.
 
-**Version**: 2.0.1 (2022-12-04, TZDB version 2022g)
+**Version**: 2.1.0 (2023-01-29, TZDB version 2022g)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -274,8 +273,9 @@ void setup() {
   Serial.println();
 
   // Print the current time zone abbreviation, e.g. "PST" or "PDT"
+  ZonedExtra ze = losAngelesTz.getZonedExtra(epochSeconds);
   Serial.print(F("Abbreviation: "));
-  Serial.print(losAngelesTz.getAbbrev(epochSeconds));
+  SERIAL_PORT_MONITOR.print(ze.abbrev());
   Serial.println();
 
   // Create from epoch seconds. London is still on standard time.
@@ -293,8 +293,9 @@ void setup() {
   Serial.println();
 
   // Print the current time zone abbreviation, e.g. "GMT" or "BST"
+  ze = londonTz.getZonedExtra(epochSeconds);
   Serial.print(F("Abbreviation: "));
-  Serial.print(londonTz.getAbbrev(epochSeconds));
+  SERIAL_PORT_MONITOR.print(ze.abbrev());
   Serial.println();
 
   Serial.println(F("=== Compare ZonedDateTime"));
@@ -1129,9 +1130,8 @@ and
 [ExtendedHinnantDateTest](https://github.com/bxparks/AceTimeValidation/tree/master/ExtendedHinnantDateTest)
 validation tests which compare the AceTime algorithms to the Hinnant Date
 algorithms. For all times zones between the years 2000 until 2100, the AceTime
-UTC offsets (`TimeZone::getUtcOffset()`), timezone abbreviations
-(`TimeZone::getAbbrev()`), and epochSecond conversion to date components
-(`ZonedDateTime::fromEpochSeconds()`) match the results from the Hinnant Date
+date-time components (`ZonedDateTime`) and abbreviations (`ZonedExtra`)
+calculated from the given epochSeconds match the results from the Hinnant Date
 libraries.
 
 <a name="Cctz"></a>