AceTime
1.11.6
Date and time classes for Arduino that support timezones from the TZ Database.
|
An implementation of ZoneProcessor that supports for all zones defined by the TZ Database. More...
#include <ExtendedZoneProcessor.h>
Public Types | |
typedef extended::TransitionTemplate< ZEB, ZPB, ZRB > | Transition |
Exposed only for testing purposes. | |
typedef extended::MatchingTransitionTemplate< ZEB, ZPB, ZRB > | MatchingTransition |
Exposed only for testing purposes. | |
typedef extended::TransitionResultTemplate< ZEB, ZPB, ZRB > | TransitionResult |
Exposed only for testing purposes. | |
typedef extended::MatchingEraTemplate< ZEB > | MatchingEra |
Exposed only for testing purposes. | |
typedef extended::TransitionStorageTemplate< kMaxTransitions, ZEB, ZPB, ZRB > | TransitionStorage |
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 |
OffsetDateTime | getOffsetDateTime (acetime_t epochSeconds) const override |
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 | log () const |
Used only for debugging. | |
void | resetTransitionAllocSize () |
Reset the TransitionStorage high water mark. More... | |
uint8_t | getTransitionAllocSize () const |
Get the largest allocation size of TransitionStorage. 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 | setBrokerFactory (const BF *brokerFactory) |
Set the broker factory at runtime. More... | |
bool | initForEpochSeconds (acetime_t epochSeconds) const |
Initialize using the epochSeconds. More... | |
bool | initForYear (int16_t year) const |
Initialize the zone rules cache, keyed by the "current" year. More... | |
![]() | |
uint8_t | getType () const |
Return the kTypeXxx of the current instance. | |
Static Public Attributes | |
static const uint8_t | kMaxTransitions = 8 |
Max number of Transitions required for all Zones supported by this class. More... | |
Protected Member Functions | |
ExtendedZoneProcessorTemplate (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 for all zones defined by the TZ Database.
The supported zones are defined in the zonedbx/zone_infos.h header file. The constructor expects a pointer to one of the ZoneInfo structures declared in the zonedbx/zone_infos.h file. The zone_processor.py file is the initial Python implementation of this class, which got translated into C++.
The underlying zoneinfo files (extended::ZoneInfo, etc) store the UTC and DST offsets of a timezone as a single signed byte in 15-minute increments. This is sufficient to accurate describe all time zones from the year 2000 until
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 925 of file ExtendedZoneProcessor.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 1262 of file ExtendedZoneProcessor.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 1152 of file ExtendedZoneProcessor.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 989 of file ExtendedZoneProcessor.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 978 of file ExtendedZoneProcessor.h.
|
inlineoverridevirtual |
This implementation calculates the OffsetDateTime.fold()
parameter correctly, and indicates whether the localized datetime is before the overlap (fold==0) or after the overlap (fold==1). During a gap, there is no ambiguity when searching on epochSeconds so fold will always be 0.
Implements ace_time::ZoneProcessor.
Definition at line 1088 of file ExtendedZoneProcessor.h.
|
inlineoverridevirtual |
In this implementation, the LocalDateTime.fold()
parameter is an input parameter that determines whether to return the earlier Transition (fold==0) or the later Transition (fold==1). This is intended to be the same algorithm as Python PEP 495. In other words:
See also the zone_processor.ZoneProcessor._find_transition_for_datetime_python() function in the AceTimePython project.
Implements ace_time::ZoneProcessor.
Definition at line 1017 of file ExtendedZoneProcessor.h.
|
inline |
Get the largest allocation size of TransitionStorage.
For debugging.
Definition at line 1137 of file ExtendedZoneProcessor.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 966 of file ExtendedZoneProcessor.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 959 of file ExtendedZoneProcessor.h.
|
inline |
Initialize using the epochSeconds.
The epochSeconds is converted to the LocalDate for UTC time, and the year is used to call initForYear(). Exposed for debugging.
Definition at line 1171 of file ExtendedZoneProcessor.h.
|
inline |
Initialize the zone rules cache, keyed by the "current" year.
Returns success status: true if successful, false if an error occurred. Exposed for debugging.
Definition at line 1181 of file ExtendedZoneProcessor.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 1103 of file ExtendedZoneProcessor.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 1110 of file ExtendedZoneProcessor.h.
|
inline |
Reset the TransitionStorage high water mark.
For debugging.
Definition at line 1132 of file ExtendedZoneProcessor.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 1162 of file ExtendedZoneProcessor.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 1141 of file ExtendedZoneProcessor.h.
|
static |
Max number of Transitions required for all Zones supported by this class.
This includes the most recent prior Transition. The max transitions for each Zone is given by the kZoneBufSize{zoneName} constant in the generated zonedb[x]/zone_infos.h
file. The maximum over all zones is given in the 'MaxBufSize' comment in the zone_infos.h
file. Currently that overall maximum is 7, which has been verified by the ExtendedDateUtilTest, ExtendedJavaTest, and ExtendedAcetzTest validation tests. We set this to one more than 7 for safety.
Definition at line 937 of file ExtendedZoneProcessor.h.