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

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:
[legend]

## Public Member Functions
| TimeZone ()
| Default constructor creates a UTC TimeZone.
uint8_t | getType () const
| Return the type of TimeZone, used to determine the behavior of certain methods at runtime. More...
TimeOffset | getStdOffset () const
| Return the Standard TimeOffset. More...
TimeOffset | getDstOffset () const
| Return the DST TimeOffset. More...
bool | isLink () const
| Return true if timezone is a Link entry pointing to a Zone entry.
uint32_t | getZoneId () const
| Return the zoneId for kTypeBasic, kTypeExtended. More...
bool | isError () const
| Return true if TimeZone is an error.
ZonedExtra | getZonedExtra (const LocalDateTime &ldt) const
| Return the ZonedExtra information at epochSeconds.
ZonedExtra | getZonedExtra (acetime_t epochSeconds) const
| Return the ZonedExtra information at epochSeconds.
OffsetDateTime | getOffsetDateTime (const LocalDateTime &ldt) const
| Return the best estimate of the OffsetDateTime at the given LocalDateTime for the current TimeZone. More...
OffsetDateTime | getOffsetDateTime (acetime_t epochSeconds) const
| Return the best estimate of the OffsetDateTime at the given epochSeconds. More...
bool | isUtc () const
| Return true if UTC (+00:00+00:00).
bool | isDst () const
| Return if mDstOffsetMinutes is not zero. 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 text representation of the time zone using the full canonical time zone name or UTC offset shift. More...
void | printShortTo (Print &printer) const
| Print the short human readable representation of the time zone. More...
void | printTargetNameTo (Print &printer) const
| Print the name of the target zone if the current time zone is a Link. More...
| TimeZone (const TimeZone &)=default
TimeZone & | operator= (const TimeZone &)=default

## Static Public Member Functions
static TimeZone | forUtc ()
| Factory method to create a UTC TimeZone.
static TimeZone | forTimeOffset (TimeOffset stdOffset, TimeOffset dstOffset=TimeOffset())
| Factory method to create from a UTC offset and an optional DST offset. More...
static TimeZone | forHours (int8_t stdHours, int8_t dstHours=0)
| Factory method to create from UTC hour offset and optional DST hour offset. More...
static TimeZone | forMinutes (int16_t stdMinutes, int16_t dstMinutes=0)
| Factory method to create from UTC minute offset and optional DST minute offset. More...
static TimeZone | forHourMinute (int8_t stdHour, int8_t stdMinute, int8_t dstHour=0, int8_t dstMinute=0)
| Factory method to create from UTC (hour, minute) pair and optional DST (hour, minute) pair. More...
static TimeZone | forZoneInfo (const basic::ZoneInfo *zoneInfo, BasicZoneProcessor *zoneProcessor)
| Convenience factory method to create from a zoneInfo and an associated BasicZoneProcessor. More...
static TimeZone | forZoneInfo (const extended::ZoneInfo *zoneInfo, ExtendedZoneProcessor *zoneProcessor)
| Convenience factory method to create from a zoneInfo and an associated ExtendedZoneProcessor. More...
static TimeZone | forZoneInfo (const complete::ZoneInfo *zoneInfo, CompleteZoneProcessor *zoneProcessor)
| Convenience factory method to create from a zoneInfo and an associated ExtendedZoneProcessor. More...
static TimeZone | forZoneKey (uintptr_t zoneKey, ZoneProcessor *processor)
| Factory method to create from a generic zoneKey and a generic zoneProcessor. More...
static TimeZone | forError ()
| Return a TimeZone representing an error condition. More...

## Static Public Attributes
static const uint8_t | kTypeError = 0
| A TimeZone that represents an invalid condition.
static const uint8_t | kTypeManual = 1
| Manual STD offset and DST offset.
static const uint8_t | kTypeReserved = 2
| Reserved for future use.

## Friends
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.

The TimeZone::getType() is designed to be extensible, so only some of its values are defined by this class:

- TimeZone::kTypeError
  - represents an error or unknown time zone
- TimeZone::kTypeManual
  - holds a base offset and a DST offset, and allows the user to modify both of these fields
- TimeZone::kTypeReserved
  - reserved for future extension, currently same as kTypeError
- Additional values are provided by specific subclasses of the ZoneProcessor class. For example:
  - BasicZoneProcessor::kTypeBasic
    - uses the BasicZoneProcessor to support the zones and links defined by `zonedb/zone_infos.h`.
  - ExtendedZoneProcessor::kTypeExtended
    - uses the ExtendedZoneProcessor to support all zones and links defined by `zonedbx/zone_infos.h`
  - Other ZoneProcessors can provide additional values, as long as they are unique.

The TimeZone class is an immutable value type. It can be passed around by value, but since it is between 5 bytes (8-bit processors) and 12 bytes (32-bit processors) 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 86 of file TimeZone.h.

## Member Function Documentation

## ◆ forError()

static TimeZone ace_time::TimeZone::forError | ( |  | ) |
| inline static

Return a TimeZone representing an error condition.

isError() returns true for this instance.

Definition at line 241 of file TimeZone.h.

## ◆ forHourMinute()

static TimeZone ace_time::TimeZone::forHourMinute | ( | int8_t | stdHour,
|  | int8_t | stdMinute,
|  | int8_t | dstHour = `0`,
|  | int8_t | dstMinute = `0`
| ) |  |
| inline static

Factory method to create from UTC (hour, minute) pair and optional DST (hour, minute) pair.

This is a convenience alternative to `forTimeOffset(TimeOffset::forHour(stdHour), TimeOffset::forHour(stdHour))`.

Definition at line 154 of file TimeZone.h.

## ◆ forHours()

static TimeZone ace_time::TimeZone::forHours | ( | int8_t | stdHours,
|  | int8_t | dstHours = `0`
| ) |  |
| inline static

Factory method to create from UTC hour offset and optional DST hour offset.

This is a convenience alternative to `forTimeOffset(TimeOffset::forHours(stdHour), TimeOffset::forHours(stdHour))`.

Definition at line 128 of file TimeZone.h.

## ◆ forMinutes()

static TimeZone ace_time::TimeZone::forMinutes | ( | int16_t | stdMinutes,
|  | int16_t | dstMinutes = `0`
| ) |  |
| inline static

Factory method to create from UTC minute offset and optional DST minute offset.

This is a convenience alternative to `forTimeOffset(TimeOffset::forMinutes(stdMinutes), TimeOffset::forMinutes(dstMinutes))`.

Definition at line 141 of file TimeZone.h.

## ◆ forTimeOffset()

static TimeZone ace_time::TimeZone::forTimeOffset | ( | TimeOffset | stdOffset,
|  | TimeOffset | dstOffset = `TimeOffset()`
| ) |  |
| inline static

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

It may be easier to use the following convenience methods:

- TimeZone::forHours(stdHours, dstHours = 0)
- TimeZone::forMinutes(stdMinutes, dstMinutes = 0)
- TimeZone::forHourMinute(stdHour, stdMinute, dstHour = 0, dstMinute = 0)

This method may become deprecated in the future.

Parameters

  stdOffset | the base offset
  dstOffset | the DST offset, default TimeOffset() (i.e. 0 offset)

Definition at line 115 of file TimeZone.h.

## ◆ forZoneInfo() [1/3]

static TimeZone ace_time::TimeZone::forZoneInfo | ( | const basic::ZoneInfo * | zoneInfo,
|  | BasicZoneProcessor * | zoneProcessor
| ) |  |
| inline static

Convenience factory method to create from a zoneInfo and an associated BasicZoneProcessor.

The ZoneInfo previously associated with the given zoneProcessor is overridden.

Parameters

  zoneInfo | a basic::ZoneInfo that identifies the zone
  zoneProcessor | a pointer to a ZoneProcessor, cannot be nullptr

Definition at line 174 of file TimeZone.h.

## ◆ forZoneInfo() [2/3]

static TimeZone ace_time::TimeZone::forZoneInfo | ( | const complete::ZoneInfo * | zoneInfo,
|  | CompleteZoneProcessor * | zoneProcessor
| ) |  |
| inline static

Convenience factory method to create from a zoneInfo and an associated ExtendedZoneProcessor.

The ZoneInfo previously associated with the given zoneProcessor is overridden.

Parameters

  zoneInfo | an extended::ZoneInfo that identifies the zone
  zoneProcessor | a pointer to a ZoneProcessor, cannot be nullptr

Definition at line 212 of file TimeZone.h.

## ◆ forZoneInfo() [3/3]

static TimeZone ace_time::TimeZone::forZoneInfo | ( | const extended::ZoneInfo * | zoneInfo,
|  | ExtendedZoneProcessor * | zoneProcessor
| ) |  |
| inline static

Convenience factory method to create from a zoneInfo and an associated ExtendedZoneProcessor.

The ZoneInfo previously associated with the given zoneProcessor is overridden.

Parameters

  zoneInfo | an extended::ZoneInfo that identifies the zone
  zoneProcessor | a pointer to a ZoneProcessor, cannot be nullptr

Definition at line 193 of file TimeZone.h.

## ◆ forZoneKey()

static TimeZone ace_time::TimeZone::forZoneKey | ( | uintptr_t | zoneKey,
|  | ZoneProcessor * | processor
| ) |  |
| inline static

Factory method to create from a generic zoneKey and a generic zoneProcessor.

The 'type' of the TimeZone is extracted from ZoneProcessor::getType(). This is an internal method for use by ZoneProcessor and its implementation classes.

Parameters

  zoneKey | an opaque Zone primary key (e.g. const ZoneInfo*, or a uint16_t index into a database table of ZoneInfo records)
  processor | the ZoneProcessor instance bound to the TimeZone

Definition at line 233 of file TimeZone.h.

## ◆ getDstOffset()

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

Return the DST TimeOffset.

Valid only for kTypeManual.

Definition at line 266 of file TimeZone.h.

## ◆ getOffsetDateTime() [1/2]

OffsetDateTime ace_time::TimeZone::getOffsetDateTime | ( | acetime_t | epochSeconds | ) | const
| inline

Return the best estimate of the OffsetDateTime at the given epochSeconds.

Used by ZonedDateTime::forEpochSeconds(), so exposed publically for testing and debugging.

Definition at line 432 of file TimeZone.h.

## ◆ getOffsetDateTime() [2/2]

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 386 of file TimeZone.h.

## ◆ getStdOffset()

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

Return the Standard TimeOffset.

Valid only for kTypeManual.

Definition at line 261 of file TimeZone.h.

## ◆ getType()

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

Return the type of TimeZone, used to determine the behavior of certain methods at runtime.

The exact value returned by this method is designed to be extensible and is an internal implementation detail. It will probably not be stable across multiple versions of this library. For stable serialization, use the toTimeZoneData() method instead.

Definition at line 258 of file TimeZone.h.

## ◆ getZoneId()

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

Return the zoneId for kTypeBasic, kTypeExtended.

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 288 of file TimeZone.h.

## ◆ isDst()

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

Return if mDstOffsetMinutes 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 475 of file TimeZone.h.

## ◆ printShortTo()

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

Print the short human readable representation of the time zone.

This method uses some rough heuristics for determine the reasonable human readable form. For basic and extended time zones, the last component of the canonical zone name is printed, with the underscore character replaced with just a space, for example "Los Angeles". For manual time zones, it prints the total UTC offset with a (D) if the DST flag is active and an (S) if not, for example, "-08:00(S)".

If you need better control over how the time zone is displayed, you need to write that code yourself using the getType() and the getZoneId() identifiers.

- kTypeManual is printed as "+/-hh:mm(S|D)" depending on DST or STD flag (e.g. "-07:00(D)")
- kTypeBasic is printed as "{zoneShortName}" (e.g. "Los Angeles")
- kTypeExtended is printed as "{zoneShortName}" (e.g. "Los Angeles")

Definition at line 34 of file TimeZone.cpp.

## ◆ printTargetNameTo()

void ace_time::TimeZone::printTargetNameTo | ( | Print & | printer | ) | const

Print the name of the target zone if the current time zone is a Link.

Otherwise print nothing.

Definition at line 60 of file TimeZone.cpp.

## ◆ printTo()

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

Print the text representation of the time zone using the full canonical time zone name or UTC offset shift.

- 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.

## ◆ 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.

Both TimeZone::kTypeBasic and TimeZone::kTypeExtended are mapped to TimeZoneData::kTypeZoneId.

Definition at line 486 of file TimeZone.h.

## Member Data Documentation

## ◆ mZoneKey

uintptr_t ace_time::TimeZone::mZoneKey

An opaque zone key.

- For kTypeBasic, this is a (const basic::ZoneInfo*).
- For kTypeExtended, this is a (const extended::ZoneInfo*).

Internally, the TimeZone class does not care how this is implemented. The factory methods expose these types for the convenience of the end users.

Definition at line 624 of file TimeZone.h.

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

- /home/brian/src/AceTime/src/ace_time/TimeZone.h
- /home/brian/src/AceTime/src/ace_time/TimeZone.cpp