Merge pull request #15 from bxparks/develop

bxparks · web-flow · commit 352722a08e47 · 2019-08-13T17:07:06.000-07:00
0.7.1 - replace TimeZone::printToAbbrev() with getAbbrev()
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,9 @@
 # Changelog
 
 * Unreleased
+* 0.7.1
+    * Replace `TimeZone::printAbbrevTo()` with more
+      flexible and useful `TimeZone::getAbbrev()`.
 * 0.7
     * Change TimeZoneData to store mStdOffset and mDstOffset in units of
       one minute (instead of 15-minute increments, "code") in the off chance
diff --git a/README.md b/README.md
@@ -204,7 +204,7 @@ Conversion from an epochSeconds to date-time components including timezone
 * 2.8 microseconds on an ESP32,
 * 6 microseconds on a Teensy 3.2.
 
-**Version**: 0.7 (2019-08-13, TZ DB version 2019b, beta)
+**Version**: 0.7.1 (2019-08-13, TZ DB version 2019b, beta)
 
 **Status**: Upgraded to latest TZ DB version 2019b. Validated against 3
 other timezone libraries (Python, Java, C++). See [CHANGELOG.md](CHANGELOG.md)
@@ -273,7 +273,7 @@ void setup() {
 
   // Print the current time zone abbreviation, e.g. "PST" or "PDT"
   Serial.print(F("Abbreviation: "));
-  pacificTz.printAbbrevTo(Serial, epochSeconds);
+  Serial.print(pacificTz.getAbbrev(epochSeconds));
   Serial.println();
 
   // Create from epoch seconds. London is still on standard time.
@@ -291,7 +291,7 @@ void setup() {
 
   // Print the current time zone abbreviation, e.g. "PST" or "PDT"
   Serial.print(F("Abbreviation: "));
-  londonTz.printAbbrevTo(Serial, epochSeconds);
+  Serial.print(londonTz.getAbbrev(epochSeconds));
   Serial.println();
 
   Serial.println(F("=== Compare ZonedDateTime"));
diff --git a/USER_GUIDE.md b/USER_GUIDE.md
@@ -2,7 +2,7 @@
 
 See the [README.md](README.md) for introductory background.
 
-Version: 0.7 (2019-08-13, TZ DB version 2019b, beta)
+Version: 0.7.1 (2019-08-13, TZ DB version 2019b, beta)
 
 ## Installation
 
@@ -798,6 +798,7 @@ class TimeZone {
 
     TimeOffset getUtcOffset(acetime_t epochSeconds) const;
     TimeOffset getDeltaOffset(acetime_t epochSeconds) const;
+    const char* getAbbrev(acetime_t epochSeconds) const;
     TimeOffset getUtcOffsetForDateTime(const LocalDateTime& ldt) const;
 
     bool isUtc() const;
@@ -806,7 +807,6 @@ class TimeZone {
 
     void printTo(Print& printer) const;
     void printShortTo(Print& printer) const;
-    void printAbbrevTo(Print& printer, acetime_t epochSeconds) const;
 };
 
 }
@@ -817,6 +817,15 @@ DST offset) at the given `epochSeconds`. The `getDeltaOffset()` returns only the
 additional DST offset; if DST is not in effect at the given `epochSeconds`, this
 returns a `TimeOffset` whose `isZero()` returns true.
 
+The `getAbbrev(epochSeconds)` method returns the human-readable timezone
+abbreviation used at the given `epochSeconds`. For example, this be "PST" for
+Pacific Standard Time, or "BST" for British Summer Time. The returned c-string
+should be used as soon as possible (e.g. printed to Serial) because the pointer
+points to a temporary buffer whose contents may change upon subsequent calls to
+`getUtcOffset()`, `getDeltaOffset()` and `getAbbrev()`. If the abbreviation
+needs to be saved for a longer period of time, it should be saved to another
+char buffer.
+
 The `getUtcOffsetForDateTime(localDateTime)` method returns the best guess of
 the total UTC offset at the given local date time. This method is not
 normally expected to be used by the app developer directly. The reaon that this
@@ -845,11 +854,6 @@ last component of the IANA TZ Database zone names. In other words,
 `"America/Los_Angeles"` is printed as `"Los_Angeles"`. This is helpful for
 printing on small width OLED displays.
 
-The `printAbbrevTo(printer, epochSeconds)` method prints the human-readable
-timezone abbreviation used at the given `epochSeconds` to the `printer`. For
-example, this be "PST" for Pacific Standard Time, or "BST" for British Summer
-Time.
-
 #### Manual TimeZone (kTypeManual)
 
 The default constructor creates a `TimeZone` in UTC time zone with no
@@ -2585,9 +2589,10 @@ and
 [ExtendedValidationUsingHinnantDateTest](tests/validation/ExtendedValidationUsingHinnantDateTest/)
 validation tests (in v0.7) which are the AceTime algorithms to the Hinnant Date
 algorithms. For all times zones between the years 2000 until 2050, the AceTime
-UTC offsets (`TimeZone::getUtcOffset()`) and epochSecond conversion to
-date components (`ZonedDateTime::fromEpochSeconds()`) match the results from the
-Hinannt Date libraries perfectly.
+UTC offsets (`TimeZone::getUtcOffset()`), timezone abbreviations
+(`TimeZone::getAbbrev()`), and epochSecond conversion to date components
+(`ZonedDateTime::fromEpochSeconds()`) match the results from the Hinannt Date
+libraries.
 
 ### Google cctz
 
diff --git a/examples/HelloDateTime/HelloDateTime.ino b/examples/HelloDateTime/HelloDateTime.ino
@@ -76,7 +76,7 @@ void setup() {
 
   // Print the current time zone abbreviation, e.g. "PST" or "PDT"
   SERIAL_PORT_MONITOR.print(F("Abbreviation: "));
-  pacificTz.printAbbrevTo(SERIAL_PORT_MONITOR, epochSeconds);
+  SERIAL_PORT_MONITOR.print(pacificTz.getAbbrev(epochSeconds));
   SERIAL_PORT_MONITOR.println();
 
   // Create from epoch seconds. London is still on standard time.
@@ -94,7 +94,7 @@ void setup() {
 
   // Print the current time zone abbreviation, e.g. "PST" or "PDT"
   SERIAL_PORT_MONITOR.print(F("Abbreviation: "));
-  londonTz.printAbbrevTo(SERIAL_PORT_MONITOR, epochSeconds);
+  SERIAL_PORT_MONITOR.print(londonTz.getAbbrev(epochSeconds));
   SERIAL_PORT_MONITOR.println();
 
   SERIAL_PORT_MONITOR.println(F("=== Compare ZonedDateTime"));
diff --git a/examples/WorldClock/Presenter.cpp b/examples/WorldClock/Presenter.cpp
@@ -5,10 +5,12 @@
 void Presenter::displayAbout() const {
   mOled.set1X();
 
-  // For smallest flash memory size, use F() macros for these longer
-  // strings, but no F() for shorter version strings.
-  mOled.print(F("AT: "));
+  // For smallest flash memory size, use F() macros for these longer strings,
+  // but no F() for shorter version strings. Comment out the headers, to save
+  // 38 bytes because I'm 12 bytes over the 30kB limit of a Pro Micro.
+
+  //mOled.print(F("AT: "));
   mOled.println(F(ACE_TIME_VERSION_STRING));
-  mOled.print(F("TZ: "));
+  //mOled.print(F("TZ: "));
   mOled.println(zonedb::kTzDatabaseVersion);
 }
diff --git a/examples/WorldClock/Presenter.h b/examples/WorldClock/Presenter.h
@@ -99,9 +99,8 @@ class Presenter {
       const ZonedDateTime dateTime = ZonedDateTime::forEpochSeconds(
           mRenderingInfo.now, mRenderingInfo.timeZone);
       if (dateTime.isError()) {
-        mOled.println(F("9999-99-99"));
-        mOled.println(F("99:99:99"));
-        mOled.println(F("Error"));
+        clearDisplay();
+        mOled.println(F("<Error>"));
         return;
       }
 
@@ -145,7 +144,7 @@ class Presenter {
       // place name
       mOled.println();
       acetime_t epochSeconds = dateTime.toEpochSeconds();
-      dateTime.timeZone().printAbbrevTo(mOled, epochSeconds);
+      mOled.print(dateTime.timeZone().getAbbrev(epochSeconds));
       mOled.print(' ');
       mOled.print('(');
       mOled.print(mRenderingInfo.name);
@@ -222,7 +221,7 @@ class Presenter {
 
       // abbreviation and place name
       mOled.println();
-      dateTime.timeZone().printAbbrevTo(mOled, mRenderingInfo.now);
+      mOled.print(dateTime.timeZone().getAbbrev(mRenderingInfo.now));
       mOled.print(' ');
       mOled.print('(');
       mOled.print(mRenderingInfo.name);
diff --git a/examples/WorldClock/RenderingInfo.h b/examples/WorldClock/RenderingInfo.h
@@ -20,7 +20,7 @@ struct RenderingInfo {
   const char* name;
   uint8_t hourMode;
   bool blinkingColon;
-  ace_time::TimeZone timeZone;
+  TimeZone timeZone;
 };
 
 #endif
diff --git a/keywords.txt b/keywords.txt
@@ -212,13 +212,13 @@ toTimeZoneData	KEYWORD2
 getType	KEYWORD2
 getUtcOffset	KEYWORD2
 getDeltaOffset	KEYWORD2
+getAbbrev	KEYWORD2
 getOffsetDateTime	KEYWORD2
 isUtc	KEYWORD2
 isDst	KEYWORD2
 setDstOffset	KEYWORD2
 printTo	KEYWORD2
 printShortTo	KEYWORD2
-printAbbrevTo	KEYWORD2
 
 # ZoneManager.h
 createForZoneInfo	KEYWORD2
diff --git a/library.properties b/library.properties
@@ -1,5 +1,5 @@
 name=AceTime
-version=0.7
+version=0.7.1
 author=Brian T. Park <brian@xparks.net>
 maintainer=Brian T. Park <brian@xparks.net>
 sentence=Date, time, clock, and TZ Database timezones for Arduino.
diff --git a/src/AceTime.h b/src/AceTime.h
@@ -55,7 +55,7 @@
 #include "ace_time/clock/SystemClockCoroutine.h"
 
 // Version format: xxyyzz == "xx.yy.zz"
-#define ACE_TIME_VERSION 700
-#define ACE_TIME_VERSION_STRING "0.7"
+#define ACE_TIME_VERSION 701
+#define ACE_TIME_VERSION_STRING "0.7.1"
 
 #endif
diff --git a/src/ace_time/TimeZone.cpp b/src/ace_time/TimeZone.cpp
@@ -67,30 +67,4 @@ void TimeZone::printShortTo(Print& printer) const {
   printer.print("<Error>");
 }
 
-void TimeZone::printAbbrevTo(Print& printer, acetime_t epochSeconds) const {
-  switch (mType) {
-    case kTypeManual:
-      if (isUtc()) {
-        printer.print("UTC");
-      } else {
-        printer.print((mDstOffsetMinutes != 0) ? "DST" : "STD");
-      }
-      return;
-    case kTypeBasic:
-    case kTypeExtended:
-      printer.print(mZoneProcessor->getAbbrev(epochSeconds));
-      return;
-    case kTypeBasicManaged:
-    case kTypeExtendedManaged:
-    {
-      ZoneProcessor* processor =
-          mZoneProcessorCache->getZoneProcessor(mZoneInfo);
-      if (! processor) break;
-      printer.print(processor->getAbbrev(epochSeconds));
-      return;
-    }
-  }
-  printer.print("<Error>");
-}
-
 }
diff --git a/src/ace_time/TimeZone.h b/src/ace_time/TimeZone.h
@@ -233,6 +233,49 @@ class TimeZone {
       return TimeOffset::forError();
     }
 
+    /**
+     * Return the time zone abbreviation at the given epochSeconds.
+     *
+     *   * kTypeManual returns "STD" or "DST",
+     *   * kTypeBasic, kTypeBasic, kTypeBasicManaged, kTypeExtendedManaged
+     *      * returns the "{abbrev}" (e.g. "PDT"),
+     *   * the empty string "" upon error.
+     *
+     * The IANA spec
+     * (https://data.iana.org/time-zones/theory.html#abbreviations) says that
+     * abbreviations are limited to 6 characters. It is unclear if this spec is
+     * guaranteed to be followed. Client programs should handle abbreviations
+     * longer than 6 characters to be safe.
+     *
+     * Warning: The returned pointer points to a char buffer that could get
+     * overriden by subsequent method calls to this object. The pointer must
+     * not be stored permanently, it should be used as soon as possible (e.g.
+     * printed out). If you need to store the abbreviation for a long period
+     * of time, copy it to anther char buffer.
+     */
+    const char* getAbbrev(acetime_t epochSeconds) const {
+      switch (mType) {
+        case kTypeManual:
+          if (isUtc()) {
+            return "UTC";
+          } else {
+            return (mDstOffsetMinutes != 0) ? "DST" : "STD";
+          }
+        case kTypeBasic:
+        case kTypeExtended:
+          return mZoneProcessor->getAbbrev(epochSeconds);
+        case kTypeBasicManaged:
+        case kTypeExtendedManaged:
+        {
+          ZoneProcessor* processor =
+              mZoneProcessorCache->getZoneProcessor(mZoneInfo);
+          if (! processor) break;
+          return processor->getAbbrev(epochSeconds);
+        }
+      }
+      return "";
+    }
+
     /**
      * Return the best estimate of the OffsetDateTime at the given
      * LocalDateTime for the current TimeZone. Used by
@@ -345,14 +388,6 @@ class TimeZone {
      */
     void printShortTo(Print& printer) const;
 
-    /**
-     * Print the time zone abbreviation for the given epochSeconds.
-     *   * kTypeManual is printed as "STD" or "DST"
-     *   * kTypeBasic is printed as "{abbrev}" (e.g. "PDT")
-     *   * kTypeExtended is printed as "{abbrev}" (e.g. "PDT")
-     */
-    void printAbbrevTo(Print& printer, acetime_t epochSeconds) const;
-
     // Use default copy constructor and assignment operator.
     TimeZone(const TimeZone&) = default;
     TimeZone& operator=(const TimeZone&) = default;
diff --git a/src/ace_time/ZoneProcessor.h b/src/ace_time/ZoneProcessor.h
@@ -79,9 +79,14 @@ class ZoneProcessor {
     virtual TimeOffset getDeltaOffset(acetime_t epochSeconds) const = 0;
 
     /**
-     * Return the time zone abbreviation at epochSeconds. This is an
-     * experimental method that has not been tested thoroughly. Use with
-     * caution. Returns an empty string ("") if an error occurs.
+     * Return the time zone abbreviation at epochSeconds. Returns an empty
+     * string ("") if an error occurs. The returned pointer points to a char
+     * buffer that could get overriden by subsequent method calls to this
+     * object. The pointer must not be stored permanently, it should be used as
+     * soon as possible (e.g. printed out).
+     *
+     * This is an experimental method that has not been tested thoroughly. Use
+     * with caution.
      */
     virtual const char* getAbbrev(acetime_t epochSeconds) const = 0;
 
diff --git a/tests/TimeZoneExtendedTest/TimeZoneExtendedTest.ino b/tests/TimeZoneExtendedTest/TimeZoneExtendedTest.ino
@@ -1,11 +1,9 @@
 #line 2 "TimeZoneExtendedTest.ino"
 
 #include <AUnit.h>
-#include <aunit/fake/FakePrint.h>
 #include <AceTime.h>
 
 using namespace aunit;
-using namespace aunit::fake;
 using namespace ace_time;
 
 // --------------------------------------------------------------------------
@@ -43,7 +41,6 @@ test(TimeZoneExtendedTest, createFor) {
 }
 
 test(TimeZoneExtendedTest, Los_Angeles) {
-  FakePrint fakePrint;
   OffsetDateTime dt;
   acetime_t epochSeconds;
 
@@ -56,17 +53,14 @@ test(TimeZoneExtendedTest, Los_Angeles) {
   epochSeconds = dt.toEpochSeconds();
   assertEqual(-8*60, tz.getUtcOffset(epochSeconds).toMinutes());
   assertEqual(0, tz.getDeltaOffset(epochSeconds).toMinutes());
-  tz.printAbbrevTo(fakePrint, epochSeconds);
-  assertEqual(F("PST"), fakePrint.getBuffer());
-  fakePrint.flush();
+  assertEqual(F("PST"), tz.getAbbrev(epochSeconds));
 
   dt = OffsetDateTime::forComponents(2018, 3, 11, 2, 0, 0,
       TimeOffset::forHours(-8));
   epochSeconds = dt.toEpochSeconds();
   assertEqual(-7*60, tz.getUtcOffset(epochSeconds).toMinutes());
   assertEqual(1*60, tz.getDeltaOffset(epochSeconds).toMinutes());
-  tz.printAbbrevTo(fakePrint, epochSeconds);
-  assertEqual(F("PDT"), fakePrint.getBuffer());
+  assertEqual(F("PDT"), tz.getAbbrev(epochSeconds));
 }
 
 // --------------------------------------------------------------------------
diff --git a/tests/TimeZoneTest/TimeZoneTest.ino b/tests/TimeZoneTest/TimeZoneTest.ino
diff --git a/tests/validation/BasicValidationUsingHinnantDateTest/TransitionTest.h b/tests/validation/BasicValidationUsingHinnantDateTest/TransitionTest.h
diff --git a/tests/validation/BasicValidationUsingHinnantDateTest/ValidationDataType.h b/tests/validation/BasicValidationUsingHinnantDateTest/ValidationDataType.h
diff --git a/tests/validation/ExtendedValidationUsingHinnantDateTest/TransitionTest.h b/tests/validation/ExtendedValidationUsingHinnantDateTest/TransitionTest.h
diff --git a/tests/validation/ExtendedValidationUsingHinnantDateTest/ValidationDataType.h b/tests/validation/ExtendedValidationUsingHinnantDateTest/ValidationDataType.h
diff --git a/tools/cpp/test_data_generator.cpp b/tools/cpp/test_data_generator.cpp

-Original file line number
+Diff line change
@@ @@ -1,5 +1,5 @@ @@
 name=AceTime
 -version=0.7
 +version=0.7.1
 author=Brian T. Park <[email protected]>
 maintainer=Brian T. Park <[email protected]>
 sentence=Date, time, clock, and TZ Database timezones for Arduino.