AceTime  0.1
Date and time classes for Arduino that supports the TZ DAtabase, and a system clock synchronized from an NTP server or an RTC chip.
Public Member Functions | Friends | List of all members
ace_time::BasicZoneSpecifier Class Reference

An implementation of ZoneSpecifier that supports a subset of the zones containing in the TZ Database. More...

#include <BasicZoneSpecifier.h>

Inheritance diagram for ace_time::BasicZoneSpecifier:
Inheritance graph
[legend]
Collaboration diagram for ace_time::BasicZoneSpecifier:
Collaboration graph
[legend]

Public Member Functions

 BasicZoneSpecifier (const basic::ZoneInfo *zoneInfo)
 Constructor. More...
 
const basic::ZoneInfogetZoneInfo () const
 Return the underlying ZoneInfo. More...
 
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...
 
TimeOffset getUtcOffsetForDateTime (const LocalDateTime &ldt) const override
 Return the UTC offset matching the given the date/time components. More...
 
void printTo (Print &printer) const override
 Print a human-readable identifier. More...
 
void log () const
 Used only for debugging. More...
 
- Public Member Functions inherited from ace_time::ZoneSpecifier
uint8_t getType () const
 Return the kTypeXxx of the current instance. More...
 

Friends

class ::BasicZoneSpecifierTest_init_primitives
 
class ::BasicZoneSpecifierTest_init
 
class ::BasicZoneSpecifierTest_createAbbreviation
 
class ::BasicZoneSpecifierTest_calcStartDayOfMonth
 
class ::BasicZoneSpecifierTest_calcRuleOffsetCode
 
class ExtendedZoneSpecifier
 

Additional Inherited Members

- Static Public Attributes inherited from ace_time::ZoneSpecifier
static const uint8_t kTypeManual = 1
 Indicate ManualZoneSpecifier. More...
 
static const uint8_t kTypeBasic = 2
 Indicate BasicZoneSpecifier. More...
 
static const uint8_t kTypeExtended = 3
 Indicate ExtendedZoneSpecifier. More...
 
- Protected Member Functions inherited from ace_time::ZoneSpecifier
 ZoneSpecifier (const ZoneSpecifier &)=default
 
ZoneSpecifieroperator= (const ZoneSpecifier &)=default
 
 ZoneSpecifier (uint8_t type)
 Constructor. More...
 
- Protected Attributes inherited from ace_time::ZoneSpecifier
uint8_t mType
 

Detailed Description

An implementation of ZoneSpecifier 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 tools/transformer.py for the authoratative algorithm):

Even with these limitations, zonedb/zone_info.h shows that 231 out of a total of 359 zones are supported by BasicZoneSpecifier.

Not thread-safe.

Definition at line 140 of file BasicZoneSpecifier.h.

Constructor & Destructor Documentation

ace_time::BasicZoneSpecifier::BasicZoneSpecifier ( const basic::ZoneInfo zoneInfo)
inlineexplicit

Constructor.

Parameters
zoneInfopointer to a ZoneInfo. Must not be nullptr.

Definition at line 146 of file BasicZoneSpecifier.h.

Member Function Documentation

const char* ace_time::BasicZoneSpecifier::getAbbrev ( acetime_t  epochSeconds) const
inlineoverridevirtual

Return the time zone abbreviation at epochSeconds.

This is an experimental method that has not been tested thoroughly. Use with caution.

Implements ace_time::ZoneSpecifier.

Definition at line 166 of file BasicZoneSpecifier.h.

TimeOffset ace_time::BasicZoneSpecifier::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.

Implements ace_time::ZoneSpecifier.

Definition at line 159 of file BasicZoneSpecifier.h.

TimeOffset ace_time::BasicZoneSpecifier::getUtcOffset ( acetime_t  epochSeconds) const
inlineoverridevirtual

Return the total UTC offset at epochSeconds, including DST offset.

Implements ace_time::ZoneSpecifier.

Definition at line 153 of file BasicZoneSpecifier.h.

TimeOffset ace_time::BasicZoneSpecifier::getUtcOffsetForDateTime ( const LocalDateTime ldt) const
inlineoverridevirtual

Return the UTC offset matching the given the date/time components.

The Transitions calculated by BasicZoneSpecifier 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 BasicZoneSpecifier, but this means that the information needed to implement this method correctly does not exist.

The implementation of this method is therefore a hack. First pass, we extract the TimeOffset on Jan 1 of the year given by the localDateTime, and guess its epochSecond using that TimeOffset. Second pass, we use the epochSecond from the previous pass to calculate the next best guess of the actual TimeOffset. We return the second pass guess as the result.

Implements ace_time::ZoneSpecifier.

Definition at line 187 of file BasicZoneSpecifier.h.

const basic::ZoneInfo* ace_time::BasicZoneSpecifier::getZoneInfo ( ) const
inline

Return the underlying ZoneInfo.

Definition at line 151 of file BasicZoneSpecifier.h.

void ace_time::BasicZoneSpecifier::log ( ) const
inline

Used only for debugging.

Definition at line 205 of file BasicZoneSpecifier.h.

void ace_time::BasicZoneSpecifier::printTo ( Print &  printer) const
overridevirtual

Print a human-readable identifier.

Implements ace_time::ZoneSpecifier.

Definition at line 6 of file BasicZoneSpecifier.cpp.


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