Class that describes a time zone. More...

#include <TimeZone.h>

Collaboration diagram for ace_time::TimeZone:

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::Info::ZoneInfo zoneInfo, BasicZoneProcessor zoneProcessor)
	Convenience factory method to create from a zoneInfo and an associated BasicZoneProcessor. More...

static TimeZone	forZoneInfo (const extended::Info::ZoneInfo zoneInfo, ExtendedZoneProcessor zoneProcessor)
	Convenience factory method to create from a zoneInfo and an associated ExtendedZoneProcessor. More...

static TimeZone	forZoneInfo (const complete::Info::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 ( )

inlinestatic

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`
	)

inlinestatic

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`
	)

inlinestatic

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`
	)

inlinestatic

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()`
	)

inlinestatic

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::Info::ZoneInfo *	zoneInfo,
		BasicZoneProcessor *	zoneProcessor
	)

inlinestatic

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::Info::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::Info::ZoneInfo *	zoneInfo,
		CompleteZoneProcessor *	zoneProcessor
	)

inlinestatic

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 complete::Info::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::Info::ZoneInfo *	zoneInfo,
		ExtendedZoneProcessor *	zoneProcessor
	)

inlinestatic

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::Info::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
	)

inlinestatic

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::Info::ZoneInfo*).
For kTypeExtended, this is a (const extended::Info::ZoneInfo*).
For kTypeComplete, this is a (const complete::Info::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 625 of file TimeZone.h.

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

/home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/TimeZone.h
/home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/TimeZone.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Function Documentation

◆ forError()

◆ forHourMinute()

◆ forHours()

◆ forMinutes()

◆ forTimeOffset()

◆ forZoneInfo() [1/3]

◆ forZoneInfo() [2/3]

◆ forZoneInfo() [3/3]

◆ forZoneKey()

◆ getDstOffset()

◆ getOffsetDateTime() [1/2]

◆ getOffsetDateTime() [2/2]

◆ getStdOffset()

◆ getType()

◆ getZoneId()

◆ isDst()

◆ printShortTo()

◆ printTargetNameTo()

◆ printTo()

◆ toTimeZoneData()

Member Data Documentation

◆ mZoneKey