AceTime
1.2
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.
|
The date (year, month, day), time (hour, minute, second), and a timeZone representing an instant in time. More...
#include <ZonedDateTime.h>
Public Member Functions | |
ZonedDateTime () | |
Default constructor. | |
bool | isError () const |
Return true if any component indicates an error condition. | |
int16_t | year () const |
Return the year. | |
void | year (int16_t year) |
Set the year given the full year. | |
int8_t | yearTiny () const |
Return the single-byte year offset from year 2000. More... | |
void | yearTiny (int8_t yearTiny) |
Set the single-byte year offset from year 2000. More... | |
uint8_t | month () const |
Return the month with January=1, December=12. | |
void | month (uint8_t month) |
Set the month. | |
uint8_t | day () const |
Return the day of the month. | |
void | day (uint8_t day) |
Set the day of the month. | |
uint8_t | hour () const |
Return the hour. | |
void | hour (uint8_t hour) |
Set the hour. | |
uint8_t | minute () const |
Return the minute. | |
void | minute (uint8_t minute) |
Set the minute. | |
uint8_t | second () const |
Return the second. | |
void | second (uint8_t second) |
Set the second. | |
uint8_t | dayOfWeek () const |
Return the day of the week using ISO 8601 numbering where Monday=1 and Sunday=7. | |
TimeOffset | timeOffset () const |
Return the offset zone of the OffsetDateTime. | |
const TimeZone & | timeZone () const |
Return the time zone of the ZonedDateTime. | |
void | timeZone (const TimeZone &timeZone) |
Set the time zone. More... | |
const LocalDateTime & | localDateTime () const |
Return the LocalDateTime of the components. | |
ZonedDateTime | convertToTimeZone (const TimeZone &timeZone) const |
Create a ZonedDateTime in a different time zone (with the same epochSeconds). | |
acetime_t | toEpochDays () const |
Return number of whole days since AceTime epoch (2000-01-01 00:00:00Z), taking into account the time zone. | |
acetime_t | toUnixDays () const |
Return the number of days since Unix epoch (1970-01-01 00:00:00). | |
acetime_t | toEpochSeconds () const |
Return seconds since AceTime epoch (2000-01-01 00:00:00Z), taking into account the time zone. More... | |
acetime_t | toUnixSeconds () const |
Return the number of seconds from Unix epoch 1970-01-01 00:00:00Z. More... | |
int8_t | compareTo (const ZonedDateTime &that) const |
Compare this ZonedDateTime with another ZonedDateTime, and return (<0, 0, >0) according to whether the epochSeconds is (a<b, a==b, a>b). More... | |
void | printTo (Print &printer) const |
Print ZonedDateTime to 'printer'. More... | |
ZonedDateTime (const ZonedDateTime &)=default | |
ZonedDateTime & | operator= (const ZonedDateTime &)=default |
Static Public Member Functions | |
static ZonedDateTime | forComponents (int16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second, const TimeZone &timeZone) |
Factory method using separated date, time, and time zone fields. More... | |
static ZonedDateTime | forEpochSeconds (acetime_t epochSeconds, const TimeZone &timeZone) |
Factory method. More... | |
static ZonedDateTime | forUnixSeconds (acetime_t unixSeconds, const TimeZone &timeZone) |
Factory method to create a ZonedDateTime using the number of seconds from Unix epoch. More... | |
static ZonedDateTime | forDateString (const char *dateString) |
Factory method. More... | |
static ZonedDateTime | forDateString (const __FlashStringHelper *dateString) |
Factory method. More... | |
static ZonedDateTime | forError () |
Return an instance whose isError() returns true. | |
Friends | |
bool | operator== (const ZonedDateTime &a, const ZonedDateTime &b) |
Return true if two ZonedDateTime objects are equal in all components. More... | |
The date (year, month, day), time (hour, minute, second), and a timeZone representing an instant in time.
The year field is internally represented as an int8_t number from -128 to 127. The value of -128 is used to indicate an error condition so that range of valid year is 1873 to 2127 inclusive.
The "epoch" for this library is 2000-01-01 00:00:00Z. The dayOfWeek (1=Sunday, 7=Saturday) is calculated internally from the date components. Changing the timeZone does not affect the dayOfWeek.
Some parts of this class were inspired by the org.joda.DateTime of http://www.joda.org and java.time.ZonedDateTime of Java 11.
Definition at line 32 of file ZonedDateTime.h.
|
inline |
Compare this ZonedDateTime with another ZonedDateTime, and return (<0, 0, >0) according to whether the epochSeconds is (a<b, a==b, a>b).
The dayOfWeek field is ignored. This method can return 0 (equal) even if the operator==() returns false if the two ZonedDateTime objects are in different time zones.
Definition at line 264 of file ZonedDateTime.h.
|
inlinestatic |
Factory method using separated date, time, and time zone fields.
This is intended mostly for testing purposes. Most production code will use the forEpochSeconds() method.
The TimeOffset at the given date/time component is calculated using the ZoneProcessor::getUtcOffsetForDateTime() determined by the actual subtype of ZoneProcessor held by the given timeZone.
year | [1873-2127] |
month | month with January=1, December=12 |
day | day of month [1-31] |
hour | hour [0-23] |
minute | minute [0-59] |
second | second [0-59], does not support leap seconds |
timeZone | a TimeZone instance (use TimeZone() for UTC) |
Definition at line 51 of file ZonedDateTime.h.
|
inlinestatic |
Factory method.
Create a ZonedDateTime from date string in flash memory F() strings. Mostly for unit testing.
Definition at line 122 of file ZonedDateTime.h.
|
inlinestatic |
Factory method.
Create a ZonedDateTime from the ISO 8601 date string. If the string cannot be parsed, then isError() on the constructed object returns true.
dateString | a string in ISO 8601 format "YYYY-MM-DDThh:mm:ss+hh:mm". The parser is very lenient and does not detect most errors. It cares mostly about the positional placement of the various components. It does not validate the separation characters like '-' or ':'. For example, both of the following will parse to the exactly same ZonedDateTime object: "2018-08-31T13:48:01-07:00" "2018/08/31 13#48#01-07#00". |
Definition at line 113 of file ZonedDateTime.h.
|
inlinestatic |
Factory method.
Create the ZonedDateTime from epochSeconds as seen from the given time zone. The dayOfWeek will be calculated internally. Returns ZonedDateTime::forError() if epochSeconds is invalid.
epochSeconds | Number of seconds from AceTime epoch (2000-01-01 00:00:00Z). A value of LocalDate::kInvalidEpochSeconds is a sentinel that is considered to be an error and causes isError() to return true. |
timeZone | a TimeZone instance (use TimeZone() for UTC) |
Definition at line 71 of file ZonedDateTime.h.
|
inlinestatic |
Factory method to create a ZonedDateTime using the number of seconds from Unix epoch.
Returns ZonedDateTime::forError() if unixSeconds is invalid.
unixSeconds | number of seconds since Unix epoch (1970-01-01T00:00:00Z) |
timeZone | a TimeZone instance (use TimeZone() for UTC) |
Definition at line 92 of file ZonedDateTime.h.
void ace_time::ZonedDateTime::printTo | ( | Print & | printer | ) | const |
Print ZonedDateTime to 'printer'.
This class does not implement the Printable interface to avoid increasing the size of the object from the additional virtual function.
Definition at line 12 of file ZonedDateTime.cpp.
|
inline |
Set the time zone.
Note that this does not convert a given ZonedDateTime into a different TimeZone. Use converToTimeZone() instead.
Definition at line 204 of file ZonedDateTime.h.
|
inline |
Return seconds since AceTime epoch (2000-01-01 00:00:00Z), taking into account the time zone.
Normally, Julian day starts at 12:00:00. We modify the formula given in wiki page to start the Gregorian day at 00:00:00. See https://en.wikipedia.org/wiki/Julian_day
Definition at line 242 of file ZonedDateTime.h.
|
inline |
Return the number of seconds from Unix epoch 1970-01-01 00:00:00Z.
The return type is a acetime_t which can represent a range of 136 years.
Tip: You can use the command 'date +s -d {iso8601date}' on a Unix box to print the unix seconds.
Definition at line 253 of file ZonedDateTime.h.
|
inline |
Return the single-byte year offset from year 2000.
Intended for memory constrained or performance critical code. May be deprecated in the future.
Definition at line 149 of file ZonedDateTime.h.
|
inline |
Set the single-byte year offset from year 2000.
Intended for memory constrained or performance critical code. May be deprecated in the future.
Definition at line 156 of file ZonedDateTime.h.
|
friend |
Return true if two ZonedDateTime objects are equal in all components.
Optimized for small changes in the less signficant fields, such as 'second' or 'minute'. The dayOfWeek is a derived field so it is not explicitly used to test equality, but it follows that if all the other fields are identical, then the dayOfWeek must also be equal.
Definition at line 301 of file ZonedDateTime.h.