AceTime  0.5
Date and time classes for Arduino that support timezones from the TZ Database, and a system clock that can synchronize from an NTP server or an RTC chip.
Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends | List of all members
ace_time::TimeZone Class Reference

Class that describes a time zone. More...

#include <TimeZone.h>

Collaboration diagram for ace_time::TimeZone:
Collaboration graph
[legend]

Public Member Functions

 TimeZone ()
 Default constructor creates a UTC TimeZone. More...
 
uint8_t getType () const
 Return the type of TimeZone. More...
 
TimeOffset getStdOffset () const
 Return the Standard TimeOffset. More...
 
TimeOffset getDstOffset () const
 Return the DST TimeOffset. More...
 
uint32_t getZoneId () const
 Return the zoneId for kTypeBasic, kTypeExtended, kTypeBasicManaged, kTypeExtendedManaged. More...
 
bool isError () const
 Return true if TimeZone is an error. More...
 
TimeOffset getUtcOffset (acetime_t epochSeconds) const
 Return the total UTC offset at epochSeconds, including DST offset.
 
TimeOffset getDeltaOffset (acetime_t epochSeconds) const
 Return the DST offset from standard UTC offset at epochSeconds. More...
 
OffsetDateTime getOffsetDateTime (const LocalDateTime &ldt) const
 Return the best estimate of the OffsetDateTime at the given LocalDateTime for the current TimeZone. More...
 
bool isUtc () const
 Return true if UTC (+00:00+00:00). More...
 
bool isDst () const
 Return if mDstOffsetCode is not zero. More...
 
void setStdOffset (TimeOffset stdOffset)
 Sets the stdOffset of the TimeZone. More...
 
void setDstOffset (TimeOffset dstOffset)
 Sets the dstOffset of the TimeZone. More...
 
TimeZoneData toTimeZoneData () const
 Convert to a TimeZoneData object, which can be fed back into ZoneManager::createForTimeZoneData() to recreate the TimeZone. More...
 
void printTo (Print &printer) const
 Print the human readable representation of the time zone. More...
 
void printShortTo (Print &printer) const
 Print the short human readable representation of the time zone. More...
 
void printAbbrevTo (Print &printer, acetime_t epochSeconds) const
 Print the time zone abbreviation for the given epochSeconds. More...
 
 TimeZone (const TimeZone &)=default
 
TimeZoneoperator= (const TimeZone &)=default
 

Static Public Member Functions

static TimeZone forUtc ()
 Factory method to create a UTC TimeZone. More...
 
static TimeZone forTimeOffset (TimeOffset stdOffset, TimeOffset dstOffset=TimeOffset())
 Factory method to create from a UTC offset and an optional DST offset. More...
 
static TimeZone forZoneInfo (const basic::ZoneInfo *zoneInfo, BasicZoneProcessor *zoneProcessor)
 Factory method to create from a zoneInfo and an associated BasicZoneProcessor. More...
 
static TimeZone forZoneInfo (const extended::ZoneInfo *zoneInfo, ExtendedZoneProcessor *zoneProcessor)
 Factory method to create from a zoneInfo and an associated ExtendedZoneProcessor. More...
 
static TimeZone forError ()
 Return a TimeZone representing an error condition. More...
 

Static Public Attributes

static const uint8_t kTypeError = 0
 
static const uint8_t kTypeManual = 1
 
static const uint8_t kTypeBasic = ZoneProcessor::kTypeBasic
 
static const uint8_t kTypeExtended = ZoneProcessor::kTypeExtended
 
static const uint8_t kTypeBasicManaged
 
static const uint8_t kTypeExtendedManaged
 

Friends

template<typename ZI , typename ZR , typename ZSC >
class ZoneManager
 
bool operator== (const TimeZone &a, const TimeZone &b)
 

Detailed Description

Class that describes a time zone.

There are 2 colloquial usages of "time zone". The first refers to a simple fixed offset from UTC. For example, we may say that "we are in -05:00 time zone". The second is a geographical region that obeys a consistent set of rules regarding the value of the UTC offset, and when the transitions to DST happens (if at all). The best known source of these geographical regions is the TZ Database maintained by IANA (https://www.iana.org/time-zones). The TimeZone class supports both meanings.

There are 6 types of TimeZone:

The TimeZone class should be treated as a const value type. (Except for kTypeManual which is self-contained and allows the stdOffset and dstOffset to be modified.) It can be passed around by value, but since it is between 5 bytes (8-bit) and 24 bytes (32-bit) big, it may be slightly more efficient to pass by const reference, then save locally by-value when needed. The ZonedDateTime holds the TimeZone object by-value.

Semantically, TimeZone really really wants to be a reference type because it needs have a reference to the ZoneProcessor helper class to do its work. In other words, it would be very convenient if the client code could create this object on the heap, and pass it around using a smart pointer to the ZonedDateTime class and shared among multiple ZonedDateTime objects. This would also allow new TimeZones to be created, while allowing older instances of ZonedDateTime to hold on to the previous versions of TimeZone.

However, in a small memory embedded environment (like Arduino Nano or Micro with only 2kB of RAM), I want to avoid any use of the heap (new operator or malloc()) inside the AceTime library. I separated out the memory intensive or mutable features of the TimeZone class into the separate ZoneProcessor class. The ZoneProcessor object should be created once at initialization time of the application (either statically allocated or potentially on the heap early in the application start up).

An alternative implementation would use an inheritance hierarchy for the TimeZone with subclasses like ManualTimeZone, BasicTimeZone and ExtendedTimeZone. However since different subclasses are of different sizes, the TimeZone object can no longer be passed around by-value, so the ZonedDateTime is forced to hold on to the TimeZone object using a pointer. Then we are forced to deal with difficult memory management and life cycle problems. Using a single TimeZone class and implementing it as a value type simplifies a lot of code.

The object can be serialized using the TimeZone::toTimeZoneData() method, and reconstructed using the ZoneManager::createForTimeZoneData() method.

Definition at line 82 of file TimeZone.h.

Constructor & Destructor Documentation

◆ TimeZone()

ace_time::TimeZone::TimeZone ( )
inline

Default constructor creates a UTC TimeZone.

Definition at line 144 of file TimeZone.h.

Member Function Documentation

◆ forError()

static TimeZone ace_time::TimeZone::forError ( )
inlinestatic

Return a TimeZone representing an error condition.

isError() returns true for this instance.

Definition at line 139 of file TimeZone.h.

◆ forTimeOffset()

static TimeZone ace_time::TimeZone::forTimeOffset ( TimeOffset  stdOffset,
TimeOffset  dstOffset = TimeOffset() 
)
inlinestatic

Factory method to create from a UTC offset and an optional DST offset.

Parameters
stdOffsetthe base offset
dstOffsetthe DST offset, default TimeOffset() (i.e. 0 offset)

Definition at line 104 of file TimeZone.h.

◆ forUtc()

static TimeZone ace_time::TimeZone::forUtc ( )
inlinestatic

Factory method to create a UTC TimeZone.

Definition at line 94 of file TimeZone.h.

◆ forZoneInfo() [1/2]

static TimeZone ace_time::TimeZone::forZoneInfo ( const basic::ZoneInfo zoneInfo,
BasicZoneProcessor zoneProcessor 
)
inlinestatic

Factory method to create from a zoneInfo and an associated BasicZoneProcessor.

The ZoneInfo previously associated with the given zoneProcessor is overridden.

Parameters
zoneInfoa basic::ZoneInfo that identifies the zone
zoneProcessora pointer to a ZoneProcessor, cannot be nullptr

Definition at line 117 of file TimeZone.h.

◆ forZoneInfo() [2/2]

static TimeZone ace_time::TimeZone::forZoneInfo ( const extended::ZoneInfo zoneInfo,
ExtendedZoneProcessor zoneProcessor 
)
inlinestatic

Factory method to create from a zoneInfo and an associated ExtendedZoneProcessor.

The ZoneInfo previously associated with the given zoneProcessor is overridden.

Parameters
zoneInfoan extended::ZoneInfo that identifies the zone
zoneProcessora pointer to a ZoneProcessor, cannot be nullptr

Definition at line 130 of file TimeZone.h.

◆ getDeltaOffset()

TimeOffset ace_time::TimeZone::getDeltaOffset ( acetime_t  epochSeconds) const
inline

Return the DST offset from standard UTC offset at epochSeconds.

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

Definition at line 216 of file TimeZone.h.

◆ getDstOffset()

TimeOffset ace_time::TimeZone::getDstOffset ( ) const
inline

Return the DST TimeOffset.

Valid only for kTypeManual.

Definition at line 161 of file TimeZone.h.

◆ getOffsetDateTime()

OffsetDateTime ace_time::TimeZone::getOffsetDateTime ( const LocalDateTime ldt) const
inline

Return the best estimate of the OffsetDateTime at the given LocalDateTime for the current TimeZone.

Used by ZonedDateTime::forComponents(), so intended to be used mostly for testing and debugging.

Definition at line 242 of file TimeZone.h.

◆ getStdOffset()

TimeOffset ace_time::TimeZone::getStdOffset ( ) const
inline

Return the Standard TimeOffset.

Valid only for kTypeManual.

Definition at line 156 of file TimeZone.h.

◆ getType()

uint8_t ace_time::TimeZone::getType ( ) const
inline

Return the type of TimeZone.

This value is useful for serializing and deserializing (or storing and restoring) the TimeZone object.

Definition at line 153 of file TimeZone.h.

◆ getZoneId()

uint32_t ace_time::TimeZone::getZoneId ( ) const
inline

Return the zoneId for kTypeBasic, kTypeExtended, kTypeBasicManaged, kTypeExtendedManaged.

Returns 0 for kTypeManual. (It is not entirely clear that a valid zoneId is always > 0, but there is little I can do without C++ exceptions.)

Definition at line 171 of file TimeZone.h.

◆ isDst()

bool ace_time::TimeZone::isDst ( ) const
inline

Return if mDstOffsetCode is not zero.

This is a convenience method that is valid only if the TimeZone is a kTypeManual. Returns false for all other type of TimeZone. This is intended to be used by applications which allows the user to set the UTC offset and DST flag manually (e.g. examples/WorldClock.ino).

Definition at line 280 of file TimeZone.h.

◆ isError()

bool ace_time::TimeZone::isError ( ) const
inline

Return true if TimeZone is an error.

Definition at line 186 of file TimeZone.h.

◆ isUtc()

bool ace_time::TimeZone::isUtc ( ) const
inline

Return true if UTC (+00:00+00:00).

Definition at line 268 of file TimeZone.h.

◆ printAbbrevTo()

void ace_time::TimeZone::printAbbrevTo ( Print &  printer,
acetime_t  epochSeconds 
) const

Print the time zone abbreviation for the given epochSeconds.

  • kTypeManual is printed as "STD" or "DST"
  • kTypeBasic is printed as "{abbrev}" (e.g. "PDT")
  • kTypeExtended is printed as "{abbrev}" (e.g. "PDT")

Definition at line 70 of file TimeZone.cpp.

◆ printShortTo()

void ace_time::TimeZone::printShortTo ( Print &  printer) const

Print the short human readable representation of the time zone.

  • kTypeManual is printed as "+/-hh:mm(STD|DST)" (e.g. "-07:00(DST)")
  • kTypeBasic is printed as "{zoneShortName}" (e.g. "Los_Angeles")
  • kTypeExtended is printed as "{zoneShortName}" (e.g. "Los_Angeles")

Definition at line 39 of file TimeZone.cpp.

◆ printTo()

void ace_time::TimeZone::printTo ( Print &  printer) const

Print the human readable representation of the time zone.

  • kTypeManual is printed as "+/-hh:mm+/-hh:mm" (e.g. "-08:00+00:00")
  • kTypeBasic is printed as "{zonename}" (e.g. "America/Los_Angeles")
  • kTypeExtended is printed as "{zonename}" (e.g. "America/Los_Angeles")

Definition at line 12 of file TimeZone.cpp.

◆ setDstOffset()

void ace_time::TimeZone::setDstOffset ( TimeOffset  dstOffset)
inline

Sets the dstOffset of the TimeZone.

Works only for kTypeManual, does nothing for any other type of TimeZone.

Definition at line 298 of file TimeZone.h.

◆ setStdOffset()

void ace_time::TimeZone::setStdOffset ( TimeOffset  stdOffset)
inline

Sets the stdOffset of the TimeZone.

Works only for kTypeManual, does nothing for any other type of TimeZone.

Definition at line 289 of file TimeZone.h.

◆ toTimeZoneData()

TimeZoneData ace_time::TimeZone::toTimeZoneData ( ) const
inline

Convert to a TimeZoneData object, which can be fed back into ZoneManager::createForTimeZoneData() to recreate the TimeZone.

All of TimeZone::kTypeBasic, kTypeExtended, kTypeBasicManaged, kTypeExtendedManaged collapse into TimeZoneData::kTypeZoneId.

Definition at line 309 of file TimeZone.h.

Member Data Documentation

◆ kTypeBasicManaged

const uint8_t ace_time::TimeZone::kTypeBasicManaged
static
Initial value:
=
ZoneProcessorCache::kTypeBasicManaged

Definition at line 88 of file TimeZone.h.

◆ kTypeExtendedManaged

const uint8_t ace_time::TimeZone::kTypeExtendedManaged
static
Initial value:
=
ZoneProcessorCache::kTypeExtendedManaged

Definition at line 90 of file TimeZone.h.

◆ mZoneProcessor

ZoneProcessor* ace_time::TimeZone::mZoneProcessor

Used by kTypeBasic, kTypeExtended.

Definition at line 425 of file TimeZone.h.

◆ mZoneProcessorCache

ZoneProcessorCache* ace_time::TimeZone::mZoneProcessorCache

Used by kTypeBasicManaged, kTypeExtendedManaged.

Definition at line 428 of file TimeZone.h.


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