AceTime
1.11.7
Date and time classes for Arduino that support timezones from the TZ Database.
|
An implementation of ZoneProcessor that supports a subset of the zones containing in the TZ Database. More...
#include <BasicZoneProcessor.h>
Public Types | |
typedef basic::TransitionTemplate< ZIB, ZEB, ZPB, ZRB > | Transition |
Exposed only for testing purposes. | |
Public Member Functions | |
bool | isLink () const override |
Return true if timezone is a Link entry pointing to a Zone entry. | |
uint32_t | getZoneId (bool followLink=false) const override |
Return the unique stable zoneId. More... | |
TimeOffset | getUtcOffset (acetime_t epochSeconds) const override |
Return the total UTC offset at epochSeconds, including DST offset. More... | |
TimeOffset | getDeltaOffset (acetime_t epochSeconds) const override |
Return the DST delta offset at epochSeconds. More... | |
const char * | getAbbrev (acetime_t epochSeconds) const override |
Return the time zone abbreviation at epochSeconds. More... | |
OffsetDateTime | getOffsetDateTime (const LocalDateTime &ldt) const override |
Return the best estimate of the OffsetDateTime at the given LocalDateTime for the timezone of the current ZoneProcessor. More... | |
OffsetDateTime | getOffsetDateTime (acetime_t epochSeconds) const override |
Return the best estimate of the OffsetDateTime at the given epochSeconds for the timezone of the current ZoneProcessor, including the fold parameter. More... | |
void | printNameTo (Print &printer, bool followLink=false) const override |
Print a human-readable identifier (e.g. More... | |
void | printShortNameTo (Print &printer, bool followLink=false) const override |
Print a short human-readable identifier (e.g. More... | |
void | setZoneKey (uintptr_t zoneKey) override |
Set the opaque zoneKey of this object to a new value, reseting any internally cached information. More... | |
bool | equalsZoneKey (uintptr_t zoneKey) const override |
Return true if ZoneProcessor is associated with the given opaque zoneKey. More... | |
void | log () const |
Used only for debugging. | |
void | setBrokerFactory (const BF *brokerFactory) |
Set the broker factory at runtime. More... | |
![]() | |
uint8_t | getType () const |
Return the kTypeXxx of the current instance. | |
Protected Member Functions | |
BasicZoneProcessorTemplate (uint8_t type, const BF *brokerFactory, uintptr_t zoneKey) | |
Constructor. More... | |
![]() | |
ZoneProcessor (const ZoneProcessor &)=delete | |
ZoneProcessor & | operator= (const ZoneProcessor &)=delete |
ZoneProcessor (uint8_t type) | |
Constructor. | |
Additional Inherited Members | |
![]() | |
uint8_t const | mType |
An implementation of ZoneProcessor that supports a subset of the zones containing in the TZ Database.
The supported list of zones, as well as the list of unsupported zones, are is listed in the zonedb/zone_info.h header file. The constructor expects a pointer to one of the ZoneInfo structures declared in the zone_infos.h file.
The internal ZoneRule and ZoneEra records that match the year of the given epochSeconds are cached for performance. The expectation is that repeated calls to the various methods will have epochSeconds which do not vary too greatly and will occur in the same year.
The Rule records are transition points which look like this:
* Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S *
Each record is represented by basic::ZoneRule and the entire collection is represented by basic::ZonePolicy.
The Zone records define the region which follows a specific set of Rules for certain time periods (given by UNTIL below):
* Zone NAME GMTOFF RULES FORMAT [UNTIL] *
Each record is represented by basic::ZoneEra and the entire collection is represented by basic::ZoneInfo.
This class assumes that the various components of ZoneInfo, ZoneEra, and ZonePolicy, ZoneRule have a number of limitations and constraints which simplify the implementation of this class. The tzcompiler.py script will remove zones which do not meet these constraints when generating the structs defined by zonedb/zone_infos.h. The constraints are at least the following (see AceTimeTools/transformer.py for the authoratative algorithm):
Even with these limitations, zonedb/zone_info.h shows that 270 out of a total of 387 zones are supported by BasicZoneProcessor (as of v0.8).
Not thread-safe.
BF | type of BrokerFactory, needed for implementations that require more complex brokers, and allows this template class to be independent of the exact type of the zone primary key |
ZIB | type of ZoneInfoBroker |
ZEB | type of ZoneEraBroker |
ZPB | type of ZonePolicyBroker |
ZRB | type of ZoneRuleBroker |
Definition at line 204 of file BasicZoneProcessor.h.
|
inlineexplicitprotected |
Constructor.
When first initialized inside a cache, the brokerFactory may be set to nullptr, and the zoneKey should be ignored.
brokerFactory | pointer to a BrokerFactory that creates a ZIB |
zoneKey | an opaque Zone primary key (e.g. const ZoneInfo*, or a uint16_t) |
Definition at line 381 of file BasicZoneProcessor.h.
|
inlineoverridevirtual |
Return true if ZoneProcessor is associated with the given opaque zoneKey.
This method should be considered to be private.
Implements ace_time::ZoneProcessor.
Definition at line 341 of file BasicZoneProcessor.h.
|
inlineoverridevirtual |
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.
Implements ace_time::ZoneProcessor.
Definition at line 232 of file BasicZoneProcessor.h.
|
inlineoverridevirtual |
Return the DST delta offset at epochSeconds.
This is an experimental method that has not been tested thoroughly. Use with caution. Returns TimeOffset::forError() if an error occurs.
Implements ace_time::ZoneProcessor.
Definition at line 225 of file BasicZoneProcessor.h.
|
inlineoverridevirtual |
Return the best estimate of the OffsetDateTime at the given epochSeconds for the timezone of the current ZoneProcessor, including the fold parameter.
Returns OffsetDateTime::forError() if an error occurs, for example, if the epochSeconds is outside of the support date range of the underlying ZoneInfo files.
Implements ace_time::ZoneProcessor.
Definition at line 310 of file BasicZoneProcessor.h.
|
inlineoverridevirtual |
Return the best estimate of the OffsetDateTime at the given LocalDateTime for the timezone of the current ZoneProcessor.
Returns OffsetDateTime::forError() if an error occurs, for example, if the LocalDateTime is outside of the support date range of the underlying ZoneInfo files.
The Transitions calculated by BasicZoneProcessor contain only the epochSeconds when each transition occurs. They do not contain the local date/time components of the transition. This design reduces the amount of memory required by BasicZoneProcessor, but this means that the information needed to implement this method correctly does not exist.
The implementation is somewhat of a hack:
0) Use the localDateTime to extract the offset, assuming that the localDatetime is UTC. This will get us within 12-14h of the correct UTC offset. 1) Use (localDateTime, offset0) to determine offset1. 2) Use (localdateTime, offset1) to determine offset2. 3) Finally, check if offset1 and offset2 are equal. If they are we reached equilibrium so we can just return (localDateTime, offset1). If they are not equal, then we have a cycle because the localDateTime occurred in a DST gap (STD->DST transition) or overlap (DST->STD transition). We arbitrarily pick the offset of the later epochSeconds since that seems to match closely to what most people would expect to happen in a gap or overlap (e.g. In the gap of 2am->3am, a 2:30am would get shifted to 3:30am.)
The code is written slightly ackwardly to try to encourage the compiler to perform Return Value Optimization. For example, I use only a single OffsetDateTime instance, and I don't use early return.
Implements ace_time::ZoneProcessor.
Definition at line 266 of file BasicZoneProcessor.h.
|
inlineoverridevirtual |
Return the total UTC offset at epochSeconds, including DST offset.
Returns TimeOffset::forError() if an error occurs.
Implements ace_time::ZoneProcessor.
Definition at line 218 of file BasicZoneProcessor.h.
|
inlineoverridevirtual |
Return the unique stable zoneId.
followLink | if true and the time zone is a Link, follow the link and return the id of the target Zone instead. If the zone is not a link, this flag is ignored. |
Implements ace_time::ZoneProcessor.
Definition at line 211 of file BasicZoneProcessor.h.
|
inlineoverridevirtual |
Print a human-readable identifier (e.g.
"America/Los_Angeles").
printer | an instance of the Print class, usually Serial |
followLink | if true and the zone is actually a link, follow the link and return the name of the target Zone instead. If the zone is not a link, this flag is ignored. |
Implements ace_time::ZoneProcessor.
Definition at line 315 of file BasicZoneProcessor.h.
|
inlineoverridevirtual |
Print a short human-readable identifier (e.g.
"Los Angeles"). Any underscore in the short name is replaced with a space.
printer | an instance of the Print class, usually Serial |
followLink | if true and the zone is actually a link, follow the link and return the short name of the target Zone instead. If the zone is not a link, this flag is ignored. |
Implements ace_time::ZoneProcessor.
Definition at line 322 of file BasicZoneProcessor.h.
|
inline |
Set the broker factory at runtime.
This is an advanced usage where the custom subclass of ExtendedZoneProcessorTemplate does not know its broker factory at compile time, so it must be set at runtime through this method.
Definition at line 367 of file BasicZoneProcessor.h.
|
inlineoverridevirtual |
Set the opaque zoneKey of this object to a new value, reseting any internally cached information.
Normally a ZoneProcessor object is associated with a single TimeZone. However, the ZoneProcessorCache will sometimes "take over" a ZoneProcessor from another TimeZone using this method. The other TimeZone will take back control of the ZoneProcessor if needed. To avoid bouncing the ownership of this object repeatedly, the application should configure the ZoneProcessorCache with enough ZoneProcessors to handle the usage pattern of the given application.
This method should be considered to be private, to be used only by the TimeZone and ZoneProcessorCache classes. I had to make it public because it got too ugly to maintain the friend
list in C++.
Implements ace_time::ZoneProcessor.
Definition at line 330 of file BasicZoneProcessor.h.