The date (year, month, day), time (hour, minute, second), and a timeZone object that supports the zones defined by the IANA TZ database. More...

#include <ZonedDateTime.h>

Public Member Functions
	ZonedDateTime ()
	Default constructor.

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 given the full 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 using ISO 8601 numbering where Monday=1 and Sunday=7.

const TimeZone &	timeZone () const
	Return the time zone of the ZonedDateTime.

void	timeZone (const TimeZone &timeZone)
	Set the time zone. More...

TimeOffset	timeOffset () const
	Return the offset zone of the OffsetDateTime.

const LocalDateTime &	localDateTime () const
	Return the LocalDateTime of the components.

const OffsetDateTime &	offsetDateTime () const
	Return the OffsetDateTime of the components.

void	normalize ()
	Normalize the ZonedDateTime after mutation. More...

ZonedDateTime	convertToTimeZone (const TimeZone &timeZone) const
	Create a ZonedDateTime in a different time zone (with the same epochSeconds).

int32_t	toEpochDays () const
	Return number of whole days since AceTime epoch taking into account the time zone. 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 time zone. 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 ZonedDateTime &that) const
	Compare 'this' ZonedDateTime with 'that' ZonedDateTime, and return (<0, 0, >0) according to whether the equivalent epochSeconds (with the timezone incorporated) is (a<b, a==b, a>b). More...

void	printTo (Print &printer) const
	Print ZonedDateTime to 'printer'. More...

	ZonedDateTime (const ZonedDateTime &)=default

ZonedDateTime &	operator= (const ZonedDateTime &)=default

Static Public Member Functions
static ZonedDateTime	forComponents (int16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second, const TimeZone &timeZone, uint8_t fold=0)
	Factory method using separated date, time, and time zone fields. More...

static ZonedDateTime	forLocalDateTime (const LocalDateTime &ldt, const TimeZone &timeZone)
	Factory method using LocalDateTime and time zone fields. More...

static ZonedDateTime	forEpochSeconds (acetime_t epochSeconds, const TimeZone &timeZone)
	Factory method. More...

static ZonedDateTime	forUnixSeconds64 (int64_t unixSeconds, const TimeZone &timeZone)
	Factory method to create a ZonedDateTime using the 64-bit number of seconds from Unix epoch. More...

static ZonedDateTime	forDateString (const char *dateString)
	Factory method. More...

static ZonedDateTime	forDateString (const __FlashStringHelper *dateString)
	Factory method. More...

static ZonedDateTime	forError ()
	Return an instance whose isError() returns true.

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

Detailed Description

The date (year, month, day), time (hour, minute, second), and a timeZone object that supports the zones defined by the IANA TZ database.

The year field is internally represented as an int16_t number, with 0 indicating -Infinity and 10000 representing +Infinity, so the normal range is [1,9999]. An invalid year is represented by INT16_MIN (-32768).

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

The dayOfWeek (1=Sunday, 7=Saturday) is calculated internally from the date components. Changing the timeZone does not affect the dayOfWeek.

Some parts of this class were inspired by the org.joda.DateTime of http://www.joda.org, the java.time.ZonedDateTime class of Java 11, and the datetime package of Python 3.

Definition at line 36 of file ZonedDateTime.h.

Member Function Documentation

◆ compareTo()

int8_t ace_time::ZonedDateTime::compareTo ( const ZonedDateTime & that ) const

inline

Compare 'this' ZonedDateTime with 'that' ZonedDateTime, and return (<0, 0, >0) according to whether the equivalent epochSeconds (with the timezone incorporated) is (a<b, a==b, a>b).

The dayOfWeek field is ignored. This method can return 0 (equal) even if the operator==() returns false if the two ZonedDateTime objects are in different time zones.

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

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

Definition at line 318 of file ZonedDateTime.h.

◆ forComponents()

static ZonedDateTime ace_time::ZonedDateTime::forComponents	(	int16_t	year,
		uint8_t	month,
		uint8_t	day,
		uint8_t	hour,
		uint8_t	minute,
		uint8_t	second,
		const TimeZone &	timeZone,
		uint8_t	fold = `0`
	)

inlinestatic

Factory method using separated date, time, and time zone fields.

This is intended mostly for testing purposes. Most production code will use the forEpochSeconds() method.

The TimeOffset at the given date/time component is calculated using TimeZone::getOffsetDateTime().

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
timeZone	a TimeZone instance (use TimeZone() for UTC)
fold	optional disambiguation of multiple occurences [0, 1]

Definition at line 55 of file ZonedDateTime.h.

◆ forDateString() [1/2]

static ZonedDateTime ace_time::ZonedDateTime::forDateString ( const __FlashStringHelper * dateString )

inlinestatic

Factory method.

Create a ZonedDateTime from date string in flash memory F() strings. Mostly for unit testing.

Definition at line 153 of file ZonedDateTime.h.

◆ forDateString() [2/2]

static ZonedDateTime ace_time::ZonedDateTime::forDateString ( const char * dateString )

inlinestatic

Factory method.

Create a ZonedDateTime from the ISO 8601 date string. If the string cannot be parsed, then isError() on the constructed object returns true.

Parameters

dateString a string in ISO 8601 format "YYYY-MM-DDThh:mm:ss+hh:mm". The parser is very lenient and does not detect most errors. 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 ZonedDateTime object: "2018-08-31T13:48:01-07:00" "2018/08/31 13#48#01-07#00".

Definition at line 144 of file ZonedDateTime.h.

◆ forEpochSeconds()

static ZonedDateTime ace_time::ZonedDateTime::forEpochSeconds	(	acetime_t	epochSeconds,
		const TimeZone &	timeZone
	)

inlinestatic

Factory method.

Create the ZonedDateTime from epochSeconds as seen from the given time zone. The dayOfWeek will be calculated internally. Returns ZonedDateTime::forError() if epochSeconds is invalid.

Parameters

epochSeconds	Number of seconds from the current epoch by `Epoch::currentEpochYear()`. The default is 2050-01-01 00:00:00 UTC which can be changed by `currentEpochYear(year)`. A value of LocalDate::kInvalidEpochSeconds is a sentinel that is considered to be an error and causes isError() to return true.
timeZone	a TimeZone instance (use TimeZone() for UTC)

Definition at line 93 of file ZonedDateTime.h.

◆ forLocalDateTime()

static ZonedDateTime ace_time::ZonedDateTime::forLocalDateTime	(	const LocalDateTime &	ldt,
		const TimeZone &	timeZone
	)

inlinestatic

Factory method using LocalDateTime and time zone fields.

This is intended mostly for testing purposes. Most production code will use the forEpochSeconds() method.

The TimeOffset at the given date/time component is calculated using TimeZone::getOffsetDateTime().

Parameters

ldt	LocalDateTime (including the fold parameter)
timeZone	a TimeZone instance (use TimeZone() for UTC)

Definition at line 75 of file ZonedDateTime.h.

◆ forUnixSeconds64()

static ZonedDateTime ace_time::ZonedDateTime::forUnixSeconds64	(	int64_t	unixSeconds,
		const TimeZone &	timeZone
	)

inlinestatic

Factory method to create a ZonedDateTime using the 64-bit number of seconds from Unix epoch.

Even though unixSeconds is 64-bit integer, the internal calculations of the DST time zone transitions are performed using a 32-bit integer. Therefore, the valid range of unixSeconds is approximately the same range as ZonedDateTime::forEpochSeconds() after translating it to the AceTime current epoch. In other words, unixSeconds should be roughly within +/- 60 years of the current epoch year given by Epoch::currentEpochYear().

Returns ZonedDateTime::forError() if unixSeconds is invalid.

Parameters

unixSeconds	number of seconds since Unix epoch (1970-01-01T00:00:00 UTC)
timeZone	a TimeZone instance (use TimeZone() for UTC)

Definition at line 119 of file ZonedDateTime.h.

◆ normalize()

void ace_time::ZonedDateTime::normalize ( )

inline

Normalize the ZonedDateTime after mutation.

This must be called after any mutation method is called (i.e. year(), month(), day(), hour(), minute(), second(), timezone()) in order to obtain correct values for various derivative information (e.g. toEpochSeconds()). Multiple mutations can be batched together before calling this method.

This method exists because AceTime objects are mutable instead of immutable. If the objects were immutable, then each mutation would create a new object that would be automatically normalized, and an unnormalized object would not be visible outside of the library. Unfortunately, making the AceTime classes immutable causes the library to consume too much additional memory and consume too much CPU resources on 8-bit processors. So we must provide this normalize() method which must be called manually by the client code.

Definition at line 255 of file ZonedDateTime.h.

◆ printTo()

void ace_time::ZonedDateTime::printTo ( Print & printer ) const

Print ZonedDateTime to 'printer'.

This class does not implement the Printable interface to avoid increasing the size of the object from the additional virtual function.

Definition at line 12 of file ZonedDateTime.cpp.

◆ timeZone()

void ace_time::ZonedDateTime::timeZone ( const TimeZone & timeZone )

inline

Set the time zone.

Note that this does not convert a given ZonedDateTime into a different TimeZone. Use converToTimeZone() instead.

Definition at line 224 of file ZonedDateTime.h.

◆ toEpochDays()

int32_t ace_time::ZonedDateTime::toEpochDays ( ) const

inline

Return number of whole days since AceTime epoch taking into account the time zone.

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

Definition at line 273 of file ZonedDateTime.h.

◆ toEpochSeconds()

acetime_t ace_time::ZonedDateTime::toEpochSeconds ( ) const

inline

Return seconds since AceTime epoch taking into account the time zone.

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

Definition at line 287 of file ZonedDateTime.h.

◆ toUnixSeconds64()

int64_t ace_time::ZonedDateTime::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 print the unix seconds.

Definition at line 298 of file ZonedDateTime.h.

Friends And Related Function Documentation

◆ operator==

bool operator==	(	const ZonedDateTime &	a,
		const ZonedDateTime &	b
	)

friend

Return true if two ZonedDateTime objects are equal in all components.

Optimized for small changes in the less signficant fields, such as 'second' or 'minute'. The dayOfWeek is a derived field so it is not explicitly used to test equality, but it follows that if all the other fields are identical, then the dayOfWeek must also be equal.

Definition at line 355 of file ZonedDateTime.h.

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

/home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/ZonedDateTime.h
/home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/ZonedDateTime.cpp

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ compareTo()

◆ forComponents()

◆ forDateString() [1/2]

◆ forDateString() [2/2]

◆ forEpochSeconds()

◆ forLocalDateTime()

◆ forUnixSeconds64()

◆ normalize()

◆ printTo()

◆ timeZone()

◆ toEpochDays()

◆ toEpochSeconds()

◆ toUnixSeconds64()

Friends And Related Function Documentation

◆ operator==