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.
|
The date (year, month, day) and time (hour, minute, second) fields representing the time with an offset from UTC. More...
#include <OffsetDateTime.h>
Public Member Functions | |
OffsetDateTime () | |
Constructor. More... | |
bool | isError () const |
Return true if any component indicates an error condition. More... | |
int16_t | year () const |
Return the year. More... | |
void | year (int16_t year) |
Set the year. More... | |
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. More... | |
void | month (uint8_t month) |
Set the month. More... | |
uint8_t | day () const |
Return the day of the month. More... | |
void | day (uint8_t day) |
Set the day of the month. More... | |
uint8_t | hour () const |
Return the hour. More... | |
void | hour (uint8_t hour) |
Set the hour. More... | |
uint8_t | minute () const |
Return the minute. More... | |
void | minute (uint8_t minute) |
Set the minute. More... | |
uint8_t | second () const |
Return the second. More... | |
void | second (uint8_t second) |
Set the second. More... | |
uint8_t | dayOfWeek () const |
Return the day of the week, Monday=1, Sunday=7 (per ISO 8601). More... | |
const LocalDate & | localDate () const |
Return the LocalDate. More... | |
const LocalTime & | localTime () const |
Return the LocalTime. More... | |
TimeOffset | timeOffset () const |
Return the offset zone of the OffsetDateTime. More... | |
void | timeOffset (TimeOffset timeOffset) |
Set the offset zone. More... | |
OffsetDateTime | convertToTimeOffset (TimeOffset timeOffset) const |
Create a OffsetDateTime in a different offset zone code (with the same epochSeconds). | |
void | printTo (Print &printer) const |
Print OffsetDateTime to 'printer' in ISO 8601 format. More... | |
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). More... | |
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... | |
OffsetDateTime (const OffsetDateTime &)=default | |
OffsetDateTime & | operator= (const OffsetDateTime &)=default |
Static Public Member Functions | |
static OffsetDateTime | forComponents (int16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second, TimeOffset timeOffset=TimeOffset()) |
Factory method using separated date, time, and UTC offset fields. More... | |
static OffsetDateTime | forEpochSeconds (acetime_t epochSeconds, TimeOffset timeOffset=TimeOffset()) |
Factory method. More... | |
static OffsetDateTime | forUnixSeconds (acetime_t unixSeconds, TimeOffset 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 | forDateString (const __FlashStringHelper *dateString) |
Factory method. More... | |
static OffsetDateTime | forError () |
Factory method that returns an instance whose isError() is true. More... | |
Friends | |
class | ZonedDateTime |
class | BasicZoneSpecifier |
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) and time (hour, minute, second) fields representing the time with an offset from UTC.
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 [1872, 2127]. 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. The largest possible int32_t value is INT32_MAX, but this value is used by kInvalidEpochSeconds to indicate an invalid value.
Parts of this class were inspired by the java.time.OffsetDateTime class of Java 8 (https://docs.oracle.com/javase/8/docs/api/java/time/OffsetDateTime.html).
Definition at line 30 of file OffsetDateTime.h.
|
inlineexplicit |
Constructor.
All internal fields are left in an undefined state.
Definition at line 137 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 in different offset zones.
Definition at line 267 of file OffsetDateTime.h.
|
inline |
Return the day of the month.
Definition at line 164 of file OffsetDateTime.h.
|
inline |
Set the day of the month.
Definition at line 167 of file OffsetDateTime.h.
|
inline |
Return the day of the week, Monday=1, Sunday=7 (per ISO 8601).
Definition at line 188 of file OffsetDateTime.h.
|
inlinestatic |
Factory method using separated date, time, and UTC offset fields.
year | [1872-2127] for 8-bit implementation, [0000-9999] for 16-bit implementation |
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 | Optional. Default UTC time zone. Using the TimeOffset object in the last component allows us to add an additional constructor that accepts a millisecond component in the future. It also hides the internal implementation details of TimeOffset. |
Definition at line 47 of file OffsetDateTime.h.
|
static |
Factory method.
Create a OffsetDateTime from the ISO 8601 date string. If the string cannot be parsed, then isError() on the constructed object returns true.
The dateString is expected to be 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"
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.
Definition at line 43 of file OffsetDateTime.cpp.
|
inlinestatic |
Factory method.
Create a OffsetDateTime from date string in flash memory F() strings. Mostly for unit testing.
Definition at line 115 of file OffsetDateTime.h.
|
inlinestatic |
Factory method.
Create the various components of the OffsetDateTime from the epochSeconds and its TimeOffset.
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 | Optional. Default is UTC time zone. |
Definition at line 62 of file OffsetDateTime.h.
|
inlinestatic |
Factory method that returns an instance whose isError() is true.
Definition at line 132 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 80 of file OffsetDateTime.h.
|
inline |
Return the hour.
Definition at line 170 of file OffsetDateTime.h.
|
inline |
Set the hour.
Definition at line 173 of file OffsetDateTime.h.
|
inline |
Return true if any component indicates an error condition.
Definition at line 140 of file OffsetDateTime.h.
|
inline |
Return the LocalDate.
Definition at line 191 of file OffsetDateTime.h.
|
inline |
Return the LocalTime.
Definition at line 194 of file OffsetDateTime.h.
|
inline |
Return the minute.
Definition at line 176 of file OffsetDateTime.h.
|
inline |
Set the minute.
Definition at line 179 of file OffsetDateTime.h.
|
inline |
Return the month with January=1, December=12.
Definition at line 158 of file OffsetDateTime.h.
|
inline |
Set the month.
Definition at line 161 of file OffsetDateTime.h.
void ace_time::OffsetDateTime::printTo | ( | Print & | printer | ) | const |
Print OffsetDateTime to 'printer' in ISO 8601 format.
Does not implement Printable to avoid memory cost of a vtable pointer.
Definition at line 11 of file OffsetDateTime.cpp.
|
inline |
Return the second.
Definition at line 182 of file OffsetDateTime.h.
|
inline |
Set the second.
Definition at line 185 of file OffsetDateTime.h.
|
inline |
Return the offset zone of the OffsetDateTime.
Definition at line 197 of file OffsetDateTime.h.
|
inline |
Set the offset zone.
Definition at line 200 of file OffsetDateTime.h.
|
inline |
Return the number of days since Unix epoch (1970-01-01 00:00:00).
Definition at line 235 of file OffsetDateTime.h.
|
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 print the unix seconds.
Definition at line 256 of file OffsetDateTime.h.
|
inline |
Return the year.
Definition at line 146 of file OffsetDateTime.h.
|
inline |
Set the year.
Definition at line 149 of file OffsetDateTime.h.
|
inline |
Return the single-byte year offset from year 2000.
Definition at line 152 of file OffsetDateTime.h.
|
inline |
Set the single-byte year offset from year 2000.
Definition at line 155 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 330 of file OffsetDateTime.h.