Date and time class. More...

#include <DateTime.h>

Collaboration diagram for DateTime:

Public Member Functions

 DateTime ()
 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)
 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
 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
 Create string formatted with time and date placeholders. More...
 
String format (const String &formatString) const
 Create string formatted with time and date placeholders. More...
 

Static Public Member Functions

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

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 ( )
inline

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
timeUnix time to assign to object

Member Function Documentation

◆ addMilliseconds()

void DateTime::addMilliseconds ( long  add)

Add time to date time object.

Parameters
addQuantity of milliseconds to add to object

◆ format() [1/2]

String DateTime::format ( const char *  formatString) const

Create string formatted with time and date placeholders.

Parameters
formatStringString including date and time formatting
Return values
StringFormatted 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 ...)
%% Percent sign

◆ format() [2/2]

String DateTime::format ( const String formatString) const
inline

Create string formatted with time and date placeholders.

Parameters
formatStringString including date and time formatting
Return values
StringFormatted string
Note
see format(const char*) for parameter details

◆ fromHttpDate()

bool DateTime::fromHttpDate ( const String httpDate)

Parse a HTTP full date and set time and date.

Parameters
httpDateHTTP full date in RFC 1123 format, e.g. Sun, 06 Nov 1994 08:49:37 GMT
Return values
boolTrue 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()

bool DateTime::fromISO8601 ( const String datetime)

Parse an ISO8601 date/time string.

Parameters
datetimeDate and optional time in ISO8601 format, e.g. "1994-11-06", "1994-11-06T08:49:37". Separators are optional.
Return values
boolTrue on success
See also
See https://en.wikipedia.org/wiki/ISO_8601

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

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

◆ 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
timepUnix time date value to convert
psecPointer to integer to hold resulting seconds
pminPointer to integer to hold resulting minutes
phourPointer to integer to hold resulting hour
pdayPointer to integer to hold resulting day of month
pwdayPointer to integer to hold resulting day of week
pmonthPointer to integer to hold resulting month
pyearPointer to integer to hold resulting year
Note
This is a more compact version of the C library localtime function
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(...);
32-bit Unix time has year 2036 issue.
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
Trueif object has no value. False if initialised.

◆ operator time_t()

DateTime::operator time_t ( )
inline

Get current Unix time.

Return values
time_tQuantity of seconds since 00:00:00 1970-01-01

◆ setTime() [1/2]

void DateTime::setTime ( time_t  time)

Set time using Unix timestamp.

Parameters
timeUnix 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
secSeconds
minMinutes
hourHour
dayDay of month
monthMonth (0=Jan, 11=Dec)
yearYear

◆ toFullDateTimeString()

String DateTime::toFullDateTimeString ( ) const

Get human readable date and time.

Return values
StringDate and time in format DD.MM.YYYY hh:mm:ss

◆ toHTTPDate()

String DateTime::toHTTPDate ( ) const

Get human readable date and time.

Return values
StringDate and time in format DDD, DD MMM YYYY hh:mm:ss GMT

◆ toISO8601()

String DateTime::toISO8601 ( ) const

Get human readable date and time.

Return values
StringDate and time in format YYYY-MM-DDThh:mm:ssZ

◆ toShortDateString()

String DateTime::toShortDateString ( ) const

Get human readable date.

Return values
StringDate in requested format, e.g. DD.MM.YYYY

◆ toShortTimeString()

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

Get human readable time.

Parameters
includeSecondsTrue to include seconds (Default: false)
Return values
StringTime in format hh:mm or hh:mm:ss

◆ toUnixTime() [1/2]

time_t DateTime::toUnixTime ( ) const

Get Unix time.

Return values
time_tUnix 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
secSeconds
minMinutes
hourHours
dayDays
monthMonth (0-11, Jan=0, Feb=1, ...Dec=11), or enum (dtJanuary, ...)
yearYear, either full 4 digit year or 2 digits for 2000-2068
Return values
time_tNumber 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: