AceTime  1.9.0
Date and time classes for Arduino that support timezones from the TZ Database.
Public Types | Public Member Functions | Static Public Attributes | Protected Member Functions | Friends | List of all members
ace_time::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB > Class Template Reference

An implementation of ZoneProcessor that supports for all zones defined by the TZ Database. More...

#include <ExtendedZoneProcessor.h>

Inheritance diagram for ace_time::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >:
Inheritance graph
[legend]
Collaboration diagram for ace_time::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >:
Collaboration graph
[legend]

Public Types

typedef extended::TransitionTemplate< ZEB, ZPB, ZRB > Transition
 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

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 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...
 
- Public Member Functions inherited from ace_time::ZoneProcessor
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...
 
- Protected Member Functions inherited from ace_time::ZoneProcessor
 ZoneProcessor (const ZoneProcessor &)=delete
 
ZoneProcessoroperator= (const ZoneProcessor &)=delete
 
 ZoneProcessor (uint8_t type)
 Constructor.
 

Friends

class ::ExtendedZoneProcessorTest_compareEraToYearMonth
 
class ::ExtendedZoneProcessorTest_compareEraToYearMonth2
 
class ::ExtendedZoneProcessorTest_createMatch
 
class ::ExtendedZoneProcessorTest_findMatches_simple
 
class ::ExtendedZoneProcessorTest_findMatches_named
 
class ::ExtendedZoneProcessorTest_findCandidateTransitions
 
class ::ExtendedZoneProcessorTest_createTransitionsFromNamedMatch
 
class ::ExtendedZoneProcessorTest_getTransitionTime
 
class ::ExtendedZoneProcessorTest_createTransitionForYear
 
class ::ExtendedZoneProcessorTest_normalizeDateTuple
 
class ::ExtendedZoneProcessorTest_expandDateTuple
 
class ::ExtendedZoneProcessorTest_calcInteriorYears
 
class ::ExtendedZoneProcessorTest_getMostRecentPriorYear
 
class ::ExtendedZoneProcessorTest_compareTransitionToMatchFuzzy
 
class ::ExtendedZoneProcessorTest_compareTransitionToMatch
 
class ::ExtendedZoneProcessorTest_processTransitionMatchStatus
 
class ::ExtendedZoneProcessorTest_fixTransitionTimes_generateStartUntilTimes
 
class ::ExtendedZoneProcessorTest_createAbbreviation
 
class ::ExtendedZoneProcessorTest_setZoneKey
 
class ::TransitionStorageTest_findTransitionForDateTime
 
class ::TransitionValidation
 

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::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >

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

  1. The AT and UNTIL transition times are stored using a 1-minute resolution, which correctly handles the 5 timezones whose DST transition times occur at 00:01. Those zones are:
    • America/Goose_Bay
    • America/Moncton
    • America/St_Johns
    • Asia/Gaza
    • Asia/Hebron

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 793 of file ExtendedZoneProcessor.h.

Constructor & Destructor Documentation

◆ ExtendedZoneProcessorTemplate()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
ace_time::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::ExtendedZoneProcessorTemplate ( 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 1048 of file ExtendedZoneProcessor.h.

Member Function Documentation

◆ equalsZoneKey()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
bool ace_time::ExtendedZoneProcessorTemplate< 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 942 of file ExtendedZoneProcessor.h.

◆ getAbbrev()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
const char* ace_time::ExtendedZoneProcessorTemplate< 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 836 of file ExtendedZoneProcessor.h.

◆ getDeltaOffset()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
TimeOffset ace_time::ExtendedZoneProcessorTemplate< 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 829 of file ExtendedZoneProcessor.h.

◆ getOffsetDateTime()

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

Implements ace_time::ZoneProcessor.

Definition at line 843 of file ExtendedZoneProcessor.h.

◆ getTransitionAllocSize()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
uint8_t ace_time::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::getTransitionAllocSize ( ) const
inline

Get the largest allocation size of TransitionStorage.

For debugging.

Definition at line 928 of file ExtendedZoneProcessor.h.

◆ getUtcOffset()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
TimeOffset ace_time::ExtendedZoneProcessorTemplate< 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 819 of file ExtendedZoneProcessor.h.

◆ initForEpochSeconds()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
bool ace_time::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::initForEpochSeconds ( acetime_t  epochSeconds) const
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 961 of file ExtendedZoneProcessor.h.

◆ initForYear()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
bool ace_time::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::initForYear ( int16_t  year) const
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 971 of file ExtendedZoneProcessor.h.

◆ printNameTo()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
void ace_time::ExtendedZoneProcessorTemplate< 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 901 of file ExtendedZoneProcessor.h.

◆ printShortNameTo()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
void ace_time::ExtendedZoneProcessorTemplate< 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 905 of file ExtendedZoneProcessor.h.

◆ resetTransitionAllocSize()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
void ace_time::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::resetTransitionAllocSize ( )
inline

Reset the TransitionStorage high water mark.

For debugging.

Definition at line 923 of file ExtendedZoneProcessor.h.

◆ setBrokerFactory()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
void ace_time::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::setBrokerFactory ( const BF *  brokerFactory)
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 952 of file ExtendedZoneProcessor.h.

◆ setZoneKey()

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
void ace_time::ExtendedZoneProcessorTemplate< 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 932 of file ExtendedZoneProcessor.h.

Member Data Documentation

◆ kMaxTransitions

template<typename BF , typename ZIB , typename ZEB , typename ZPB , typename ZRB >
const uint8_t ace_time::ExtendedZoneProcessorTemplate< BF, ZIB, ZEB, ZPB, ZRB >::kMaxTransitions = 8
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 805 of file ExtendedZoneProcessor.h.


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