Date and time class. More...

#include <DateTime.h>

Collaboration diagram for DateTime:

Classes
struct	ZoneInfo
	Basic information required when displaying or handling local times. More...

Public Member Functions
	DateTime ()=default
	Instantiate an uninitialised date and time object. More...

	DateTime (time_t time)
	Instantiate a date and time object from a Unix timestamp. More...

	operator time_t ()
	Get current Unix time. More...

void	setTime (time_t time)
	Set time using Unix timestamp. More...

void	setTime (uint8_t sec, uint8_t min, uint8_t hour, uint8_t day, uint8_t month, uint16_t year)
	Set time using time and date component values. More...

bool	fromHttpDate (const String &httpDate)
	Parse a HTTP full date and set time and date. More...

bool	fromISO8601 (const String &datetime, ZoneInfo *zone=nullptr)
	Parse an ISO8601 date/time string. More...

bool	isNull () const
	Check if time date object is initialised. More...

time_t	toUnixTime () const
	Get Unix time. More...

String	toShortDateString () const
	Get human readable date. More...

String	toShortTimeString (bool includeSeconds=false) const
	Get human readable time. More...

String	toFullDateTimeString () const
	Get human readable date and time. More...

String	toISO8601 (const ZoneInfo *zone=nullptr) const
	Get human readable date and time. More...

String	toHTTPDate () const
	Get human readable date and time. More...

void	addMilliseconds (long add)
	Add time to date time object. More...

String	format (const char formatString, const ZoneInfo zone=nullptr) const
	Create string formatted with time and date placeholders. More...

String	format (const String &formatString, const ZoneInfo *zone=nullptr) const
	Create string formatted with time and date placeholders. More...

Static Public Member Functions
static bool	fromHttpDate (const String &httpDate, time_t &time)
	Parse a HTTP full date string and return the time_t value. More...

static bool	fromISO8601 (const String &datetime, time_t &time, uint16_t &milliseconds, int16_t &offsetMins)
	Parse an ISO8601 date/time string and return discrete components. More...

static void	fromUnixTime (time_t timep, uint8_t psec, uint8_t pmin, uint8_t phour, uint8_t pday, uint8_t pwday, uint8_t pmonth, uint16_t *pyear)
	Convert from Unix time to individual time components. More...

static time_t	toUnixTime (int sec, int min, int hour, int day, uint8_t month, uint16_t year)
	Convert from individual time components to Unix time. More...

Utility functions
static bool	isLeapYear (uint16_t year)

static uint8_t	getMonthDays (uint8_t month, uint16_t year)

static String	getLocaleDayName (uint8_t day)

static String	getLocaleMonthName (uint8_t month)

static String	getIsoDayName (uint8_t day)

static String	getIsoMonthName (uint8_t month)

static uint16_t	getDaysInYear (uint16_t year)

Public Attributes
uint16_t	Year = 0
	Full Year number. More...

uint16_t	DayofYear = 0
	Day of year (0-365) More...

uint8_t	DayofWeek = 0
	Day of week (0-6 Sunday is day 0) More...

uint8_t	Month = 0
	Month (0-11 Jan is month 0) More...

uint8_t	Day = 0
	Day of month (1-31) More...

uint8_t	Hour = 0
	Hour (0-23) More...

uint8_t	Minute = 0
	Minute (0-59) More...

uint8_t	Second = 0
	Second (0-59) More...

uint16_t	Milliseconds = 0
	Milliseconds (0-999) More...

Detailed Description

Date and time class.

This class contains a 'broken-down' date and time into its individual year, month, etc. components.

Date and time functions mostly work with Unix time, the quantity of seconds since 00:00:00 1970-01-01. There is no support for leap seconds which are added (and in theory, removed) occasionally to compensate for earth rotation variation. This means that timespan calculation and free-running clocks may be inaccurate if they span leap seconds. To facilitate leap seconds, reference must be made to leap second table. This will not be done within the Sming framework and must be handled by application code if required.

See also: https://www.eecis.udel.edu/~mills/leap.html

Note: time_t is a signed 64-bit value for all architectures except Windows Host and esp32 ESP-IDF 4.x.

32-bit signed values support a range of +/-68 years; the Unix epoch is midnight 1 Jan 1970, so overflows at about 3am on 19 Jan 2038. The value is signed which allows dates prior to 1970 to be represented.

An unsigned 32-bit value can be used to store dates provided they are after 1970. These are good until February 2106.

Constructor & Destructor Documentation

◆ DateTime() [1/2]

DateTime::DateTime ( )

default

Instantiate an uninitialised date and time object.

◆ DateTime() [2/2]

DateTime::DateTime ( time_t time )

inline

Instantiate a date and time object from a Unix timestamp.

Parameters

time	Unix time to assign to object

Member Function Documentation

◆ addMilliseconds()

void DateTime::addMilliseconds ( long add )

Add time to date time object.

Parameters

add	Quantity of milliseconds to add to object

Note: This operation is computationally expensive, requiring conversion to and from time_t.

◆ format() [1/2]

String DateTime::format	(	const char *	formatString,
		const ZoneInfo *	zone = `nullptr`
	)		const

Create string formatted with time and date placeholders.

Parameters

formatString	String including date and time formatting
zone	Optional timezone information

Return values

String Formatted string

Note

Uses strftime style formatting, e.g. format("Today is %a, %d %b %Y") returns "Today is Mon, 10 Dec 2018"

Localisation may be implemented in libsming at compile time by setting LOCALE, e.g. LOCALE=LOCALE_DE_DE

Default localisation is EN_GB

Formatting parameters

Param	Description	Locale
%a	Abbreviated weekday name	*
%A	Full weekday name	*
%b	Abbreviated month name	*
%B	Full month name	*
%c	Locale preferred date and time format	*
%C	Century number (2 digits)
%d	Day of month as decimal number with leading zero (2 digits)
%D	US date format (mm/dd/yyyy)
%e	Day of month as decimal number with leading space (2 digits)
%F	ISO 8601 date format (YYYY-mm-dd)
%h	Equivalent to %b	*
%H	Hour as a decimal number using a 24-hour clock (range 00 to 23)
%I	Hour as a decimal number using a 12-hour clock (range 00 to 12)
%j	Day of the year as a decimal number (range 001 to 366)
%m	Month as a decimal number (range 01 to 12)
%M	Minute as a decimal number (range 00 to 59)
%n	Newline
%p	Meridiem indicator: AM or PM. Midnight is AM and noon is PM
%r	Locale 12-hour clock time notation. This is equivalent to %I:%M:%S %p	*
%R	Time in 24-hour notation (HH:MM)
%S	Second as a decimal number (range 00 to 60)
%t	Horizontal tab
%T	Time in 24-hour notation (HH:MM:SS)
%u	Day of the week as a decimal (range 1 to 7, Monday is 1)
%U	Week number as a decimal number (range 00 to 53, first Sunday as the first day of week 01)
%V	ISO 8601 week number as a decimal number (range 01 to 53, where week 1 is the first week including a Thursday)
%w	Day of the week as a decimal (range 0 to 6, Sunday is 0)
%W	Week number as a decimal number (range 00 to 53, first Monday as the first day of week 01)
%x	Locale preferred date representation	*
%X	Locale preferred time representation	*
%y	Year as a decimal number without a century (range 00 to 99)
%Y	Year as a decimal number (range 1970 to ...)
%z	Timezone offset in Â±HHMM format (1)
%%:z	Timezone offset in Â±HH:MM format (1)
%Z	Timezone tag (1)
%%	Percent sign

(1) If zone is not provided then the z, %:z and Z placeholders produce empty text

◆ format() [2/2]

String DateTime::format	(	const String &	formatString,
		const ZoneInfo *	zone = `nullptr`
	)		const

inline

Create string formatted with time and date placeholders.

Parameters

formatString	String including date and time formatting
zone	Optional zone information containing additional format information

Return values

String Formatted string

See also: See format(const char*, const ZoneInfo*) for parameter details

◆ fromHttpDate() [1/2]

bool DateTime::fromHttpDate ( const String & httpDate )

Parse a HTTP full date and set time and date.

Parameters

httpDate HTTP full date in RFC 1123 format, e.g. Sun, 06 Nov 1994 08:49:37 GMT

Return values

bool	True on success

See also: See fromHttpDate(const String& time_t&)

◆ fromHttpDate() [2/2]

static bool DateTime::fromHttpDate	(	const String &	httpDate,
		time_t &	time
	)

static

Parse a HTTP full date string and return the time_t value.

Parameters

httpDate	HTTP full date in RFC 1123 format, e.g. Sun, 06 Nov 1994 08:49:37 GMT
time	On success, contains the decoded value

Return values

bool	True on success

Note: Also supports obsolete RFC 850 date format, e.g. Sunday, 06-Nov-94 08:49:37 GMT where 2 digit year represents range 1970-2069; GMT suffix is optional and is always assumed / ignored

◆ fromISO8601() [1/2]

static bool DateTime::fromISO8601	(	const String &	datetime,
		time_t &	time,
		uint16_t &	milliseconds,
		int16_t &	offsetMins
	)

static

Parse an ISO8601 date/time string and return discrete components.

Parameters

datetime	Date and optional time in ISO8601 format, e.g. "1994-11-06", "1994-11-06T08:49:37". Separators are optional.
time	The time_t component
milliseconds	Additional milliseconds value
offsetMins	Any offset specified in the time

Return values

bool	True on success

See also: See https://en.wikipedia.org/wiki/ISO_8601

Basic format doesn't include separators, whereas Extended format does. Both are supported.

Acceptable date formats:

YYYY-MM-DD or YYYYMMDD
YYYY-MM (but not YYYYMM)

Acceptable time formats:

Thh:mm:ss.sss or Thhmmss.sss
Thh:mm:ss or Thhmmss
Thh:mm.mmm or Thhmm.mmm
Thh:mm or Thhmm
Thh.hhh
Thh

Times with an offset:

<time>Z <time>Â±hh:mm <time>Â±hhmm <time>Â±hh

◆ fromISO8601() [2/2]

bool DateTime::fromISO8601	(	const String &	datetime,
		ZoneInfo *	zone = `nullptr`
	)

Parse an ISO8601 date/time string.

Parameters

datetime	Date and optional time in ISO8601 format, e.g. "1994-11-06", "1994-11-06T08:49:37". Separators are optional.
zone	If provided, on success the `offsetMins` field will contain the time offset (0 for GMT) and the decoded DateTime will be 'local'. If zone is null then the decoded datetime will be UTC.

Return values

bool	True on success. On failure, value of DateTime is unchanged.

See also: See fromISO8601(const String&, time_t&, uint16_t&, int16_t&)

◆ fromUnixTime()

static void DateTime::fromUnixTime	(	time_t	timep,
		uint8_t *	psec,
		uint8_t *	pmin,
		uint8_t *	phour,
		uint8_t *	pday,
		uint8_t *	pwday,
		uint8_t *	pmonth,
		uint16_t *	pyear
	)

static

Convert from Unix time to individual time components.

Parameters

timep	Unix time date value to convert
psec	Pointer to integer to hold resulting seconds
pmin	Pointer to integer to hold resulting minutes
phour	Pointer to integer to hold resulting hour
pday	Pointer to integer to hold resulting day of month
pwday	Pointer to integer to hold resulting day of week
pmonth	Pointer to integer to hold resulting month
pyear	Pointer to integer to hold resulting year

Note: Pass the Unix timedate value and pointers to existing integers. The integers are updated with the converted values; This static function may be used without instantiating a DateTime object, e.g. DateTime::convertFromUnixTime(...);; Unix time does not account for leap seconds.; All of the return values are optional, specify nullptr if not required

◆ getDaysInYear()

static uint16_t DateTime::getDaysInYear ( uint16_t year )

static

◆ getIsoDayName()

static String DateTime::getIsoDayName ( uint8_t day )

static

◆ getIsoMonthName()

static String DateTime::getIsoMonthName ( uint8_t month )

static

◆ getLocaleDayName()

static String DateTime::getLocaleDayName ( uint8_t day )

static

◆ getLocaleMonthName()

static String DateTime::getLocaleMonthName ( uint8_t month )

static

◆ getMonthDays()

static uint8_t DateTime::getMonthDays	(	uint8_t	month,
		uint16_t	year
	)

static

◆ isLeapYear()

static bool DateTime::isLeapYear ( uint16_t year )

static

◆ isNull()

bool DateTime::isNull ( ) const

Check if time date object is initialised.

Return values

True	if object has no value. False if initialised.

◆ operator time_t()

DateTime::operator time_t ( )

inline

Get current Unix time.

Return values

time_t Quantity of seconds since 00:00:00 1970-01-01

◆ setTime() [1/2]

void DateTime::setTime ( time_t time )

Set time using Unix timestamp.

Parameters

time	Unix time to set object time to

◆ setTime() [2/2]

void DateTime::setTime	(	uint8_t	sec,
		uint8_t	min,
		uint8_t	hour,
		uint8_t	day,
		uint8_t	month,
		uint16_t	year
	)

inline

Set time using time and date component values.

Parameters

sec	Seconds
min	Minutes
hour	Hour
day	Day of month
month	Month (0=Jan, 11=Dec)
year	Year

◆ toFullDateTimeString()

String DateTime::toFullDateTimeString ( ) const

Get human readable date and time.

Return values

String Date and time in format DD.MM.YYYY hh:mm:ss

◆ toHTTPDate()

String DateTime::toHTTPDate ( ) const

Get human readable date and time.

Return values

String Date and time in format DDD, DD MMM YYYY hh:mm:ss GMT

◆ toISO8601()

String DateTime::toISO8601 ( const ZoneInfo * zone = nullptr ) const

Get human readable date and time.

Parameters

zone	Optional timezone information

Return values

String Date and time

See also: See fromISO8601() for string formats

Note: If zone isn't specified then UTC is assumed and timezone indicator 'Z' will be appended

◆ toShortDateString()

String DateTime::toShortDateString ( ) const

Get human readable date.

Return values

String Date in requested format, e.g. DD.MM.YYYY

◆ toShortTimeString()

String DateTime::toShortTimeString ( bool includeSeconds = false ) const

Get human readable time.

Parameters

includeSeconds True to include seconds (Default: false)

Return values

String Time in format hh:mm or hh:mm:ss

◆ toUnixTime() [1/2]

time_t DateTime::toUnixTime ( ) const

Get Unix time.

Return values

time_t Unix time, quantity of seconds since 00:00:00 1970-01-01

Note: Unix time does not account for leap seconds.

◆ toUnixTime() [2/2]

static time_t DateTime::toUnixTime	(	int	sec,
		int	min,
		int	hour,
		int	day,
		uint8_t	month,
		uint16_t	year
	)

static

Convert from individual time components to Unix time.

Parameters

sec	Seconds
min	Minutes
hour	Hours
day	Days
month	Month (0-11, Jan=0, Feb=1, ...Dec=11), or enum (dtJanuary, ...)
year	Year, either full 4 digit year or 2 digits for 2000-2068

Return values

time_t Number of seconds since unix epoch (Midnight, Jan 1 1970)

Note: Seconds, minutes, hours and days may be any value, e.g. to calculate the value for 300 days since 1970 (epoch), set day=300; This static function may be used without instantiating a DateTime object, e.g. time_t unixTime = DateTime::toUnixTime(...);; Unix time does not account for leap seconds.

Member Data Documentation

◆ Day

uint8_t DateTime::Day = 0

Day of month (1-31)

◆ DayofWeek

uint8_t DateTime::DayofWeek = 0

Day of week (0-6 Sunday is day 0)

◆ DayofYear

uint16_t DateTime::DayofYear = 0

Day of year (0-365)

◆ Hour

uint8_t DateTime::Hour = 0

Hour (0-23)

◆ Milliseconds

uint16_t DateTime::Milliseconds = 0

Milliseconds (0-999)

◆ Minute

uint8_t DateTime::Minute = 0

Minute (0-59)

◆ Month

uint8_t DateTime::Month = 0

Month (0-11 Jan is month 0)

◆ Second

uint8_t DateTime::Second = 0

Second (0-59)

◆ Year

uint16_t DateTime::Year = 0

Full Year number.

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

DateTime.h

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DateTime() [1/2]

◆ DateTime() [2/2]

Member Function Documentation

◆ addMilliseconds()

◆ format() [1/2]

◆ format() [2/2]

◆ fromHttpDate() [1/2]

◆ fromHttpDate() [2/2]

◆ fromISO8601() [1/2]

◆ fromISO8601() [2/2]

◆ fromUnixTime()

◆ getDaysInYear()

◆ getIsoDayName()

◆ getIsoMonthName()

◆ getLocaleDayName()

◆ getLocaleMonthName()

◆ getMonthDays()

◆ isLeapYear()

◆ isNull()

◆ operator time_t()

◆ setTime() [1/2]

◆ setTime() [2/2]

◆ toFullDateTimeString()

◆ toHTTPDate()

◆ toISO8601()

◆ toShortDateString()

◆ toShortTimeString()

◆ toUnixTime() [1/2]

◆ toUnixTime() [2/2]

Member Data Documentation

◆ Day

◆ DayofWeek

◆ DayofYear

◆ Hour

◆ Milliseconds

◆ Minute

◆ Month

◆ Second

◆ Year