AceTime
1.11.6
Date and time classes for Arduino that support timezones from the TZ Database.
|
Class that describes a time zone. More...
#include <TimeZone.h>
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 (bool followLink=false) const |
Return the zoneId for kTypeBasic, kTypeExtended. More... | |
bool | isError () const |
Return true if TimeZone is an error. | |
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... | |
const char * | getAbbrev (acetime_t epochSeconds) const |
Return the time zone abbreviation at the given epochSeconds. More... | |
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... | |
void | setStdOffset (TimeOffset stdOffset) |
Sets the stdOffset of the TimeZone. More... | |
void | setDstOffset (TimeOffset dstOffset) |
Sets the dstOffset of the TimeZone. More... | |
TimeZoneData | toTimeZoneData (bool followLink=false) const |
Convert to a TimeZoneData object, which can be fed back into ZoneManager::createForTimeZoneData() to recreate the TimeZone. More... | |
void | printTo (Print &printer, bool followLink=false) 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, bool followLink=false) const |
Print the short human readable representation of the time zone. 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 (int8_t stdMinutes, int8_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 | 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) |
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:
zonedb/zone_infos.h
.zonedbx/zone_infos.h
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 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 85 of file TimeZone.h.
|
inlinestatic |
Return a TimeZone representing an error condition.
isError() returns true for this instance.
Definition at line 216 of file TimeZone.h.
|
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 153 of file TimeZone.h.
|
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 127 of file TimeZone.h.
|
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 140 of file TimeZone.h.
|
inlinestatic |
Factory method to create from a UTC offset and an optional DST offset.
It may be easier to use the following convenience methods:
This method may become deprecated in the future.
stdOffset | the base offset |
dstOffset | the DST offset, default TimeOffset() (i.e. 0 offset) |
Definition at line 114 of file TimeZone.h.
|
inlinestatic |
Convenience factory method to create from a zoneInfo and an associated BasicZoneProcessor.
The ZoneInfo previously associated with the given zoneProcessor is overridden.
zoneInfo | a basic::ZoneInfo that identifies the zone |
zoneProcessor | a pointer to a ZoneProcessor, cannot be nullptr |
Definition at line 173 of file TimeZone.h.
|
inlinestatic |
Convenience factory method to create from a zoneInfo and an associated ExtendedZoneProcessor.
The ZoneInfo previously associated with the given zoneProcessor is overridden.
zoneInfo | an extended::ZoneInfo that identifies the zone |
zoneProcessor | a pointer to a ZoneProcessor, cannot be nullptr |
Definition at line 192 of file TimeZone.h.
|
inlinestatic |
Factory method to create from a generic zoneKey and a generic zoneProcessor.
The 'type' of the TimeZone is extracted from ZoneProcessor::getType().
Definition at line 208 of file TimeZone.h.
|
inline |
Return the time zone abbreviation at the given epochSeconds.
The IANA spec (https://data.iana.org/time-zones/theory.html#abbreviations) says that abbreviations are limited to 6 characters. It is unclear if this spec is guaranteed to be followed. Client programs should handle abbreviations longer than 6 characters to be safe.
Warning: The returned pointer points to a char buffer that could get overriden by subsequent method calls to this object. The pointer must not be stored permanently, it should be used as soon as possible (e.g. printed out). If you need to store the abbreviation for a long period of time, copy it to anther char buffer.
Definition at line 337 of file TimeZone.h.
|
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 304 of file TimeZone.h.
|
inline |
|
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 386 of file TimeZone.h.
|
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 361 of file TimeZone.h.
|
inline |
Return the Standard TimeOffset.
Valid only for kTypeManual.
Definition at line 236 of file TimeZone.h.
|
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 233 of file TimeZone.h.
|
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.)
followLink | if true and the time zone is a Link, follow the link and return the id of the target Zone instead. If the zone is not a link, this flag is ignored. |
Definition at line 267 of file TimeZone.h.
|
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 419 of file TimeZone.h.
void ace_time::TimeZone::printShortTo | ( | Print & | printer, |
bool | followLink = false |
||
) | 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.
Definition at line 33 of file TimeZone.cpp.
void ace_time::TimeZone::printTo | ( | Print & | printer, |
bool | followLink = false |
||
) | const |
Print the text representation of the time zone using the full canonical time zone name or UTC offset shift.
Definition at line 11 of file TimeZone.cpp.
|
inline |
Sets the dstOffset of the TimeZone.
Works only for kTypeManual, does nothing for any other type of TimeZone.
Definition at line 437 of file TimeZone.h.
|
inline |
Sets the stdOffset of the TimeZone.
Works only for kTypeManual, does nothing for any other type of TimeZone.
Definition at line 428 of file TimeZone.h.
|
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 448 of file TimeZone.h.
uintptr_t ace_time::TimeZone::mZoneKey |
An opaque zone key.
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 571 of file TimeZone.h.