AceTime  0.5
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.
Public Member Functions | Static Public Member Functions | Friends | List of all members
ace_time::LocalDateTime Class Reference

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 LocalDatelocalDate () const
 Return the LocalDate. More...
 
const LocalTimelocalTime () 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
 
LocalDateTimeoperator= (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...
 

Detailed Description

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.

Constructor & Destructor Documentation

◆ LocalDateTime()

ace_time::LocalDateTime::LocalDateTime ( )
inlineexplicit

Constructor.

All internal fields are left in an undefined state.

Definition at line 158 of file LocalDateTime.h.

Member Function Documentation

◆ day() [1/2]

uint8_t ace_time::LocalDateTime::day ( ) const
inline

Return the day of the month.

Definition at line 184 of file LocalDateTime.h.

◆ day() [2/2]

void ace_time::LocalDateTime::day ( uint8_t  day)
inline

Set the day of the month.

Definition at line 187 of file LocalDateTime.h.

◆ dayOfWeek()

uint8_t ace_time::LocalDateTime::dayOfWeek ( ) const
inline

Return the day of the week, Monday=1, Sunday=7 (per ISO 8601).

Definition at line 208 of file LocalDateTime.h.

◆ forComponents()

static LocalDateTime ace_time::LocalDateTime::forComponents ( int16_t  year,
uint8_t  month,
uint8_t  day,
uint8_t  hour,
uint8_t  minute,
uint8_t  second 
)
inlinestatic

Factory method using separated date and time components.

Parameters
year[1873-2127]
monthmonth with January=1, December=12
dayday of month [1-31]
hourhour [0-23]
minuteminute [0-59]
secondsecond [0-59], does not support leap seconds

Definition at line 40 of file LocalDateTime.h.

◆ forDateString() [1/2]

LocalDateTime ace_time::LocalDateTime::forDateString ( const char *  dateString)
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 39 of file LocalDateTime.cpp.

◆ forDateString() [2/2]

static LocalDateTime ace_time::LocalDateTime::forDateString ( const __FlashStringHelper *  dateString)
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.

◆ forDateStringChainable()

LocalDateTime ace_time::LocalDateTime::forDateStringChainable ( const char *&  dateString)
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 47 of file LocalDateTime.cpp.

◆ forEpochSeconds()

static LocalDateTime ace_time::LocalDateTime::forEpochSeconds ( acetime_t  epochSeconds)
inlinestatic

Factory method.

Create the various components of the LocalDateTime from the epochSeconds.

Returns LocalDateTime::forError() if epochSeconds is equal to LocalDate::kInvalidEpochSeconds.

Parameters
epochSecondsNumber 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.

◆ forError()

static LocalDateTime ace_time::LocalDateTime::forError ( )
inlinestatic

Factory method that returns an instance where isError() returns true.

Definition at line 153 of file LocalDateTime.h.

◆ forTinyComponents()

static LocalDateTime ace_time::LocalDateTime::forTinyComponents ( int8_t  yearTiny,
uint8_t  month,
uint8_t  day,
uint8_t  hour,
uint8_t  minute,
uint8_t  second 
)
inlinestatic

Factory method using components with an int8_t yearTiny.

Definition at line 49 of file LocalDateTime.h.

◆ forUnixSeconds()

static LocalDateTime ace_time::LocalDateTime::forUnixSeconds ( acetime_t  unixSeconds)
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.

◆ hour() [1/2]

uint8_t ace_time::LocalDateTime::hour ( ) const
inline

Return the hour.

Definition at line 190 of file LocalDateTime.h.

◆ hour() [2/2]

void ace_time::LocalDateTime::hour ( uint8_t  hour)
inline

Set the hour.

Definition at line 193 of file LocalDateTime.h.

◆ isError()

bool ace_time::LocalDateTime::isError ( ) const
inline

Return true if any component indicates an error condition.

Definition at line 161 of file LocalDateTime.h.

◆ localDate()

const LocalDate& ace_time::LocalDateTime::localDate ( ) const
inline

Return the LocalDate.

Definition at line 211 of file LocalDateTime.h.

◆ localTime()

const LocalTime& ace_time::LocalDateTime::localTime ( ) const
inline

Return the LocalTime.

Definition at line 214 of file LocalDateTime.h.

◆ minute() [1/2]

uint8_t ace_time::LocalDateTime::minute ( ) const
inline

Return the minute.

Definition at line 196 of file LocalDateTime.h.

◆ minute() [2/2]

void ace_time::LocalDateTime::minute ( uint8_t  minute)
inline

Set the minute.

Definition at line 199 of file LocalDateTime.h.

◆ month() [1/2]

uint8_t ace_time::LocalDateTime::month ( ) const
inline

Return the month with January=1, December=12.

Definition at line 178 of file LocalDateTime.h.

◆ month() [2/2]

void ace_time::LocalDateTime::month ( uint8_t  month)
inline

Set the month.

Definition at line 181 of file LocalDateTime.h.

◆ printTo()

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 15 of file LocalDateTime.cpp.

◆ second() [1/2]

uint8_t ace_time::LocalDateTime::second ( ) const
inline

Return the second.

Definition at line 202 of file LocalDateTime.h.

◆ second() [2/2]

void ace_time::LocalDateTime::second ( uint8_t  second)
inline

Set the second.

Definition at line 205 of file LocalDateTime.h.

◆ toEpochSeconds()

acetime_t ace_time::LocalDateTime::toEpochSeconds ( ) const
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 235 of file LocalDateTime.h.

◆ toUnixDays()

acetime_t ace_time::LocalDateTime::toUnixDays ( ) const
inline

Return the number of days since Unix epoch (1970-01-01 00:00:00).

Definition at line 225 of file LocalDateTime.h.

◆ toUnixSeconds()

acetime_t ace_time::LocalDateTime::toUnixSeconds ( ) const
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 251 of file LocalDateTime.h.

◆ year() [1/2]

int16_t ace_time::LocalDateTime::year ( ) const
inline

Return the year.

Definition at line 166 of file LocalDateTime.h.

◆ year() [2/2]

void ace_time::LocalDateTime::year ( int16_t  year)
inline

Set the year.

Definition at line 169 of file LocalDateTime.h.

◆ yearTiny() [1/2]

int8_t ace_time::LocalDateTime::yearTiny ( ) const
inline

Return the single-byte year offset from year 2000.

Definition at line 172 of file LocalDateTime.h.

◆ yearTiny() [2/2]

void ace_time::LocalDateTime::yearTiny ( int8_t  yearTiny)
inline

Set the single-byte year offset from year 2000.

Definition at line 175 of file LocalDateTime.h.

Friends And Related Function Documentation

◆ operator==

bool operator== ( const LocalDateTime a,
const LocalDateTime b 
)
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 299 of file LocalDateTime.h.


The documentation for this class was generated from the following files: