AceTime 2.4.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< ZIS, 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< ZIS, ZIB, ZEB, ZPB, ZRB >:
[legend]
Collaboration diagram for ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >:
[legend]

## Public Types
typedef extended::TransitionTemplate< ZEB, ZPB, ZRB > | Transition
| Exposed only for testing purposes.
typedef extended::TransitionForSecondsTemplate< ZEB, ZPB, ZRB > | TransitionForSeconds
| Exposed only for testing purposes.
typedef extended::TransitionForDateTimeTemplate< ZEB, ZPB, ZRB > | TransitionForDateTime
| 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 () 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 ZIS *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 ZIS *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 ZIS, typename ZIB, typename ZEB, typename ZPB, typename ZRB>
class ace_time::ExtendedZoneProcessorTemplate< ZIS, 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

  ZIS | type of ZoneInfoStore, 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 88 of file ExtendedZoneProcessor.h.

## Constructor & Destructor Documentation

## ◆ ExtendedZoneProcessorTemplate()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >::ExtendedZoneProcessorTemplate | ( | uint8_t | type,
|  | const ZIS * | zoneInfoStore,
|  | uintptr_t | zoneKey
| ) |  |
| inline explicit protected

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

## Member Function Documentation

## ◆ equalsZoneKey()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

bool ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >::equalsZoneKey | ( | uintptr_t | zoneKey | ) | const
| inline override virtual

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

## ◆ findByEpochSeconds()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

FindResult ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >::findByEpochSeconds | ( | acetime_t | epochSeconds | ) | const
| inline override virtual

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

## ◆ getTransitionAllocSize()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

uint8_t ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >::getTransitionAllocSize | ( |  | ) | const
| inline

Get the largest allocation size of TransitionStorage.

For debugging.

Definition at line 270 of file ExtendedZoneProcessor.h.

## ◆ initForEpochSeconds()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

bool ace_time::ExtendedZoneProcessorTemplate< ZIS, 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 303 of file ExtendedZoneProcessor.h.

## ◆ initForYear()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

bool ace_time::ExtendedZoneProcessorTemplate< ZIS, 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 313 of file ExtendedZoneProcessor.h.

## ◆ printNameTo()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

void ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >::printNameTo | ( | Print & | printer | ) | const
| inline override virtual

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

## ◆ printShortNameTo()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

void ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >::printShortNameTo | ( | Print & | printer | ) | const
| inline override virtual

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

## ◆ printTargetNameTo()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

void ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >::printTargetNameTo | ( | Print & | printer | ) | const
| inline override virtual

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

## ◆ resetTransitionAllocSize()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

void ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >::resetTransitionAllocSize | ( |  | ) |
| inline

Reset the TransitionStorage high water mark.

For debugging.

Definition at line 265 of file ExtendedZoneProcessor.h.

## ◆ setZoneInfoStore()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

void ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >::setZoneInfoStore | ( | const ZIS * | 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 294 of file ExtendedZoneProcessor.h.

## ◆ setZoneKey()

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

void ace_time::ExtendedZoneProcessorTemplate< ZIS, ZIB, ZEB, ZPB, ZRB >::setZoneKey | ( | uintptr_t | zoneKey | ) |
| inline override virtual

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

## Member Data Documentation

## ◆ kMaxTransitions

template<typename ZIS , typename ZIB , typename ZEB , typename ZPB , typename ZRB >

const uint8_t ace_time::ExtendedZoneProcessorTemplate< ZIS, 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 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 101 of file ExtendedZoneProcessor.h.

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

- /home/brian/src/AceTime/src/ace_time/ExtendedZoneProcessor.h