AceTime 3.0.0 Date and time classes for Arduino that support timezones from the TZ Database.

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 fixed 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.
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 | fold () const
| Return the fold.
void | fold (uint8_t fold)
| Set the fold.
uint8_t | dayOfWeek () const
| Return the day of the week, Monday=1, Sunday=7 (per ISO 8601).
TimeOffset | timeOffset () const
| Return the UTC offset of the OffsetDateTime.
void | timeOffset (TimeOffset timeOffset)
| Set the UTC offset.
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 UTC offset code (with the same epochSeconds). More...
int32_t | toEpochDays () const
| Return number of whole days since AceTime epoch taking into account the UTC offset. More...
int32_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 taking into account the UTC offset. More...
int64_t | toUnixSeconds64 () const
| Return the 64-bit number of seconds from Unix epoch 1970-01-01 00:00:00 UTC. More...
int8_t | compareTo (const OffsetDateTime &that) const
| Compare 'this' OffsetDateTime with 'that' OffsetDateTime, and return (<0, 0, >0) according to whether the epochSeconds (incorporating the time offset) 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, uint8_t fold=0)
| Factory method using separated date, time, and UTC offset fields. More...
static OffsetDateTime | forEpochSeconds (acetime_t epochSeconds, TimeOffset timeOffset, uint8_t fold=0)
| Factory method. More...
static OffsetDateTime | forUnixSeconds64 (int64_t unixSeconds, TimeOffset timeOffset, int8_t fold=0)
| Factory method that takes the number of seconds (64-bit) 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 | forDateStringChainable (const char *&dateString)
| Variant of forDateString() that updates the pointer to the next unprocessed character. 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...

## Detailed Description

The date (year, month, day), time (hour, minute, second) and fixed offset from UTC (timeOffset).

The year field is valid from [0, 10000] with year 0 interpreted as -Infinity and year 10000 interpreted as +Infinity. An invalid year is represented by INT16_MIN (-32768). If the year is restricted to the range 2000-2099, then the last 2 digits map directly to the fields supported by the DS3231 RTC chip.

The default epoch for AceTime is 2050-01-01T00:00:00 UTC, but can be changed using `Epoch::currentEpochYear()`. The `toEpochSeconds()` method returns a `int32_t` number of seconds offset from that epoch.

The dayOfWeek (1=Monday, 7=Sunday, per ISO 8601) is calculated internally from the date fields.

Parts of this class were inspired by the java.time.OffsetDateTime class of Java 11, and the datetime package of Python 3.

Definition at line 37 of file OffsetDateTime.h.

## Constructor & Destructor Documentation

## ◆ OffsetDateTime()

ace_time::OffsetDateTime::OffsetDateTime | ( |  | ) |
| inline explicit

Constructor.

All internal fields are left in an undefined state.

Definition at line 147 of file OffsetDateTime.h.

## Member Function Documentation

## ◆ compareTo()

int8_t ace_time::OffsetDateTime::compareTo | ( | const OffsetDateTime & | that | ) | const
| inline

Compare 'this' OffsetDateTime with 'that' OffsetDateTime, and return (<0, 0, >0) according to whether the epochSeconds (incorporating the time offset) 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.

If you want to know whether the local representatation of 'this' OffsetDateTime occurs before or after the local representation of 'that', use `this->localDateTime().compareTo(that.localDateTime())` instead. This expression ignores the time offset which is sometimes what you want.

If either this->isError() or that.isError() is true, the result is undefined.

Definition at line 296 of file OffsetDateTime.h.

## ◆ convertToTimeOffset()

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

Create a OffsetDateTime in a different UTC offset code (with the same epochSeconds).

Calls forEpochSeconds() so subject to its overflow/underflow limits.

Definition at line 221 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,
|  | uint8_t | fold = `0`
| ) |  |
| inline static

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

Parameters

  year | year [0,10000]
  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.
  fold | optional disambiguation of multiple occurences [0, 1]

Definition at line 61 of file OffsetDateTime.h.

## ◆ forDateString() [1/2]

OffsetDateTime ace_time::OffsetDateTime::forDateString | ( | const __FlashStringHelper * | dateString | ) |
| static

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

## ◆ forDateString() [2/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. 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"

Parameters

  dateString | the date and time in ISO 8601 format "YYYY-MM-DDThh:mm:ss+/-hh:mm". The range of valid dates is from 0001-01-01T00:00:00 to 9999-12-31T23:59:59.

Definition at line 27 of file OffsetDateTime.cpp.

## ◆ 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 52 of file OffsetDateTime.cpp.

## ◆ forEpochSeconds()

static OffsetDateTime ace_time::OffsetDateTime::forEpochSeconds | ( | acetime_t | epochSeconds,
|  | TimeOffset | timeOffset,
|  | uint8_t | fold = `0`
| ) |  |
| inline static

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

  epochSeconds | Number of seconds from AceTime epoch (2050-01-01 00:00:00 by default). Use LocalDate::kInvalidEpochSeconds to define an invalid instance whose isError() returns true.
  timeOffset | time offset from UTC

Definition at line 79 of file OffsetDateTime.h.

## ◆ forUnixSeconds64()

static OffsetDateTime ace_time::OffsetDateTime::forUnixSeconds64 | ( | int64_t | unixSeconds,
|  | TimeOffset | timeOffset,
|  | int8_t | fold = `0`
| ) |  |
| inline static

Factory method that takes the number of seconds (64-bit) 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 OffsetDateTime::forError() if unixSeconds is invalid.

Parameters

  unixSeconds | number of seconds since Unix epoch (1970-01-01T00:00:00 UTC)
  timeOffset | time offset from UTC

Definition at line 98 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 14 of file OffsetDateTime.cpp.

## ◆ toEpochDays()

int32_t ace_time::OffsetDateTime::toEpochDays | ( |  | ) | const
| inline

Return number of whole days since AceTime epoch taking into account the UTC offset.

The default epoch is 2050-01-01 00:00:00 UTC but can be changed using `Epoch::currentEpochYear()`.

Definition at line 231 of file OffsetDateTime.h.

## ◆ toEpochSeconds()

acetime_t ace_time::OffsetDateTime::toEpochSeconds | ( |  | ) | const
| inline

Return seconds since AceTime epoch taking into account the UTC offset.

The default epoch is 2050-01-01 00:00:00 UTC but can be changed using `Epoch::currentEpochYear()`.

Definition at line 259 of file OffsetDateTime.h.

## ◆ toUnixSeconds64()

int64_t ace_time::OffsetDateTime::toUnixSeconds64 | ( |  | ) | const
| inline

Return the 64-bit number of seconds from Unix epoch 1970-01-01 00:00:00 UTC.

Returns LocalDate::kInvalidUnixSeconds64 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.

## 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 335 of file OffsetDateTime.h.

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

- /home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/OffsetDateTime.h
- /home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/OffsetDateTime.cpp