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

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. 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...
 
TimeOffset timeOffset () const
 Return the offset zone of the OffsetDateTime. More...
 
void timeOffset (TimeOffset timeOffset)
 Set the offset zone. More...
 
const LocalDateTimelocalDateTime () const
 Return the LocalDateTime. More...
 
const LocalDatelocalDate () const
 Return the LocalDate. More...
 
const LocalTimelocalTime () const
 Return the LocalTime. More...
 
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). 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...
 
void printTo (Print &printer) const
 Print OffsetDateTime to 'printer' in ISO 8601 format. More...
 
 OffsetDateTime (const OffsetDateTime &)=default
 
OffsetDateTimeoperator= (const OffsetDateTime &)=default
 

Static Public Member Functions

static OffsetDateTime forLocalDateTimeAndOffset (const LocalDateTime &localDateTime, TimeOffset timeOffset)
 Factory method from LocalDateTime and TimeOffset. More...
 
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. More...
 

Friends

bool operator== (const OffsetDateTime &a, const OffsetDateTime &b)
 Return true if two OffsetDateTime objects are equal in all components. More...
 

Detailed Description

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.

Constructor & Destructor Documentation

◆ OffsetDateTime()

ace_time::OffsetDateTime::OffsetDateTime ( )
inlineexplicit

Constructor.

All internal fields are left in an undefined state.

Definition at line 151 of file OffsetDateTime.h.

Member Function Documentation

◆ compareTo()

int8_t ace_time::OffsetDateTime::compareTo ( const OffsetDateTime that) const
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 278 of file OffsetDateTime.h.

◆ day() [1/2]

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

Return the day of the month.

Definition at line 178 of file OffsetDateTime.h.

◆ day() [2/2]

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

Set the day of the month.

Definition at line 181 of file OffsetDateTime.h.

◆ dayOfWeek()

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

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

Definition at line 202 of file OffsetDateTime.h.

◆ forComponents()

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

Factory method using separated date, time, and UTC offset fields.

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
timeOffsetthe 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.

◆ forDateString() [1/2]

OffsetDateTime ace_time::OffsetDateTime::forDateString ( const char *  dateString)
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.

Parameters
dateStringthe 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 29 of file OffsetDateTime.cpp.

◆ forDateString() [2/2]

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

◆ forDateStringChainable()

OffsetDateTime ace_time::OffsetDateTime::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 36 of file OffsetDateTime.cpp.

◆ forEpochSeconds()

static OffsetDateTime ace_time::OffsetDateTime::forEpochSeconds ( acetime_t  epochSeconds,
TimeOffset  timeOffset 
)
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.

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.
timeOffsettime offset from UTC

Definition at line 71 of file OffsetDateTime.h.

◆ forError()

static OffsetDateTime ace_time::OffsetDateTime::forError ( )
inlinestatic

Factory method that returns an instance whose isError() is true.

Definition at line 146 of file OffsetDateTime.h.

◆ forLocalDateTimeAndOffset()

static OffsetDateTime ace_time::OffsetDateTime::forLocalDateTimeAndOffset ( const LocalDateTime localDateTime,
TimeOffset  timeOffset 
)
inlinestatic

Factory method from LocalDateTime and TimeOffset.

Definition at line 37 of file OffsetDateTime.h.

◆ forUnixSeconds()

static OffsetDateTime ace_time::OffsetDateTime::forUnixSeconds ( acetime_t  unixSeconds,
TimeOffset  timeOffset 
)
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.

◆ hour() [1/2]

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

Return the hour.

Definition at line 184 of file OffsetDateTime.h.

◆ hour() [2/2]

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

Set the hour.

Definition at line 187 of file OffsetDateTime.h.

◆ isError()

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

Return true if any component indicates an error condition.

Definition at line 154 of file OffsetDateTime.h.

◆ localDate()

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

Return the LocalDate.

Definition at line 214 of file OffsetDateTime.h.

◆ localDateTime()

const LocalDateTime& ace_time::OffsetDateTime::localDateTime ( ) const
inline

Return the LocalDateTime.

Definition at line 211 of file OffsetDateTime.h.

◆ localTime()

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

Return the LocalTime.

Definition at line 217 of file OffsetDateTime.h.

◆ minute() [1/2]

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

Return the minute.

Definition at line 190 of file OffsetDateTime.h.

◆ minute() [2/2]

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

Set the minute.

Definition at line 193 of file OffsetDateTime.h.

◆ month() [1/2]

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

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

Definition at line 172 of file OffsetDateTime.h.

◆ month() [2/2]

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

Set the month.

Definition at line 175 of file OffsetDateTime.h.

◆ printTo()

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 16 of file OffsetDateTime.cpp.

◆ second() [1/2]

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

Return the second.

Definition at line 196 of file OffsetDateTime.h.

◆ second() [2/2]

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

Set the second.

Definition at line 199 of file OffsetDateTime.h.

◆ timeOffset() [1/2]

TimeOffset ace_time::OffsetDateTime::timeOffset ( ) const
inline

Return the offset zone of the OffsetDateTime.

Definition at line 205 of file OffsetDateTime.h.

◆ timeOffset() [2/2]

void ace_time::OffsetDateTime::timeOffset ( TimeOffset  timeOffset)
inline

Set the offset zone.

Definition at line 208 of file OffsetDateTime.h.

◆ toUnixDays()

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

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

Definition at line 246 of file OffsetDateTime.h.

◆ toUnixSeconds()

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

◆ year() [1/2]

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

Return the year.

Definition at line 160 of file OffsetDateTime.h.

◆ year() [2/2]

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

Set the year.

Definition at line 163 of file OffsetDateTime.h.

◆ yearTiny() [1/2]

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

Return the single-byte year offset from year 2000.

Definition at line 166 of file OffsetDateTime.h.

◆ yearTiny() [2/2]

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

Set the single-byte year offset from year 2000.

Definition at line 169 of file OffsetDateTime.h.

Friends And Related Function Documentation

◆ operator==

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


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