Simple general-purpose date/time class (no TZ / DST / leap seconds).
This class stores date and time information in a broken-down form, as
a tuple (year, month, day, hour, minute, second). The day of the week
is not stored, but computed on request. The class has no notion of time
zones, daylight saving time, or
leap seconds
: time is stored in whatever time zone the user chooses to use.
The class supports dates in the range from 1 Jan 2000 to 31 Dec 2099 inclusive.
This builds a
DateTime
from an integer specifying the number of seconds elapsed since the
epoch: 1970-01-01 00:00:00. This number is analogous to Unix time, with
two small differences:
The Unix epoch is specified to be at 00:00:00
UTC
,
whereas this class has no notion of time zones. The epoch used in this
class is then at 00:00:00 on whatever time zone the user chooses to use,
ignoring changes in DST.
Unix time is conventionally represented with signed numbers, whereas
this constructor takes an unsigned argument. Because of this, it does
not
suffer from the
year 2038 problem
.
If called without argument, it returns the earliest time representable by this class: 2000-01-01 00:00:00.
See also
The
unixtime()
method is the converse of this constructor.
Parameters
t
Time elapsed in seconds since 1970-01-01 00:00:00.
DateTime() [2/6]
DateTime::DateTime
(
uint16_t
year
,
uint8_t
month
,
uint8_t
day
,
uint8_t
hour
=
0
,
uint8_t
min
=
0
,
uint8_t
sec
=
0
)
Constructor from (year, month, day, hour, minute, second).
Warning
If the provided parameters are not valid (e.g. 31 February), the constructed
DateTime
will be invalid.
See also
The
isValid()
method can be used to test whether the constructed
DateTime
is valid.
Parameters
year
Either the full year (range: 2000–2099) or the offset from year 2000 (range: 0–99).
month
Month number (1–12).
day
Day of the month (1–31).
hour,min,sec
Hour (0–23), minute (0–59) and second (0–59).
/*F********************************************************************
*
**********************************************************************/
char *DateTime::
toString ( char * buffer ) const
Writes the
DateTime
as a string in a user-defined format.
The buffer parameter should be initialized by the caller with a string specifying the requested format. This format string may contain any of the following specifiers:
specifier
output
YYYY
the year as a 4-digit number (2000–2099)
YY
the year as a 2-digit number (00–99)
MM
the month as a 2-digit number (01–12)
MMM
the abbreviated English month name ("Jan"–"Dec")
DD
the day as a 2-digit number (01–31)
DDD
the abbreviated English day of the week ("Mon"–"Sun")
AP
either "AM" or "PM"
ap
either "am" or "pm"
hh
the hour as a 2-digit number (00–23 or 01–12)
mm
the minute as a 2-digit number (00–59)
ss
the second as a 2-digit number (00–59)
If either "AP" or "ap" is used, the "hh" specifier uses 12-hour mode
(range: 01–12). Otherwise it works in 24-hour mode (range: 00–23).
The specifiers within
buffer
will be overwritten with the appropriate values from the
DateTime
. Any characters not belonging to one of the above specifiers are left as-is.
Example
: The format "DDD, DD MMM YYYY hh:mm:ss" generates an output of the form "Thu, 16 Apr 2020 18:34:56.
See also
The
timestamp()
method provides similar functionnality, but it returns a
String
object and supports a limited choice of predefined formats.
Parameters
[in,out]
buffer
Array of
char
for holding the format description and the formatted
DateTime
.
Before calling this method, the buffer should be initialized by the
user with the format string. The method will overwrite the buffer with
the formatted date and/or time.
Returns
A pointer to the provided buffer. This is returned for convenience, in order to enable idioms such as
Serial.println(now.toString(buffer));
year()
uint16_t DateTime::year
(
)
const
inline
Return the year.
Returns
Year (range: 2000–2099).
month()
uint8_t DateTime::month
(
)
const
inline
Return the month.
Returns
Month number (1–12).
day()
uint8_t DateTime::day
(
)
const
inline
Return the day of the month.
Returns
Day of the month (1–31).
hour()
uint8_t DateTime::hour
(
)
const
inline
Return the hour.
Returns
Hour (0–23).
twelveHour()
uint8_t DateTime::twelveHour
(
)
const
Return the hour in 12-hour format.
Returns
Hour (1–12).
isPM()
uint8_t DateTime::isPM
(
)
const
inline
Return whether the time is PM.
Returns
0 if the time is AM, 1 if it's PM.
minute()
uint8_t DateTime::minute
(
)
const
inline
Return the minute.
Returns
Minute (0–59).
second()
uint8_t DateTime::second
(
)
const
inline
Return the second.
Returns
Second (0–59).
dayOfTheWeek()
uint8_t DateTime::dayOfTheWeek
(
)
const
Return the day of the week.
Returns
Day of week as an integer from 0 (Sunday) to 6 (Saturday).
The generated timestamp conforms to one of the predefined, ISO 8601-compatible formats for representing the date (if
opt
is
TIMESTAMP_DATE
), the time (
TIMESTAMP_TIME
), or both (
TIMESTAMP_FULL
).
See also
The
toString()
method provides more general string formatting.