AceTime
0.1
Date and time classes for Arduino that supports the TZ DAtabase, and a system clock synchronized from an NTP server or an RTC chip.
|
Class that describes a time zone. More...
#include <TimeZone.h>
Public Member Functions | |
TimeZone () | |
Default constructor. More... | |
uint8_t | getType () const |
Return the type of TimeZone. More... | |
TimeOffset | getUtcOffset (acetime_t epochSeconds) const |
Return the total UTC offset at epochSeconds, including DST offset. More... | |
TimeOffset | getDeltaOffset (acetime_t epochSeconds) const |
Return the DST offset from standard UTC offset at epochSeconds. More... | |
TimeOffset | getUtcOffsetForDateTime (const LocalDateTime &ldt) const |
Return the best guess of the UTC offset at the given LocalDateTime for the current TimeZone. More... | |
void | printTo (Print &printer) const |
Print the 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... | |
bool | isDst () const |
Return the isDst() value of the underlying ManualZoneSpecifier. More... | |
void | isDst (bool dst) |
Sets the isDst() flag of the underlying ManualZoneSpecifier. More... | |
TimeZone (const TimeZone &)=default | |
TimeZone & | operator= (const TimeZone &)=default |
Static Public Member Functions | |
static TimeZone | forTimeOffset (TimeOffset offset=TimeOffset()) |
Factory method to create from a fixed UTC offset. More... | |
static TimeZone | forZoneSpecifier (const ZoneSpecifier *zoneSpecifier) |
Factory method to create from a ZoneSpecifier. More... | |
Static Public Attributes | |
static const uint8_t | kTypeFixed = 0 |
static const uint8_t | kTypeZoneSpecifier = 1 |
Friends | |
bool | operator== (const TimeZone &a, const TimeZone &b) |
Class that describes a time zone.
There are 2 types:
The TimeZone class really really wants to be a reference type. 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 pointer (or 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 ZoneSpecifier class. The ZoneSpecifier 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).
The TimeZone class becomes a thin wrapper around a ZoneSpecifier object (essentially acting like a smart pointer in some sense). It should be treated as a value type and passed around by value or by const reference.
An alternative implementation would use an inheritance hierarchy for the TimeZone, with 2 subclasses (ManualTimeZone and AutoTimeZone). However this means that the TimeZone object can no longer be passed around by value, and the ZonedDateTime is forced to hold on to the TimeZone object using a pointer. It then becomes very difficult to change the offset and DST fields of the ManualTimeZone. Using a single TimeZone class and implementing it as a value type simplifies a lot of code.
Definition at line 50 of file TimeZone.h.
|
inline |
Default constructor.
Definition at line 75 of file TimeZone.h.
|
inlinestatic |
Factory method to create from a fixed UTC offset.
offset | the fixed UTC offset, default 00:00 offset |
Definition at line 60 of file TimeZone.h.
|
inlinestatic |
Factory method to create from a ZoneSpecifier.
zoneSpecifier | an instance of ManualZoneSpecifier, BasicZoneSpecifier, or ExtendedZoneSpecifier. Cannot be nullptr. |
Definition at line 70 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 94 of file TimeZone.h.
|
inline |
Return the type of TimeZone.
Definition at line 80 of file TimeZone.h.
|
inline |
Return the total UTC offset at epochSeconds, including DST offset.
Definition at line 83 of file TimeZone.h.
|
inline |
Return the best guess of the UTC offset 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 105 of file TimeZone.h.
|
inline |
Return the isDst() value of the underlying ManualZoneSpecifier.
This is a convenience method that is valid only if the TimeZone was constructed using a ManualZoneSpecifier. 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 125 of file TimeZone.h.
|
inline |
Sets the isDst() flag of the underlying ManualZoneSpecifier.
Does nothing for any other type of TimeZone. This is a convenience method for applications that allow the user to set the DST flag manually (e.g. examples/WorldClock).
Definition at line 137 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 21 of file TimeZone.cpp.
void ace_time::TimeZone::printTo | ( | Print & | printer | ) | const |
Print the human readable representation of the time zone.
Definition at line 7 of file TimeZone.cpp.
TimeOffset ace_time::TimeZone::mOffset |
Used if mType == mTypeFixed.
Definition at line 178 of file TimeZone.h.
const ZoneSpecifier* ace_time::TimeZone::mZoneSpecifier |
Used if mType == mTypeZoneSpecifier.
Definition at line 181 of file TimeZone.h.