AceTime
1.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 offset from UTC (timeOffset). More...
#include <OffsetDateTime.h>
Public Member Functions | |
OffsetDateTime () | |
Constructor. More... | |
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. | |
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, Monday=1, Sunday=7 (per ISO 8601). | |
TimeOffset | timeOffset () const |
Return the offset zone of the OffsetDateTime. | |
void | timeOffset (TimeOffset timeOffset) |
Set the offset zone. | |
const LocalDateTime & | localDateTime () const |
Return the LocalDateTime. | |
const LocalDate & | localDate () const |
Return the LocalDate. | |
const LocalTime & | localTime () const |
Return the LocalTime. | |
OffsetDateTime | convertToTimeOffset (TimeOffset timeOffset) const |
Create a OffsetDateTime in a different offset zone code (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 offset 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 offset zone. | |
acetime_t | toUnixSeconds () const |
Return the number of seconds from Unix epoch 1970-01-01 00:00:00Z. More... | |
int8_t | compareTo (const OffsetDateTime &that) const |
Compare this OffsetDateTime with another OffsetDateTime, and return (<0, 0, >0) according to whether the epochSeconds is (a<b, a==b, a>b). More... | |
void | printTo (Print &printer) const |
Print OffsetDateTime to 'printer' in ISO 8601 format. More... | |
OffsetDateTime (const OffsetDateTime &)=default | |
OffsetDateTime & | operator= (const OffsetDateTime &)=default |
Static Public Member Functions | |
static OffsetDateTime | forLocalDateTimeAndOffset (const LocalDateTime &localDateTime, TimeOffset timeOffset) |
Factory method from LocalDateTime and TimeOffset. | |
static OffsetDateTime | forComponents (int16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second, TimeOffset timeOffset) |
Factory method using separated date, time, and UTC offset fields. More... | |
static OffsetDateTime | forEpochSeconds (acetime_t epochSeconds, TimeOffset timeOffset) |
Factory method. More... | |
static OffsetDateTime | forUnixSeconds (acetime_t unixSeconds, TimeOffset timeOffset) |
Factory method that takes the number of seconds since Unix Epoch of 1970-01-01. More... | |
static OffsetDateTime | forDateString (const char *dateString) |
Factory method. More... | |
static OffsetDateTime | forDateStringChainable (const char *&dateString) |
Variant of forDateString() that updates the pointer to the next unprocessed character. More... | |
static OffsetDateTime | forDateString (const __FlashStringHelper *dateString) |
Factory method. More... | |
static OffsetDateTime | forError () |
Factory method that returns an instance whose isError() is true. | |
Friends | |
bool | operator== (const OffsetDateTime &a, const OffsetDateTime &b) |
Return true if two OffsetDateTime objects are equal in all components. More... | |
The date (year, month, day), time (hour, minute, second) and offset from UTC (timeOffset).
The dayOfWeek (1=Monday, 7=Sunday, per ISO 8601) is calculated internally from the date fields.
The year field is internally represented as int8_t offset from the year 2000, so in theory it is valid from [1873, 2127] since -128 is used to indicate an error condition. If the year is restricted to the range 00-99, these fields map directly to the fields supported by the DS3231 RTC chip. The "epoch" for this library is 2000-01-01T00:00:00Z and toEpochSeconds() returns a int32_t number of seconds offset from that epoch.
Parts of this class were inspired by the java.time.OffsetDateTime class of Java 11 (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/OffsetDateTime.html).
Definition at line 33 of file OffsetDateTime.h.
|
inlineexplicit |
Constructor.
All internal fields are left in an undefined state.
Definition at line 151 of file OffsetDateTime.h.
|
inline |
Compare this OffsetDateTime with another OffsetDateTime, and return (<0, 0, >0) according to whether the epochSeconds is (a<b, a==b, a>b).
This method can return 0 (equal) even if the operator==() returns false if the two OffsetDateTime objects are using different time offsets.
Definition at line 286 of file OffsetDateTime.h.
|
inlinestatic |
Factory method using separated date, time, and UTC offset fields.
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 |
timeOffset | the time offset from UTC. Using TimeOffset in the last component (instead of an int8_t or int16_t) allows us to overload an additional constructor that accepts a millisecond component in the future. |
Definition at line 53 of file OffsetDateTime.h.
|
inlinestatic |
Factory method.
Create a OffsetDateTime from date string in flash memory F() strings. Mostly for unit testing. Returns OffsetDateTime::forError() if a parsing error occurs.
Definition at line 128 of file OffsetDateTime.h.
|
static |
Factory method.
Create a OffsetDateTime from the ISO 8601 date string. If the string cannot be parsed, then returns OffsetDateTime::forError(). Created for debugging purposes not for production use.
The parsing validation is so weak that the behavior is undefined for most invalid date/time strings. The range of valid dates is roughly from 1872-01-01T00:00:00 to 2127-12-31T23:59:59. However, the UTC offset may cause some of the dates on the two extreme ends invalid. The behavior is undefined in those cases.
dateString | the date and time in ISO 8601 format "YYYY-MM-DDThh:mm:ss+/-hh:mm", but currently, the parser is very lenient. 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 OffsetDateTime object: "2018-08-31T13:48:01-07:00" "2018/08/31 13#48#01-07#00" |
Definition at line 28 of file OffsetDateTime.cpp.
|
static |
Variant of forDateString() that updates the pointer to the next unprocessed character.
This allows chaining to another forXxxStringChainable() method.
This method assumes that the dateString is sufficiently long.
Definition at line 35 of file OffsetDateTime.cpp.
|
inlinestatic |
Factory method.
Create the various components of the OffsetDateTime from the epochSeconds and its TimeOffset. Returns OffsetDateTime::forError() if epochSeconds or timeOffset is an error.
epochSeconds | Number of seconds from AceTime epoch (2000-01-01 00:00:00). Use LocalDate::kInvalidEpochSeconds to define an invalid instance whose isError() returns true. |
timeOffset | time offset from UTC |
Definition at line 71 of file OffsetDateTime.h.
|
inlinestatic |
Factory method that takes the number of seconds since Unix Epoch of 1970-01-01.
Similar to forEpochSeconds(), the seconds corresponding to the partial day are truncated down towards the smallest whole day.
Definition at line 85 of file OffsetDateTime.h.
void ace_time::OffsetDateTime::printTo | ( | Print & | printer | ) | const |
Print OffsetDateTime to 'printer' in ISO 8601 format.
This class does not implement the Printable interface to avoid increasing the size of the object from the additional virtual function.
Definition at line 15 of file OffsetDateTime.cpp.
|
inline |
Return the number of seconds from Unix epoch 1970-01-01 00:00:00Z.
It returns kInvalidEpochSeconds if isError() is true.
Tip: You can use the command 'date +s -d {iso8601date}' on a Unix box to convert an ISO8601 date to the unix seconds.
Definition at line 275 of file OffsetDateTime.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 170 of file OffsetDateTime.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 177 of file OffsetDateTime.h.
|
friend |
Return true if two OffsetDateTime objects are equal in all components.
Optimized for small changes in the less signficant fields, such as 'second' or 'minute'.
Definition at line 325 of file OffsetDateTime.h.