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.
|
Class that describes a time zone. More...
#include <TimeZone.h>
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 | |
TimeZone & | operator= (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... | |
Friends | |
template<typename ZI , typename ZR , typename ZSC > | |
class | ZoneManager |
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.
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.
|
inline |
Default constructor creates a UTC TimeZone.
Definition at line 144 of file TimeZone.h.
|
inlinestatic |
Return a TimeZone representing an error condition.
isError() returns true for this instance.
Definition at line 139 of file TimeZone.h.
|
inlinestatic |
Factory method to create from a UTC offset and an optional DST offset.
stdOffset | the base offset |
dstOffset | the DST offset, default TimeOffset() (i.e. 0 offset) |
Definition at line 104 of file TimeZone.h.
|
inlinestatic |
Factory method to create a UTC TimeZone.
Definition at line 94 of file TimeZone.h.
|
inlinestatic |
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 117 of file TimeZone.h.
|
inlinestatic |
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 130 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 216 of file TimeZone.h.
|
inline |
|
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.
|
inline |
Return the Standard TimeOffset.
Valid only for kTypeManual.
Definition at line 156 of file TimeZone.h.
|
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.
|
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.
|
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.
|
inline |
Return true if TimeZone is an error.
Definition at line 186 of file TimeZone.h.
|
inline |
Return true if UTC (+00:00+00:00).
Definition at line 268 of file TimeZone.h.
void ace_time::TimeZone::printAbbrevTo | ( | Print & | printer, |
acetime_t | epochSeconds | ||
) | const |
Print the time zone abbreviation for the given epochSeconds.
Definition at line 70 of file TimeZone.cpp.
void ace_time::TimeZone::printShortTo | ( | Print & | printer | ) | const |
Print the short human readable representation of the time zone.
Definition at line 39 of file TimeZone.cpp.
void ace_time::TimeZone::printTo | ( | Print & | printer | ) | const |
Print the human readable representation of the time zone.
Definition at line 12 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 298 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 289 of file TimeZone.h.
|
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.
|
static |
Definition at line 88 of file TimeZone.h.
|
static |
Definition at line 90 of file TimeZone.h.
ZoneProcessor* ace_time::TimeZone::mZoneProcessor |
Used by kTypeBasic, kTypeExtended.
Definition at line 425 of file TimeZone.h.
ZoneProcessorCache* ace_time::TimeZone::mZoneProcessorCache |
Used by kTypeBasicManaged, kTypeExtendedManaged.
Definition at line 428 of file TimeZone.h.