AceTime  3.0.0
Date and time classes for Arduino that support timezones from the TZ Database.
Public Types | Public Member Functions | Protected Member Functions | Friends | List of all members
ace_time::BasicZoneProcessorTemplate< D > Class Template Reference

An implementation of ZoneProcessor that supports a subset of the zones containing in the TZ Database. More...

#include <BasicZoneProcessor.h>

Inheritance diagram for ace_time::BasicZoneProcessorTemplate< D >:
Inheritance graph
[legend]
Collaboration diagram for ace_time::BasicZoneProcessorTemplate< D >:
Collaboration graph
[legend]

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
 
ZoneProcessoroperator= (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...
 

Friends

class ::BasicZoneProcessorTest_priorYearOfRule
 
class ::BasicZoneProcessorTest_compareRulesBeforeYear
 
class ::BasicZoneProcessorTest_findLatestPriorRule
 
class ::BasicZoneProcessorTest_findZoneEra
 
class ::BasicZoneProcessorTest_init_primitives
 
class ::BasicZoneProcessorTest_initForLocalDate
 
class ::BasicZoneProcessorTest_setZoneKey
 
class ::BasicZoneProcessorTest_calcRuleOffsetMinutes
 

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):

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
Bbroker type

Definition at line 191 of file BasicZoneProcessor.h.

Constructor & Destructor Documentation

◆ BasicZoneProcessorTemplate()

template<typename D >
ace_time::BasicZoneProcessorTemplate< D >::BasicZoneProcessorTemplate ( uint8_t  type,
const typename D::ZoneInfoStore *  zoneInfoStore,
uintptr_t  zoneKey 
)
inlineexplicitprotected

Constructor.

When first initialized inside a cache, the zoneInfoStore may be set to nullptr, and the zoneKey should be ignored.

Parameters
typeindentifier for the specific subclass of ZoneProcessor (e.g. Basic versus Extended) mostly used for debugging
zoneInfoStorepointer to a ZoneInfoStore that creates a ZoneInfoBroker
zoneKeyan 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()

template<typename D >
bool ace_time::BasicZoneProcessorTemplate< D >::equalsZoneKey ( uintptr_t  zoneKey) const
inlineoverridevirtual

Return true if ZoneProcessor is associated with the given opaque zoneKey.

This method should be considered to be private.

Parameters
zoneKeyan 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()

template<typename D >
FindResult ace_time::BasicZoneProcessorTemplate< D >::findByLocalDateTime ( const LocalDateTime ldt) const
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()

template<typename D >
void ace_time::BasicZoneProcessorTemplate< D >::printNameTo ( Print &  printer) const
inlineoverridevirtual

Print a human-readable identifier (e.g.

"America/Los_Angeles").

Parameters
printeran instance of the Print class, usually Serial

Implements ace_time::ZoneProcessor.

Definition at line 299 of file BasicZoneProcessor.h.

◆ printShortNameTo()

template<typename D >
void ace_time::BasicZoneProcessorTemplate< D >::printShortNameTo ( Print &  printer) const
inlineoverridevirtual

Print a short human-readable identifier (e.g.

"Los Angeles"). Any underscore in the short name is replaced with a space.

Parameters
printeran instance of the Print class, usually Serial

Implements ace_time::ZoneProcessor.

Definition at line 303 of file BasicZoneProcessor.h.

◆ printTargetNameTo()

template<typename D >
void ace_time::BasicZoneProcessorTemplate< D >::printTargetNameTo ( Print &  printer) const
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
printeran instance of the Print class, usually Serial

Implements ace_time::ZoneProcessor.

Definition at line 307 of file BasicZoneProcessor.h.

◆ setZoneInfoStore()

template<typename D >
void ace_time::BasicZoneProcessorTemplate< D >::setZoneInfoStore ( const typename D::ZoneInfoStore *  zoneInfoStore)
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()

template<typename D >
void ace_time::BasicZoneProcessorTemplate< D >::setZoneKey ( uintptr_t  zoneKey)
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
zoneKeyan 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: