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

#include <ExtendedZoneProcessor.h>

Inheritance diagram for ace_time::ExtendedZoneProcessorTemplate< D >:

Collaboration diagram for ace_time::ExtendedZoneProcessorTemplate< D >:

Public Types
typedef extended::TransitionTemplate< D >	Transition
	Exposed only for testing purposes.

typedef extended::TransitionForSecondsTemplate< D >	TransitionForSeconds
	Exposed only for testing purposes.

typedef extended::TransitionForDateTimeTemplate< D >	TransitionForDateTime
	Exposed only for testing purposes.

typedef extended::MatchingEraTemplate< D >	MatchingEra
	Exposed only for testing purposes.

typedef extended::TransitionStorageTemplate< kMaxTransitions, D >	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 () const override
	Return the unique stable zoneId.

FindResult	findByLocalDateTime (const LocalDateTime &ldt) const override
	Return the search results at given LocalDateTime.

FindResult	findByEpochSeconds (acetime_t epochSeconds) const override

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	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	setZoneInfoStore (const typename D::ZoneInfoStore *zoneInfoStore)
	Set the zone info store 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 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...

Friends
class	::ExtendedZoneProcessorTest_compareEraToYearMonth

class	::ExtendedZoneProcessorTest_compareEraToYearMonth2

class	::ExtendedZoneProcessorTest_createMatchingEra

class	::ExtendedZoneProcessorTest_findMatches_simple

class	::ExtendedZoneProcessorTest_findMatches_named

class	::ExtendedZoneProcessorTest_findCandidateTransitions

class	::ExtendedZoneProcessorTest_createTransitionsFromNamedMatch

class	::ExtendedZoneProcessorTest_getTransitionTime

class	::ExtendedZoneProcessorTest_createTransitionForYear

class	::ExtendedZoneProcessorTest_calcInteriorYears

class	::ExtendedZoneProcessorTest_getMostRecentPriorYear

class	::ExtendedZoneProcessorTest_compareTransitionToMatchFuzzy

class	::ExtendedZoneProcessorTest_compareTransitionToMatch

class	::ExtendedZoneProcessorTest_processTransitionCompareStatus

class	::ExtendedZoneProcessorTest_fixTransitionTimes_generateStartUntilTimes

class	::ExtendedZoneProcessorTest_setZoneKey

class	::ExtendedTransitionValidation

class	::CompleteTransitionValidation

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::ExtendedZoneProcessorTemplate< D >

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::Info::ZoneInfo) 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 2100. 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

B	broker type

Definition at line 81 of file ExtendedZoneProcessor.h.

Constructor & Destructor Documentation

◆ ExtendedZoneProcessorTemplate()

template<typename D >

ace_time::ExtendedZoneProcessorTemplate< D >::ExtendedZoneProcessorTemplate	(	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

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

Member Function Documentation

◆ equalsZoneKey()

template<typename D >

bool ace_time::ExtendedZoneProcessorTemplate< 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

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

◆ findByEpochSeconds()

template<typename D >

FindResult ace_time::ExtendedZoneProcessorTemplate< D >::findByEpochSeconds ( acetime_t epochSeconds ) const

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

◆ getTransitionAllocSize()

template<typename D >

uint8_t ace_time::ExtendedZoneProcessorTemplate< D >::getTransitionAllocSize ( ) const

inline

Get the largest allocation size of TransitionStorage.

For debugging.

Definition at line 263 of file ExtendedZoneProcessor.h.

◆ initForEpochSeconds()

template<typename D >

bool ace_time::ExtendedZoneProcessorTemplate< D >::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 296 of file ExtendedZoneProcessor.h.

◆ initForYear()

template<typename D >

bool ace_time::ExtendedZoneProcessorTemplate< D >::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 306 of file ExtendedZoneProcessor.h.

◆ printNameTo()

template<typename D >

void ace_time::ExtendedZoneProcessorTemplate< D >::printNameTo ( Print & printer ) const

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

◆ printShortNameTo()

template<typename D >

void ace_time::ExtendedZoneProcessorTemplate< 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

printer an instance of the Print class, usually Serial

Implements ace_time::ZoneProcessor.

Definition at line 231 of file ExtendedZoneProcessor.h.

◆ printTargetNameTo()

template<typename D >

void ace_time::ExtendedZoneProcessorTemplate< 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

printer an instance of the Print class, usually Serial

Implements ace_time::ZoneProcessor.

Definition at line 235 of file ExtendedZoneProcessor.h.

◆ resetTransitionAllocSize()

template<typename D >

void ace_time::ExtendedZoneProcessorTemplate< D >::resetTransitionAllocSize ( )

inline

Reset the TransitionStorage high water mark.

For debugging.

Definition at line 258 of file ExtendedZoneProcessor.h.

◆ setZoneInfoStore()

template<typename D >

void ace_time::ExtendedZoneProcessorTemplate< 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 287 of file ExtendedZoneProcessor.h.

◆ setZoneKey()

template<typename D >

void ace_time::ExtendedZoneProcessorTemplate< 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

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

Member Data Documentation

◆ kMaxTransitions

template<typename D >

const uint8_t ace_time::ExtendedZoneProcessorTemplate< D >::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 various tests (e.g. HinnantExtendedTest, DateUtilExtendedTest, JavaExtendedTest, and AcetzExtendedTest) in the AceTimeValidation project. We set this to one more than 7 for safety.

Definition at line 94 of file ExtendedZoneProcessor.h.

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

/home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/ExtendedZoneProcessor.h

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

template<typename D> class ace_time::ExtendedZoneProcessorTemplate< D >

Constructor & Destructor Documentation

◆ ExtendedZoneProcessorTemplate()

Member Function Documentation

◆ equalsZoneKey()

◆ findByEpochSeconds()

◆ getTransitionAllocSize()

◆ initForEpochSeconds()

◆ initForYear()

◆ printNameTo()

◆ printShortNameTo()

◆ printTargetNameTo()

◆ resetTransitionAllocSize()

◆ setZoneInfoStore()

◆ setZoneKey()

Member Data Documentation

◆ kMaxTransitions

template<typename D>
class ace_time::ExtendedZoneProcessorTemplate< D >