diff --git a/docs/date_time_timezone.md b/docs/date_time_timezone.md index 072b44972..e546e94af 100644 --- a/docs/date_time_timezone.md +++ b/docs/date_time_timezone.md @@ -817,11 +817,11 @@ hold a reference to: ``` 0..1 TimeZone <>-------- ZoneProcessor - ^ - | - .----- +----. + ^ + | + .-----+-----. | | - BasicZoneProcessor ExtendedZoneProcessor + BasicZoneProcessor ExtendedZoneProcessor ``` Here is the class declaration of `TimeZone`: @@ -860,6 +860,7 @@ class TimeZone { static TimeZone forUtc(); TimeZone(); // same as forUtc() + bool isError() const; uint8_t getType() const; TimeOffset getStdOffset() const; @@ -869,10 +870,13 @@ 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; + + OffsetDateTime getOffsetDateTime(const LocalDateTime& ldt) const; bool isUtc() const; bool isDst() const; + + void setStdOffset(TimeOffset stdOffset); void setDstOffset(TimeOffset offset); TimeZoneData toTimeZoneData() const; @@ -898,17 +902,17 @@ points to a temporary buffer whose contents may change upon subsequent calls to 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 -is a best guess is because the local date time is sometime ambiguious during a -DST transition. For example, if the local clock shifts from 01:00 to 02:00 at -the start of summer, then the time of 01:30 does not exist. If the -`getUtcOffsetForDateTime()` method is given a non-existing time, it makes an -educated guess at what the user meant. Additionally, when the local time -transitions from 02:00 to 01:00 in the autumn, a given local time such as 01:30 -occurs twice. If the `getUtcOffsetForDateTime()` method is given a time of -01:30, it will arbitrarily decide which offset to return. +The `getOffsetDateTime(localDateTime)` method returns the best guess of +the `OffsetDateTime` at the given local date time. This method is used by +`ZonedDateTime::forComponents()` and is exposed mostly for debugging. The reaon +that this is a best guess is because the local date time is sometime ambiguious +during a DST transition. For example, if the local clock shifts from 01:00 to +02:00 at the start of summer, then the time of 01:30 does not exist. If the +`getOffsetDateTime()` method is given a non-existing time, it makes an educated +guess at what the user meant. Additionally, when the local time transitions from +02:00 to 01:00 in the autumn, a given local time such as 01:30 occurs twice. If +the `getOffsetDateTime()` method is given a time of 01:30, it will arbitrarily +decide which offset to return. The `isUtc()`, `isDst()` and `setDstOffset(TimeOffset)` methods are valid *only* if the `TimeZone` is a `kTypeManual`. Otherwise, `isUtc()` and `isDst()` return diff --git a/keywords.txt b/keywords.txt index 066ce214c..403a42e7c 100644 --- a/keywords.txt +++ b/keywords.txt @@ -174,7 +174,7 @@ getType KEYWORD2 getUtcOffset KEYWORD2 getDeltaOffset KEYWORD2 getAbbrev KEYWORD2 -getUtcOffsetForDateTime KEYWORD2 +getOffsetDateTime KEYWORD2 printTo KEYWORD2 printShortTo KEYWORD2 @@ -183,7 +183,7 @@ getType KEYWORD2 getUtcffset KEYWORD2 getDeltaOffset KEYWORD2 getAbbrev KEYWORD2 -getUtcOffsetForDateTime KEYWORD2 +getOffsetDateTime KEYWORD2 printNameTo KEYWORD2 printShortNameTo KEYWORD2 @@ -192,7 +192,7 @@ getType KEYWORD2 getUtcffset KEYWORD2 getDeltaOffset KEYWORD2 getAbbrev KEYWORD2 -getUtcOffsetForDateTime KEYWORD2 +getOffsetDateTime KEYWORD2 resetTransitionHighWater KEYWORD2 getTransitionHighWater KEYWORD2 printNameTo KEYWORD2 diff --git a/src/ace_time/ZonedDateTime.h b/src/ace_time/ZonedDateTime.h index 483399a28..fabc12418 100644 --- a/src/ace_time/ZonedDateTime.h +++ b/src/ace_time/ZonedDateTime.h @@ -36,9 +36,8 @@ class ZonedDateTime { * This is intended mostly for testing purposes. Most production code * will use the forEpochSeconds() method. * - * The TimeOffset at the given date/time component is calculated using the - * ZoneProcessor::getUtcOffsetForDateTime() determined by the actual - * subtype of ZoneProcessor held by the given timeZone. + * The TimeOffset at the given date/time component is calculated using + * TimeZone::getOffsetDateTime(). * * @param year [1873-2127] * @param month month with January=1, December=12