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.

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

const LocalDate &	localDate () const
	Return the LocalDate.

const LocalTime &	localTime () const
	Return the LocalTime.

int32_t	toEpochDays () const
	Return number of whole days since AceTime epoch. 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 the current AceTime epoch defined by Epoch::currentEpochYear(). More...

int64_t	toUnixSeconds64 () const
	Return 64-bit seconds from Unix epoch 1970-01-01 00:00:00 UTC, after assuming that the date and time components are in UTC timezone. More...

int8_t	compareTo (const LocalDateTime &that) const
	Compare 'this' LocalDateTime with 'that' LocalDateTime, and return (<0, 0, >0) according to whether 'this' occurs (before, same as, after) 'that'. More...

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, uint8_t fold=0)
	Factory method using separated date and time components. More...

static LocalDateTime	forEpochSeconds (acetime_t epochSeconds, uint8_t fold=0)
	Factory method. More...

static LocalDateTime	forUnixSeconds64 (int64_t unixSeconds, uint8_t fold=0)
	Factory method that takes the 64-bit number of seconds since Unix Epoch of 1970-01-01. More...

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

static LocalDateTime	forDateString (const __FlashStringHelper *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	forError ()
	Factory method that returns an instance where isError() returns true.

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). The 'fold' parameter was inspired by the datetime package in Python 3.6.

Definition at line 30 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 148 of file LocalDateTime.h.

Member Function Documentation

◆ compareTo()

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

inline

Compare 'this' LocalDateTime with 'that' LocalDateTime, and return (<0, 0, >0) according to whether 'this' occurs (before, same as, after) 'that'.

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

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

inlinestatic

Factory method using separated date and time components.

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

Definition at line 44 of file LocalDateTime.h.

◆ forDateString() [1/2]

LocalDateTime ace_time::LocalDateTime::forDateString ( const __FlashStringHelper * dateString )

static

Factory method.

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

Definition at line 47 of file LocalDateTime.cpp.

◆ forDateString() [2/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 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 strings will parse to the exactly same LocalDateTime object: "2018-08-31T13:48:01" and "2018/08/31 13.48.01"

Parameters

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

Definition at line 40 of file LocalDateTime.cpp.

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

◆ forEpochSeconds()

static LocalDateTime ace_time::LocalDateTime::forEpochSeconds	(	acetime_t	epochSeconds,
		uint8_t	fold = `0`
	)

inlinestatic

Factory method.

Create the various components of the LocalDateTime from the epochSeconds.

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

Parameters

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 63 of file LocalDateTime.h.

◆ forUnixSeconds64()

static LocalDateTime ace_time::LocalDateTime::forUnixSeconds64	(	int64_t	unixSeconds,
		uint8_t	fold = `0`
	)

inlinestatic

Factory method that takes the 64-bit number of seconds since Unix Epoch of 1970-01-01.

Valid until the 64-bit unixSeconds reaches the equivalent of 2068-01-19T03:14:07 UTC. Returns LocalDateTime::forError() if unixSeconds is invalid.

Definition at line 90 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 16 of file LocalDateTime.cpp.

◆ toEpochDays()

int32_t ace_time::LocalDateTime::toEpochDays ( ) const

inline

Return number of whole days since AceTime epoch.

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

Definition at line 211 of file LocalDateTime.h.

◆ toEpochSeconds()

acetime_t ace_time::LocalDateTime::toEpochSeconds ( ) const

inline

Return seconds since the current AceTime epoch defined by Epoch::currentEpochYear().

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

Returns LocalDate::kInvalidEpochSeconds if isError() is true, or the epochSeconds is out of range.

Definition at line 230 of file LocalDateTime.h.

◆ toUnixSeconds64()

int64_t ace_time::LocalDateTime::toUnixSeconds64 ( ) const

inline

Return 64-bit seconds from Unix epoch 1970-01-01 00:00:00 UTC, after assuming that the date and time components are in UTC timezone.

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 of a given ISO8601 date.

Definition at line 245 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 297 of file LocalDateTime.h.

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

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

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ LocalDateTime()

Member Function Documentation

◆ compareTo()

◆ forComponents()

◆ forDateString() [1/2]

◆ forDateString() [2/2]

◆ forDateStringChainable()

◆ forEpochSeconds()

◆ forUnixSeconds64()

◆ printTo()

◆ toEpochDays()

◆ toEpochSeconds()

◆ toUnixSeconds64()

Friends And Related Function Documentation

◆ operator==