AceTime  1.7.4
Date and time classes for Arduino that support timezones from the TZ Database, and a system clock that can synchronize from an NTP server or an RTC chip.
Public Types | Public Member Functions | Protected Member Functions | Friends | List of all members
ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB > 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< BF, ZIB, ZEB, ZPB, ZRB >:
Inheritance graph
[legend]
Collaboration diagram for ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >:
Collaboration graph
[legend]

Public Types

typedef basic::TransitionTemplate< ZIB, ZEB, ZPB, ZRB > Transition
 Exposed only for testing purposes.
 

Public Member Functions

uint32_t getZoneId () const override
 Return the unique stable zoneId.
 
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...
 
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 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)
 
- 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 BF *brokerFactory, 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.
 

Friends

class ::BasicZoneProcessorTest_priorYearOfRule
 
class ::BasicZoneProcessorTest_compareRulesBeforeYear
 
class ::BasicZoneProcessorTest_findLatestPriorRule
 
class ::BasicZoneProcessorTest_findZoneEra
 
class ::BasicZoneProcessorTest_init_primitives
 
class ::BasicZoneProcessorTest_init
 
class ::BasicZoneProcessorTest_setZoneKey
 
class ::BasicZoneProcessorTest_createAbbreviation
 
class ::BasicZoneProcessorTest_calcRuleOffsetMinutes
 

Additional Inherited Members

- Protected Attributes inherited from ace_time::ZoneProcessor
const uint8_t mType
 

Detailed Description

template<typename BF, typename ZIB, typename ZEB, typename ZPB, typename ZRB>
class ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >

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.

Template Parameters
BFtype 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
ZIBtype of ZoneInfoBroker
ZEBtype of ZoneEraBroker
ZPBtype of ZonePolicyBroker
ZRBtype of ZoneRuleBroker

Definition at line 202 of file BasicZoneProcessor.h.

Constructor & Destructor Documentation

◆ BasicZoneProcessorTemplate()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::BasicZoneProcessorTemplate ( uint8_t  type,
const BF *  brokerFactory,
uintptr_t  zoneKey 
)
inlineexplicitprotected

Constructor.

Parameters
brokerFactorypointer to a BrokerFactory that creates a ZIB
zoneKeyan opaque Zone primary key (e.g. const ZoneInfo*)

Definition at line 350 of file BasicZoneProcessor.h.

Member Function Documentation

◆ equalsZoneKey()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
bool ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::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.

Implements ace_time::ZoneProcessor.

Definition at line 318 of file BasicZoneProcessor.h.

◆ getAbbrev()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
const char* ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::getAbbrev ( acetime_t  epochSeconds) const
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 223 of file BasicZoneProcessor.h.

◆ getDeltaOffset()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
TimeOffset ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::getDeltaOffset ( acetime_t  epochSeconds) const
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 216 of file BasicZoneProcessor.h.

◆ getOffsetDateTime()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
OffsetDateTime ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::getOffsetDateTime ( const LocalDateTime ldt) const
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 257 of file BasicZoneProcessor.h.

◆ getUtcOffset()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
TimeOffset ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::getUtcOffset ( acetime_t  epochSeconds) const
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 209 of file BasicZoneProcessor.h.

◆ printNameTo()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
void ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::printNameTo ( Print &  printer) const
inlineoverridevirtual

Print a human-readable identifier (e.g.

"America/Los_Angeles").

Implements ace_time::ZoneProcessor.

Definition at line 301 of file BasicZoneProcessor.h.

◆ printShortNameTo()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
void ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::printShortNameTo ( Print &  printer) const
inlineoverridevirtual

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

"Los_Angeles")

Implements ace_time::ZoneProcessor.

Definition at line 305 of file BasicZoneProcessor.h.

◆ setZoneKey()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
void ace_time::BasicZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::setZoneKey ( uintptr_t  zoneKey)
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 ZoneProcessorCache should allocate enough ZoneProcessors to handle the usage pattern.

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 309 of file BasicZoneProcessor.h.


The documentation for this class was generated from the following file: