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< D > | 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 () const override |
| Return the unique stable zoneId. | |
| FindResult | findByLocalDateTime (const LocalDateTime &ldt) const override |
| Return the search results at given LocalDateTime. More... | |
| FindResult | findByEpochSeconds (acetime_t epochSeconds) const override |
| Return the search results at given epochSeconds. | |
| void | printNameTo (Print &printer) const override |
| Print a human-readable identifier (e.g. More... | |
| void | printShortNameTo (Print &printer) const override |
| Print a short human-readable identifier (e.g. More... | |
| void | printTargetNameTo (Print &printer) const override |
| Print the full 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 | setZoneInfoStore (const typename D::ZoneInfoStore *zoneInfoStore) |
| Set the zone info store at runtime. More... | |
 Public Member Functions inherited from ace_time::ZoneProcessor | |
| uint8_t | getType () const |
| Return the kTypeXxx of the current instance. | |
Protected Member Functions | |
| BasicZoneProcessorTemplate (uint8_t type, const typename D::ZoneInfoStore *zoneInfoStore, uintptr_t zoneKey) | |
| Constructor. More... | |
| Protected Member Functions inherited from ace_time::ZoneProcessor | |
| ZoneProcessor (const ZoneProcessor &)=delete | |
| ZoneProcessor & | operator= (const ZoneProcessor &)=delete |
| ZoneProcessor (uint8_t type) | |
| Constructor. | |
| bool | isFilled (int16_t year) const |
| Check if the Transition cache is filled for the given year and current epochYear. More... | |
Additional Inherited Members | |
| Protected Attributes inherited from ace_time::ZoneProcessor | |
| uint8_t const | mType |
| User-visible indicator of the subclass of ZoneProcessor, which implments a specific time-zone algorithm. More... | |
| int16_t | mYear = LocalDate::kInvalidYear |
| Year that was used to calculate the transitions in the current cache. More... | |
| int16_t | mEpochYear = LocalDate::kInvalidYear |
| Epoch year that was used to calculate the transitions in the current cache. More... | |
Detailed Description
template<typename D>
class ace_time::BasicZoneProcessorTemplate< D >
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::Info::ZoneRule and the entire collection is represented by basic::Info::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::Info::ZoneEra and the entire collection is represented by basic::Info::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):
- ZoneInfo UNTIL field must contain only the full year; cannot contain month, day, or time components
- ZoneInfo untilTimeSuffix can contain only 'w' (not 's' or 'u')
- ZonePolicy can contain only 1 ZoneRule in a single month
- ZoneRule AT time cannot occur on Jan 1
- ZoneRule atTimeSuffix can be any of ('w', 's', and 'u')
- ZoneRule LETTER must contain only a single letter (not "WAT" or "CST")
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.
- Template Parameters
-
B broker type
Definition at line 191 of file BasicZoneProcessor.h.
Constructor & Destructor Documentation
◆ BasicZoneProcessorTemplate()
|
inlineexplicitprotected |
Constructor.
When first initialized inside a cache, the zoneInfoStore may be set to nullptr, and the zoneKey should be ignored.
- Parameters
-
type indentifier for the specific subclass of ZoneProcessor (e.g. Basic versus Extended) mostly used for debugging zoneInfoStore pointer to a ZoneInfoStore that creates a ZoneInfoBroker zoneKey an opaque Zone primary key (e.g. const ZoneInfo*, or a uint16_t index into a database table of ZoneInfo records)
Definition at line 363 of file BasicZoneProcessor.h.
Member Function Documentation
◆ equalsZoneKey()
|
inlineoverridevirtual |
Return true if ZoneProcessor is associated with the given opaque zoneKey.
This method should be considered to be private.
- Parameters
-
zoneKey an opaque Zone primary key (e.g. const ZoneInfo*, or a uint16_t index into a database table of ZoneInfo records)
Implements ace_time::ZoneProcessor.
Definition at line 322 of file BasicZoneProcessor.h.
◆ findByLocalDateTime()
|
inlineoverridevirtual |
Return the search results at given LocalDateTime.
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.)
This algorithm will detect a FindResult::kTypeGap, but it will not be able to distinguish between a kTypeExact and kTypeOverlap.
Implements ace_time::ZoneProcessor.
Definition at line 232 of file BasicZoneProcessor.h.
◆ printNameTo()
|
inlineoverridevirtual |
Print a human-readable identifier (e.g.
"America/Los_Angeles").
- Parameters
-
printer an instance of the Print class, usually Serial
Implements ace_time::ZoneProcessor.
Definition at line 299 of file BasicZoneProcessor.h.
◆ printShortNameTo()
|
inlineoverridevirtual |
Print a short human-readable identifier (e.g.
"Los Angeles"). Any underscore in the short name is replaced with a space.
- Parameters
-
printer an instance of the Print class, usually Serial
Implements ace_time::ZoneProcessor.
Definition at line 303 of file BasicZoneProcessor.h.
◆ printTargetNameTo()
|
inlineoverridevirtual |
Print the full identifier (e.g.
"America/Los_Angeles") of the target zone if the current zone is a Link entry. Otherwise, print nothing.
- Parameters
-
printer an instance of the Print class, usually Serial
Implements ace_time::ZoneProcessor.
Definition at line 307 of file BasicZoneProcessor.h.
◆ setZoneInfoStore()
|
inline |
Set the zone info store at runtime.
This is an advanced usage where the custom subclass of ExtendedZoneProcessorTemplate does not know its zone info store at compile time, so it must be set at runtime through this method.
Definition at line 346 of file BasicZoneProcessor.h.
◆ setZoneKey()
|
inlineoverridevirtual |
Set the opaque zoneKey of this object to a new value, reseting any internally cached information.
If the new zoneKey is the same as the old zoneKey, the cache remains valid.
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++.
- Parameters
-
zoneKey an opaque Zone primary key (e.g. const ZoneInfo*, or a uint16_t index into a database table of ZoneInfo records)
Implements ace_time::ZoneProcessor.
Definition at line 313 of file BasicZoneProcessor.h.
The documentation for this class was generated from the following file:
- /home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/BasicZoneProcessor.h
