AceTime
1.0
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 holds the date-time as the components (year, month, day, hour, minute, second) without regards to the time zone. More...
#include <LocalDateTime.h>
Public Member Functions | |
LocalDateTime () | |
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... | |
acetime_t | toEpochDays () const |
Return number of whole days since AceTime epoch (2000-01-01 00:00:00Z). | |
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, after assuming that the date and time components are in UTC timezone. More... | |
acetime_t | toUnixSeconds () const |
Return seconds from Unix epoch 1970-01-01 00:00:00Z, after assuming that the date and time components are in UTC timezone. More... | |
int8_t | compareTo (const LocalDateTime &that) const |
Compare this LocalDateTime with another LocalDateTime, and return (<0, 0, >0) according to whether the epochSeconds is (a<b, a==b, a>b). | |
void | printTo (Print &printer) const |
Print LocalDateTime to 'printer' in ISO 8601 format. More... | |
LocalDateTime (const LocalDateTime &)=default | |
LocalDateTime & | operator= (const LocalDateTime &)=default |
Static Public Member Functions | |
static LocalDateTime | forComponents (int16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second) |
Factory method using separated date and time components. More... | |
static LocalDateTime | forTinyComponents (int8_t yearTiny, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second) |
Factory method using components with an int8_t yearTiny. More... | |
static LocalDateTime | forEpochSeconds (acetime_t epochSeconds) |
Factory method. More... | |
static LocalDateTime | forUnixSeconds (acetime_t unixSeconds) |
Factory method that takes the number of seconds since Unix Epoch of 1970-01-01. More... | |
static LocalDateTime | forDateString (const char *dateString) |
Factory method. More... | |
static LocalDateTime | forDateStringChainable (const char *&dateString) |
Variant of forDateString() that updates the pointer to the next unprocessed character. More... | |
static LocalDateTime | forDateString (const __FlashStringHelper *dateString) |
Factory method. More... | |
static LocalDateTime | forError () |
Factory method that returns an instance where isError() returns true. More... | |
Friends | |
bool | operator== (const LocalDateTime &a, const LocalDateTime &b) |
Return true if two LocalDateTime objects are equal in all components. More... | |
Class that holds the date-time as the components (year, month, day, hour, minute, second) without regards to the time zone.
It is an aggregation of the LocalDate and LocalTime classes.
Parts of this class were inspired by the java.time.LocalDateTime class of Java 11 (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/LocalDateTime.html).
Definition at line 27 of file LocalDateTime.h.
|
inlineexplicit |
Constructor.
All internal fields are left in an undefined state.
Definition at line 158 of file LocalDateTime.h.
|
inline |
Return the day of the month.
Definition at line 192 of file LocalDateTime.h.
|
inline |
Set the day of the month.
Definition at line 195 of file LocalDateTime.h.
|
inline |
Return the day of the week, Monday=1, Sunday=7 (per ISO 8601).
Definition at line 216 of file LocalDateTime.h.
|
inlinestatic |
Factory method using separated date and time components.
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 |
Definition at line 40 of file LocalDateTime.h.
|
static |
Factory method.
Create a LocalDateTime from the ISO 8601 date string. If the string cannot be parsed, then returns LocalDateTime::forError().
The dateString is expected to be in ISO 8601 format "YYYY-MM-DDThh:mm:ss", 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 LocalDateTime 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.
Definition at line 38 of file LocalDateTime.cpp.
|
inlinestatic |
Factory method.
Create a LocalDateTime from date string in flash memory F() strings. Mostly for unit testing.
Definition at line 135 of file LocalDateTime.h.
|
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 46 of file LocalDateTime.cpp.
|
inlinestatic |
Factory method.
Create the various components of the LocalDateTime from the epochSeconds.
Returns LocalDateTime::forError() if epochSeconds is equal to LocalDate::kInvalidEpochSeconds.
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. |
Definition at line 67 of file LocalDateTime.h.
|
inlinestatic |
Factory method that returns an instance where isError() returns true.
Definition at line 153 of file LocalDateTime.h.
|
inlinestatic |
Factory method using components with an int8_t yearTiny.
Definition at line 49 of file LocalDateTime.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.
Returns LocalDateTime::forError() if epochSeconds is equal to LocalDate::kInvalidEpochSeconds.
Definition at line 97 of file LocalDateTime.h.
|
inline |
Return the hour.
Definition at line 198 of file LocalDateTime.h.
|
inline |
Set the hour.
Definition at line 201 of file LocalDateTime.h.
|
inline |
Return true if any component indicates an error condition.
Definition at line 161 of file LocalDateTime.h.
|
inline |
Return the LocalDate.
Definition at line 219 of file LocalDateTime.h.
|
inline |
Return the LocalTime.
Definition at line 222 of file LocalDateTime.h.
|
inline |
Return the minute.
Definition at line 204 of file LocalDateTime.h.
|
inline |
Set the minute.
Definition at line 207 of file LocalDateTime.h.
|
inline |
Return the month with January=1, December=12.
Definition at line 186 of file LocalDateTime.h.
|
inline |
Set the month.
Definition at line 189 of file LocalDateTime.h.
void ace_time::LocalDateTime::printTo | ( | Print & | printer | ) | const |
Print LocalDateTime 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 14 of file LocalDateTime.cpp.
|
inline |
Return the second.
Definition at line 210 of file LocalDateTime.h.
|
inline |
Set the second.
Definition at line 213 of file LocalDateTime.h.
|
inline |
Return seconds since AceTime epoch 2000-01-01 00:00:00Z, after assuming that the date and time components are in UTC timezone.
Returns LocalDate::kInvalidEpochSeconds if isError() is true.
Definition at line 243 of file LocalDateTime.h.
|
inline |
Return the number of days since Unix epoch (1970-01-01 00:00:00).
Definition at line 233 of file LocalDateTime.h.
|
inline |
Return seconds from Unix epoch 1970-01-01 00:00:00Z, after assuming that the date and time components are in UTC timezone.
Returns LocalDate::kInvalidEpochSeconds if isError() is true.
Tip: You can use the command 'date +s -d {iso8601date}' on a Unix box to print the unix seconds of a given ISO8601 date.
Definition at line 259 of file LocalDateTime.h.
|
inline |
Return the year.
Definition at line 166 of file LocalDateTime.h.
|
inline |
Set the year.
Definition at line 169 of file LocalDateTime.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 176 of file LocalDateTime.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 183 of file LocalDateTime.h.
|
friend |
Return true if two LocalDateTime objects are equal in all components.
Optimized for small changes in the less signficant fields, such as 'second' or 'minute'.
Definition at line 307 of file LocalDateTime.h.