AceTime 3.0.0 Date and time classes for Arduino that support timezones from the TZ Database.

Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
ace_time::ZoneProcessor Class Referenceabstract

Base interface for ZoneProcessor classes. More...

`#include <ZoneProcessor.h>`

Inheritance diagram for ace_time::ZoneProcessor:
[legend]

## Public Member Functions
uint8_t | getType () const
| Return the kTypeXxx of the current instance.
virtual bool | isLink () const =0
| Return true if timezone is a Link entry pointing to a Zone entry.
virtual uint32_t | getZoneId () const =0
| Return the unique stable zoneId.
virtual FindResult | findByLocalDateTime (const LocalDateTime &ldt) const =0
| Return the search results at given LocalDateTime.
virtual FindResult | findByEpochSeconds (acetime_t epochSeconds) const =0
| Return the search results at given epochSeconds.
virtual void | printNameTo (Print &printer) const =0
| Print a human-readable identifier (e.g. More...
virtual void | printShortNameTo (Print &printer) const =0
| Print a short human-readable identifier (e.g. More...
virtual void | printTargetNameTo (Print &printer) const =0
| Print the full identifier (e.g. More...
virtual void | setZoneKey (uintptr_t zoneKey)=0
| Set the opaque zoneKey of this object to a new value, reseting any internally cached information. More...
virtual bool | equalsZoneKey (uintptr_t zoneKey) const =0
| Return true if ZoneProcessor is associated with the given opaque zoneKey. More...

## Protected Member Functions
| 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...
virtual bool | equals (const ZoneProcessor &other) const =0
| Return true if equal.

## Protected Attributes
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...

## Friends
bool | operator== (const ZoneProcessor &a, const ZoneProcessor &b)

## Detailed Description

Base interface for ZoneProcessor classes.

There were 2 options for implmenting the various concrete implementations of ZoneProcessors:

1) Implement only a single getType() method to distinguish the different runtime types of the object. Then use this type information in the TimeZone class to downcast the ZoneProcessor pointer to the correct subclass, and call the correct methods.

2) Fully implement a polymorphic class hierarchy, lifting various common methods (e.g. findByLocalDateTime(), findByEpochSeconds()) into this interface as virtual methods, then add a virtual equals() method to implement the operator==().

The problem with Option 1 is that the code for both subclasses would be compiled into the program, even if the application used only one of the subclasses. Instead I use Option 2, using a fully polymorphic class hierarchy, adding 3-4 virtual methods. When a program uses only a single subclass, only that particular subclass is included into the program. Unfortunately, this comes at the cost of forcing programs to use the virtual dispatch at runtime for some of the often-used methods.

Definition at line 140 of file ZoneProcessor.h.

## Member Function Documentation

## ◆ equalsZoneKey()

virtual bool ace_time::ZoneProcessor::equalsZoneKey | ( | uintptr_t | zoneKey | ) | const
| pure 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)

Implemented in ace_time::ExtendedZoneProcessorTemplate< D >, ace_time::ExtendedZoneProcessorTemplate< complete::Info >, ace_time::ExtendedZoneProcessorTemplate< extended::Info >, ace_time::BasicZoneProcessorTemplate< D >, and ace_time::BasicZoneProcessorTemplate< basic::Info >.

## ◆ isFilled()

bool ace_time::ZoneProcessor::isFilled | ( | int16_t | year | ) | const
| inline protected

Check if the Transition cache is filled for the given year and current epochYear.

Checking the epoch year allows the cache to be automatically invalidated and regenerated if the epoch year is changed.

Definition at line 229 of file ZoneProcessor.h.

## ◆ printNameTo()

virtual void ace_time::ZoneProcessor::printNameTo | ( | Print & | printer | ) | const
| pure virtual

Print a human-readable identifier (e.g.

"America/Los_Angeles").

Parameters

  printer | an instance of the Print class, usually Serial

Implemented in ace_time::ExtendedZoneProcessorTemplate< D >, ace_time::ExtendedZoneProcessorTemplate< complete::Info >, ace_time::ExtendedZoneProcessorTemplate< extended::Info >, ace_time::BasicZoneProcessorTemplate< D >, and ace_time::BasicZoneProcessorTemplate< basic::Info >.

## ◆ printShortNameTo()

virtual void ace_time::ZoneProcessor::printShortNameTo | ( | Print & | printer | ) | const
| pure 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

Implemented in ace_time::ExtendedZoneProcessorTemplate< D >, ace_time::ExtendedZoneProcessorTemplate< complete::Info >, ace_time::ExtendedZoneProcessorTemplate< extended::Info >, ace_time::BasicZoneProcessorTemplate< D >, and ace_time::BasicZoneProcessorTemplate< basic::Info >.

## ◆ printTargetNameTo()

virtual void ace_time::ZoneProcessor::printTargetNameTo | ( | Print & | printer | ) | const
| pure 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

Implemented in ace_time::ExtendedZoneProcessorTemplate< D >, ace_time::ExtendedZoneProcessorTemplate< complete::Info >, ace_time::ExtendedZoneProcessorTemplate< extended::Info >, ace_time::BasicZoneProcessorTemplate< D >, and ace_time::BasicZoneProcessorTemplate< basic::Info >.

## ◆ setZoneKey()

virtual void ace_time::ZoneProcessor::setZoneKey | ( | uintptr_t | zoneKey | ) |
| pure 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)

Implemented in ace_time::ExtendedZoneProcessorTemplate< D >, ace_time::ExtendedZoneProcessorTemplate< complete::Info >, ace_time::ExtendedZoneProcessorTemplate< extended::Info >, ace_time::BasicZoneProcessorTemplate< D >, and ace_time::BasicZoneProcessorTemplate< basic::Info >.

## Member Data Documentation

## ◆ mEpochYear

int16_t ace_time::ZoneProcessor::mEpochYear = LocalDate::kInvalidYear
| mutable protected

Epoch year that was used to calculate the transitions in the current cache.

Set to LocalDate::kInvalidYear to indicate invalid cache.

Definition at line 255 of file ZoneProcessor.h.

## ◆ mType

uint8_t const ace_time::ZoneProcessor::mType
| protected

User-visible indicator of the subclass of ZoneProcessor, which implments a specific time-zone algorithm.

Three common ones are BasicZoneProcessor::kTypeBasic and ExtendedZoneProcessor::kTypeExtended.

Definition at line 243 of file ZoneProcessor.h.

## ◆ mYear

int16_t ace_time::ZoneProcessor::mYear = LocalDate::kInvalidYear
| mutable protected

Year that was used to calculate the transitions in the current cache.

Set to LocalDate::kInvalidYear to indicate invalid cache.

Definition at line 249 of file ZoneProcessor.h.

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

- /home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/ZoneProcessor.h