Merge pull request #65 from bxparks/develop

merge v1.7.2 into master

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
 * Unreleased
+* 1.7.2 (2021-06-02)
+    * **Bug Fix**: Add `ZonedDateTime::normalize()`, which must be called by
+      the client code after calling a `ZonedDateTime` mutation function.
+        * See [ZonedDateTime Normalization](docs/date_time_timezone.md#ZonedDateTimeNormalization).
+        * Increases flash usage by 222 bytes by making this single call on an
+          AVR unfortunately.
+    * Migrate `PrintStr::getCstr()` in AceCommon <=1.4.4 to the shorter
+      `PrintStr::cstr()` in AceCommon >= 1.4.5.
+    * Migrate to AceRoutine v1.3.1, which changes
+      `AceRoutine::coroutineMillis()` into non-virtual.
+    * Change `SystemClock` to instantiate from `SystemClockTemplate`, which
+      allows `SystemClock::clockMillis()` to also become non-virtual. Saves
+      20-40 bytes of flash. No discernible changes in CPU time.
 * 1.7.1 (2021-04-02)
     * Simplify calculation of `SystemClock::getSecondsSinceSyncAttempt()`
       and `SystemClock::getSecondsToSyncAttempt()`, which substantially

README.md

@@ -40,7 +40,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.7.1 (2021-04-02, TZ DB version 2021a)
+**Version**: 1.7.2 (2021-06-02, TZ DB version 2021a)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -75,7 +75,7 @@ installation instructions.
     * [Tool Chain](#ToolChain)
     * [Operating System](#OperatingSystem)
 * [License](#License)
-* [Feedback and Support](#FeedbackSupport)
+* [Feedback and Support](#FeedbackAndSupport)
 * [Authors](#Authors)
 
 <a name="Overview"></a>
@@ -563,15 +563,17 @@ See [docs/installation.md](docs/installation.md).
 
 * [README.md](README.md)
     * this file
-* [docs/date_time_timezone.md](docs/date_time_timezone.md)
+* Date, Time and TimeZones
+  ([docs/date_time_timezone.md](docs/date_time_timezone.md))
     * Date and Time classes
     * TimeZone classes
     * ZoneInfo Database
     * Mutations
     * Error Handling
     * Motivation and Design Considerations
     * Bugs and Limitations
-* [docs/clock_system_clock.md](docs/clock_system_clock.md)
+* Clocks and SystemClocks
+  ([docs/clock_system_clock.md](docs/clock_system_clock.md))
     * Clock
     * NTP Clock, DS3231 Clock, STM32 RTC Clock, STM32F1 Clock
     * SystemClock, SystemClockLoop, SystemClockCoroutine
@@ -655,7 +657,7 @@ them.
 
 [MIT License](https://opensource.org/licenses/MIT)
 
-<a name="FeedbackSupport"></a>
+<a name="FeedbackAndSupport"></a>
 ## Feedback and Support
 
 If you find this library useful, consider starring this project on GitHub. The

docs/clock_system_clock.md

@@ -12,7 +12,7 @@ sense for these classes to be in a separate library because the other parts of
 AceTime library are not dependent of the Clock classes. But for now, these
 classes live within the AceTime library.
 
-**Version**: 1.7.1 (2021-04-02, TZ DB version 2021a)
+**Version**: 1.7.2 (2021-06-02, TZ DB version 2021a)
 
 ## Table of Contents
 
@@ -49,7 +49,7 @@ classes live within the AceTime library.
 ## Overview
 
 The main purpose of the `Clock` classes in this module is to provide a 32-bit
-signed integer (`acetime_t` typedefed to `int32_t`) that represents the number
+signed integer (`acetime_t` typedef'ed to `int32_t`) that represents the number
 of seconds since a fixed point in the past called the "Epoch". The AceTime Epoch
 is defined to be 2000-01-01 00:00:00 UTC.
 
@@ -190,7 +190,7 @@ API, but subclasses are expected to provide the non-blocking interface when
 needed.
 
 The `acetime_t` value from `getNow()` can be converted into the desired time
-zone using the `ZonedDateTime` and `TimeZone` classes desribed in the previous
+zone using the `ZonedDateTime` and `TimeZone` classes described in the previous
 sections.
 
 <a name="NtpClock"></a>
@@ -278,7 +278,7 @@ you delete the commit, they can be retrieved from the git history.
 ## DS3231 Clock
 
 The `DS3231Clock` class uses the DS3231 RTC chip. It contains an internal
-temperature-compensated osciallator that counts time in 1 second steps. It is
+temperature-compensated oscillator that counts time in 1 second steps. It is
 often connected to a battery or a supercapacitor to survive power failures. The
 DS3231 chip stores the time broken down by various date and time components
 (i.e. year, month, day, hour, minute, seconds). It contains internal logic that
@@ -521,7 +521,7 @@ class SystemClock: public Clock {
 
     Clock* getReferenceClock() const { return mReferenceClock; }
 
-    virtual unsigned long clockMillis() const { return ::millis(); }
+    unsigned long clockMillis() const { return ::millis(); }
 
     void keepAlive();
 

docs/date_time_timezone.md

@@ -12,7 +12,7 @@ following namespaces:
   `ExtendedZoneManager`
 * `ace_time::internal`: not normally needed by app developers
 
-**Version**: 1.7.1 (2021-04-02, TZ DB version 2021a)
+**Version**: 1.7.2 (2021-06-02, TZ DB version 2021a)
 
 ## Table of Contents
 
@@ -62,6 +62,7 @@ following namespaces:
     * [TimeOffset Mutations](#TimeOffsetMutations)
     * [LocalDate Mutations](#LocalDateMutations)
     * [ZonedDateTime Mutations](#ZonedDateTimeMutations)
+    * [ZonedDateTime Normalization](#ZonedDateTimeNormalization)
     * [TimePeriod Mutations](#TimePeriodMutations)
 * [Error Handling](#ErrorHandling)
     * [isError()](#IsError)
@@ -82,7 +83,7 @@ following namespaces:
 The Date, Time, and TimeZone classes provide an abstraction layer to make it
 easier to use and manipulate date and time fields, in different time zones. It
 is difficult to organize the various parts of this library in the most easily
-digestable way, but perhaps they can be categorized into three parts:
+digestible way, but perhaps they can be categorized into three parts:
 
 * Simple Date and Time classes for converting date and time fields to and
   from the "epoch seconds",
@@ -1820,7 +1821,7 @@ const basic::ZoneInfo* zoneInfo = ...;
 PrintStr<32> printStr; // buffer of 32 bytes on the stack
 BasicZone(zoneInfo).printNameTo(printStr);
 
-const char* name = printStr.getCstr();
+const char* name = printStr.cstr();
 // do stuff with 'name', but only while 'printStr' is alive
 ...
 ```
@@ -2065,7 +2066,7 @@ which prints to the serial port.
 The AceCommon library (https://github.com:bxparks/AceCommon) provides a
 subclass of `Print` called `PrintStr` which allows printing to an in-memory
 buffer. The contents of the in-memory buffer can be retrieved as a normal
-c-string using the `PrintStr::getCstr()` method.
+c-string using the `PrintStr::cstr()` method.
 
 Instances of the `PrintStr` object is expected to be created on the stack. The
 object will be destroyed automatically when the stack is unwound after returning
@@ -2089,7 +2090,7 @@ using namespace ace_time;
 
   PrintStr<32> printStr; // 32-byte buffer
   dt.printTo(printStr);
-  const char* cstr = printStr.getCstr();
+  const char* cstr = printStr.cstr();
 
   // do stuff with cstr...
 
@@ -2114,10 +2115,12 @@ the code size increased by 500-700 bytes, which I could not afford because the
 program takes up almost the entire flash memory of an Ardunio Pro Micro with
 only 28672 bytes of flash memory.
 
-Most date and time classes in the AceTime library are mutable. The mutation
-operations are not implemented within the class itself to avoid bloating
-the class API surface. The mutation functions live as functions in separate
-namespaces outside of the class definitions:
+Most date and time classes in the AceTime library are mutable. Except for
+primitive mutations of setting specific fields (e.g.
+`ZonedDateTime::year(uint16_t)`), most higher-level mutation operations are not
+implemented within the class itself to avoid bloating the class API surface. The
+mutation functions live as functions in separate namespaces outside of the class
+definitions:
 
 * `time_period_mutation.h`
 * `time_offset_mutation.h`
@@ -2145,8 +2148,12 @@ increment the `ZonedDateTime::day()` field from Feb 29 to Feb 30, then to Feb
 converted into an Epoch seconds (using `toEpochSeconds()`), then converted back
 to a `ZonedDateTime` object (using `forEpochSeconds()`). By deferring this
 normalization step until the user has finished setting all the clock fields, we
-can reduce the size of the code in flash. (The limiting factor for many Arduino
-environments is the code size, not the CPU time.)
+can reduce the size of the code in flash. (The limiting factor for many 8-bit
+Arduino environments is the code size, not the CPU time.)
+
+Mutating the `ZonedDateTime` requires calling the `ZonedDateTime::normalize()`
+method after making the changes. See the subsection on [ZonedDateTime
+Normalization](#ZonedDateTimeNormalization) below.
 
 It is not clear that making the AceTime objects mutable was the best design
 decision. But it seems to produce far smaller code sizes (hundreds of bytes of
@@ -2161,6 +2168,9 @@ The `TimeOffset` object can be mutated with:
 
 ```C++
 namespace ace_time {
+
+void setMinutes(int16_t minutes) {
+
 namespace time_offset_mutation {
 
 void increment15Minutes(TimeOffset& offset);
@@ -2172,10 +2182,15 @@ void increment15Minutes(TimeOffset& offset);
 <a name="LocalDateMutations"></a>
 ### LocalDate Mutations
 
-The `LocalDate` object can be mutated with the following methods:
+The `LocalDate` object can be mutated with the following methods and functions:
 
 ```C++
 namespace ace_time {
+
+void LocalDate::year(int16_t year);
+void LocalDate::month(uint8_t month);
+void LocalDate::day(uint8_t month);
+
 namespace local_date_mutation {
 
 void incrementOneDay(LocalDate& ld);
@@ -2188,10 +2203,20 @@ void decrementOneDay(LocalDate& ld);
 <a name="ZonedDateTimeMutations"></a>
 ### ZonedDateTime Mutations
 
-The `ZonedDateTime` object can be mutated using the following methods:
+The `ZonedDateTime` object can be mutated using the following methods and
+functions:
 
 ```C++
 namespace ace_time {
+
+void ZonedDateTime::year(int16_t year);
+void ZonedDateTime::month(uint8_t month);
+void ZonedDateTime::day(uint8_t month);
+void ZonedDateTime::hour(uint8_t hour);
+void ZonedDateTime::minute(uint8_t minute);
+void ZonedDateTime::second(uint8_t second);
+void ZonedDateTime::timeZone(const TimeZone& timeZone);
+
 namespace zoned_date_time_mutation {
 
 void incrementYear(ZonedDateTime& dateTime);
@@ -2204,13 +2229,48 @@ void incrementMinute(ZonedDateTime& dateTime);
 }
 ```
 
+<a name="ZonedDateTimeNormalization"></a>
+### ZonedDateTimeNormalization
+
+When the `ZonedDateTime` object is mutated using the methods and functions
+listed above, the client code must call `ZonedDateTime::normalize()` before
+calling a method that calculates derivative information, in particular, the
+`ZonedDateTime::toEpochSeconds()` method. Otherwise, the resulting epochSeconds
+may be incorrect if the old `ZonedDateTime` and the new `ZonedDatetime` crosses
+a DST boundary. Multiple mutations can be batched before calling
+`normalize()`.
+
+For example:
+
+```C++
+
+TimeZone tz = ...;
+ZonedDateTime zdt = ZonedDateTime::forComponent(2000, 1, 1, 0, 0, 0, tz);
+
+zdt.year(2021);
+zdt.month(4);
+zdt.day(20);
+zdt.normalize();
+acetime_t newEpochSeconds = zdt.toEpochSeconds();
+```
+
+Adding this single call to `normalize()` seems to increase flash consumption by
+220 bytes on an 8-bit AVR processor. Unfortunately, it must be called to ensure
+accuracy across DST boundaries.
+
 <a name="TimePeriodMutations"></a>
 ### TimePeriod Mutations
 
 The `TimePeriod` can be mutated using the following methods:
 
 ```C++
 namespace ace_time {
+
+void TimePeriod::hour(uint8_t hour);
+void TimePeriod::minute(uint8_t minute);
+void TimePeriod::second(uint8_t second);
+void TimePeriod::sign(int8_t sign);
+
 namespace time_period_mutation {
 
 void negate(TimePeriod& period);

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.7.1
+PROJECT_NUMBER         = 1.7.2
 
 # 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.7.1</span>
+   &#160;<span id="projectnumber">1.7.2</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database, and a system clock that can synchronize from an NTP server or an RTC chip.</div>
   </td>
@@ -137,8 +137,8 @@
 <div class="line"><a name="l00075"></a><span class="lineno">   75</span>&#160; </div>
 <div class="line"><a name="l00076"></a><span class="lineno">   76</span>&#160; </div>
 <div class="line"><a name="l00077"></a><span class="lineno">   77</span>&#160;<span class="comment">// Version format: xxyyzz == &quot;xx.yy.zz&quot;</span></div>
-<div class="line"><a name="l00078"></a><span class="lineno">   78</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION 10701</span></div>
-<div class="line"><a name="l00079"></a><span class="lineno">   79</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION_STRING &quot;1.7.1&quot;</span></div>
+<div class="line"><a name="l00078"></a><span class="lineno">   78</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION 10702</span></div>
+<div class="line"><a name="l00079"></a><span class="lineno">   79</span>&#160;<span class="preprocessor">#define ACE_TIME_VERSION_STRING &quot;1.7.2&quot;</span></div>
 <div class="line"><a name="l00080"></a><span class="lineno">   80</span>&#160; </div>
 <div class="line"><a name="l00081"></a><span class="lineno">   81</span>&#160;<span class="preprocessor">#endif</span></div>
 </div><!-- fragment --></div><!-- contents -->

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.7.1</span>
+   &#160;<span id="projectnumber">1.7.2</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database, and a system clock that can synchronize from an NTP server or an RTC chip.</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.7.1</span>
+   &#160;<span id="projectnumber">1.7.2</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database, and a system clock that can synchronize from an NTP server or an RTC chip.</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.7.1</span>
+   &#160;<span id="projectnumber">1.7.2</span>
    </div>
    <div id="projectbrief">Date and time classes for Arduino that support timezones from the TZ Database, and a system clock that can synchronize from an NTP server or an RTC chip.</div>
   </td>