Merge pull request #110 from bxparks/develop

merge 2.2.0 into master

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,67 @@
 # Changelog
 
 * Unreleased
+* 2.2.0 (2023-03-24, TZDB version 2023b)
+    * Upgrade TZDB from 2022g to 2023b
+        * 2023a skipped because it came out only a day earlier.
+        * 2023a: https://mm.icann.org/pipermail/tz-announce/2023-March/000077.html
+            * Egypt now uses DST again, from April through October.
+            * This year Morocco springs forward April 23, not April 30.
+            * Palestine delays the start of DST this year.
+            * Much of Greenland still uses DST from 2024 on.
+            * America/Yellowknife now links to America/Edmonton.
+            * tzselect can now use current time to help infer timezone.
+            * The code now defaults to C99 or later.
+            * Fix use of C23 attributes.
+        * 2023b: https://mm.icann.org/pipermail/tz-announce/2023-March/000078.html
+            * Lebanon delays the start of DST this year.
+    * **Bug Fix**
+        * Change arguments for `TimeZone::forMinutes()` from `uint8_t` to
+          `uint16_t`.
+    * **Breaking Change**
+        * Make `TimeZone` effectively immutable, by removing `setStdOffset()`
+          and `setDstOffset()` methods.
+        * Client applications should create a new `TimeZone` object using
+          `TimeZone::forTimeOffset(std, dst)` and overwrite the old one.
+        * See [Migrating to v2.2](MIGRATING.md#MigratingToVersion220).
+    * Add support for Seeed Studio XIAO M0 (SAMD21).
+        * Required updating `zoneino/compat.h` to clobber the broken definition
+          of `FPSTR()` in Seeeduino 1.8.3.
+    * Simplify the handling of `Rule.LETTER`.
+        * Encode all letters as an index into `ZoneContext.letters` array, not
+          just `LETTER` which are only a single character.
+        * On 8-bit AVR:
+            * Increases `BasicZoneProcessor` by ~200 bytes when 1-2 zones are
+              used. But flash remains the same when the full TZ database is
+              used.
+            * No change to `ExtendedZoneProcessor` for 1-2 zones. But decreases
+              flash usage by ~300 bytes when the full TZ database is used.
+        * The small increase in flash is worth it because this greatly
+          simplifies the complicated code surrounding LETTER that was difficult
+          to understand and maintain.
+    * Unify Basic and Extended zoneinfo encoding.
+        * Change encoding of `basic::ZoneRule.deltaCode`,
+          `basic::ZoneEra.deltaCode`, and `basic::ZoneEra.offsetCode` to be
+          identical their counterparts in `extended::ZoneXxx`.
+        * Merge `BasicBrokers.h` and `ExtendedBrokers.h` into just `Brokers.h`.
+    * Restructure zonedb directories
+        * Lift `ace_time/internal/testing/tzonedb[x]` database files 
+          to `ace_time/tzonedb[x]`.
+        * Lift `ace_time/zonedb[x]` database files to `ace_time/zonedb[x]`.
+        * These changes are transparent to client apps because the C++
+          namespaces of these files are unchanged.
+        * Lift `ace_time/internal/Zone*.h` files into new `src/zoneinfo/`
+          directory. These are the classes that describe the `*zonedb*`
+          databases.
+    * Add `ZonedDateTime::offsetDateTime()`
+        * Returns the underlying `OffsetDateTime` inside the `ZonedDateTime`.
+        * Analogous to `ZonedDateTime::localDateTime()`.
+    * Always generate anchor rules in zonedb.
+        * Allows `ExtendedZoneProcessor` to work over all years `[0,10000)`
+          even with truncated zonedb (e.g. `[2000,2100)`).
+        * Accuracy is guaranteed only for the requested interval (e.g.
+          `[2000,2100)`.
+        * But the code won't crash outside of that interval.
 * 2.1.1 (2023-02-02, TZDB version 2022g)
     * `ZonedExtra`
         * Add `ZonedExtra::forComponents()` factory method, for consistency with

DEVELOPER.md

@@ -94,8 +94,8 @@ ace_time::hw    |     ace_time::basic
 As explained in the README.md, the AceTime library comes with 2 versions of the
 [TZ Data](https://www.iana.org/time-zones):
 
-* `src/ace_time/zonedb/*`: files used by the `BasicZoneProcessor` class
-* `src/ace_time/zonedbx/*`: files used by the `ExtendedZoneProcessor` class
+* `src/zonedb/*`: files used by the `BasicZoneProcessor` class
+* `src/zonedbx/*`: files used by the `ExtendedZoneProcessor` class
 
 There are 2 main files in these directories:
 
@@ -239,11 +239,11 @@ STDOFF (1-min resolution)
                        ---------------> | minute  | code     |
                                         | (4-bits)| (4-bits) |
                                         +--------------------+
-                                                      ^
-RULES (numeric, 15-min resolution)                   /
--> rules_delta_seconds                              /
-    -> rules_delta_code -- (basic) ----------------/
-                        -- (extended) + 4 ---------
+                                                    ^
+RULES (numeric, 15-min resolution)                 /
+-> era_delta_seconds                              /
+  -> era_delta_minutes                           /
+    -> era_delta_code + 4------------------------
 
 
 UNTIL (1-min resolution)
@@ -280,9 +280,10 @@ AT (1-min resolution)
                                         +--------------------+
 
 SAVE (15-min resolution)
--> delta_seconds                        +--------------------+
-    -> delta_code -- (basic) ---------> |     deltaCode      |
-                  -- (extended) + 4 --> |     (8 bits)       |
+-> delta_seconds
+  -> delta_minutes                      +--------------------+
+    -> delta_code + 4 ----------------> |     deltaCode      |
+                                        |     (8 bits)       |
                                         +--------------------+
 ```
 
@@ -601,14 +602,9 @@ available.
     * `$ make validations`
     * `$ make runvalidations`
 * Update the various zoneinfo files for AceTime:
-    * `zonedb`
-        * `$ cd AceTime/src/ace_time/zonedb`
-        * Update the `TZ_VERSION` variable in `Makefile`.
-        * `$ make`
-    * `zonedbx`
-        * `$ cd AceTime/src/ace_time/zonedbx`
-        * Update the `TZ_VERSION` variable in `Makefile`.
-        * `$ make`
+    * `$ cd AceTime/src`
+    * Update the `TZ_VERSION` variable in `Makefile`.
+    * `$ make`
 * Update CHANGELOGs
     * AceTime/CHANGELOG.md
     * AceTimePython/CHANGELOG.md

MIGRATING.md

@@ -2,6 +2,7 @@
 
 ## Table of Contents
 
+* [Migrating to v2.2.0](#MigratingToVersion220)
 * [Migrating to v2.1.0](#MigratingToVersion210)
     * [Unified Links](#UnifiedLinks)
     * [ZonedExtra](#ZonedExtra)
@@ -18,6 +19,46 @@
     * [Migrating the DS3231Clock](#MigratingTheDS3231Clock)
     * [Migrating to LinkManagers](#MigratingToLinkManagers)
 
+<a name="MigratingToVersion220"></a>
+## Migrating to v2.2
+
+### Immutable TimeZone class
+
+Previously, the `TimeZone` class was semantically immutable when using the
+IANA timezones through the `BasicZoneProcessor` or `ExtendedZoneProcessor`.
+There was one exception: When the `TimeZone` represented a fixed UTC offset
+(e.g. type of `TimeZone::kTypeManual`), the `TimeZone` allowed the STD offset
+and DST offset to be modified in-place.
+
+This was a mistake, because the `TimeZone` object was meant to be copied by
+value, and allowing it to be mutable meant that 2 different `ZonedDateTime`
+objects could intend to hold the same `TimeZone` object, but modifying one
+instance would not update the other instance.
+
+In v2.2, the `TimeZone` class becomes immutable, and the following methods are
+removed:
+
+```C++
+class TimeZone {
+  public:
+    void setStdOffset(TimeZone offset);
+    void setDstOffset(TimeZone offset);
+};
+```
+
+To modify a `TimeZone`, create a new instance, then call
+`ZonedDateTime::convertToTimeZone(const TimeZone& tz)` instead. For example, to
+change to Daylight Saving Time for Pacific time:
+
+```C++
+TimeZone tz = TimeZone::forHours(-8, 0); // PST time
+ZonedDateTime zdt = ZonedDateTime::forComponents(...);
+
+TimeZone newTz = TimeZone::forTimeOffset(
+  tz.getStdOffset(), TimeOffset::forHours(1));
+ZonedDateTime newDt = zdt.convertToTimeZone(newTz);
+```
+
 <a name="MigratingToVersion210"></a>
 ## Migrating to v2.1