RTClib
Public Types | Public Member Functions | Protected Attributes | List of all members
DateTime Class Reference

Simple general-purpose date/time class (no TZ / DST / leap seconds). More...

#include <RTClib.h>

Public Types

enum  timestampOpt { TIMESTAMP_FULL, TIMESTAMP_TIME, TIMESTAMP_DATE }
 

Public Member Functions

 DateTime (uint32_t t=SECONDS_FROM_1970_TO_2000)
 Constructor from Unix time. More...
 
 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). More...
 
 DateTime (const DateTime &copy)
 Copy constructor. More...
 
 DateTime (const char *date, const char *time)
 Constructor for generating the build time. More...
 
 DateTime (const __FlashStringHelper *date, const __FlashStringHelper *time)
 Memory friendly constructor for generating the build time. More...
 
 DateTime (const char *iso8601date)
 Constructor for creating a DateTime from an ISO8601 date string. More...
 
bool isValid () const
 Check whether this DateTime is valid. More...
 
char * toString (char *buffer)
 Writes the DateTime as a string in a user-defined format. More...
 
uint16_t year () const
 Return the year. More...
 
uint8_t month () const
 Return the month. More...
 
uint8_t day () const
 Return the day of the month. More...
 
uint8_t hour () const
 Return the hour. More...
 
uint8_t twelveHour () const
 Return the hour in 12-hour format. More...
 
uint8_t isPM () const
 Return whether the time is PM. More...
 
uint8_t minute () const
 Return the minute. More...
 
uint8_t second () const
 Return the second. More...
 
uint8_t dayOfTheWeek () const
 Return the day of the week. More...
 
uint32_t secondstime () const
 Convert the DateTime to seconds since 1 Jan 2000. More...
 
uint32_t unixtime (void) const
 Return Unix time: seconds since 1 Jan 1970. More...
 
String timestamp (timestampOpt opt=TIMESTAMP_FULL)
 Return a ISO 8601 timestamp as a String object. More...
 
DateTime operator+ (const TimeSpan &span)
 Add a TimeSpan to the DateTime object. More...
 
DateTime operator- (const TimeSpan &span)
 Subtract a TimeSpan from the DateTime object. More...
 
TimeSpan operator- (const DateTime &right)
 Subtract one DateTime from another. More...
 
bool operator< (const DateTime &right) const
 Test if one DateTime is less (earlier) than another. More...
 
bool operator> (const DateTime &right) const
 Test if one DateTime is greater (later) than another. More...
 
bool operator<= (const DateTime &right) const
 Test if one DateTime is less (earlier) than or equal to another. More...
 
bool operator>= (const DateTime &right) const
 Test if one DateTime is greater (later) than or equal to another. More...
 
bool operator== (const DateTime &right) const
 Test if two DateTime objects are equal. More...
 
bool operator!= (const DateTime &right) const
 Test if two DateTime objects are not equal. More...
 

Protected Attributes

uint8_t yOff
 Year offset from 2000.
 
uint8_t m
 Month 1-12.
 
uint8_t d
 Day 1-31.
 
uint8_t hh
 Hours 0-23.
 
uint8_t mm
 Minutes 0-59.
 
uint8_t ss
 Seconds 0-59.
 

Detailed Description

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.

Member Enumeration Documentation

◆ timestampOpt

Format of the ISO 8601 timestamp generated by timestamp(). Each option corresponds to a toString() format as follows:

Enumerator
TIMESTAMP_FULL 

YYYY-MM-DDThh:mm:ss

TIMESTAMP_TIME 

hh:mm:ss

TIMESTAMP_DATE 

YYYY-MM-DD

Constructor & Destructor Documentation

◆ DateTime() [1/6]

DateTime::DateTime ( uint32_t  t = SECONDS_FROM_1970_TO_2000)

Constructor from Unix time.

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
tTime 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
yearEither the full year (range: 2000–2099) or the offset from year 2000 (range: 0–99).
monthMonth number (1–12).
dayDay of the month (1–31).
hour,min,secHour (0–23), minute (0–59) and second (0–59).

◆ DateTime() [3/6]

DateTime::DateTime ( const DateTime copy)

Copy constructor.

Parameters
copyDateTime to copy.

◆ DateTime() [4/6]

DateTime::DateTime ( const char *  date,
const char *  time 
)

Constructor for generating the build time.

This constructor expects its parameters to be strings in the format generated by the compiler's preprocessor macros __DATE__ and __TIME__. Usage:

DateTime buildTime(__DATE__, __TIME__);
Note
The F() macro can be used to reduce the RAM footprint, see the next constructor.
Parameters
dateDate string, e.g. "Apr 16 2020".
timeTime string, e.g. "18:34:56".

◆ DateTime() [5/6]

DateTime::DateTime ( const __FlashStringHelper *  date,
const __FlashStringHelper *  time 
)

Memory friendly constructor for generating the build time.

This version is intended to save RAM by keeping the date and time strings in program memory. Use it with the F() macro:

DateTime buildTime(F(__DATE__), F(__TIME__));
Parameters
dateDate PROGMEM string, e.g. F("Apr 16 2020").
timeTime PROGMEM string, e.g. F("18:34:56").

◆ DateTime() [6/6]

DateTime::DateTime ( const char *  iso8601dateTime)

Constructor for creating a DateTime from an ISO8601 date string.

This constructor expects its parameters to be a string in the https://en.wikipedia.org/wiki/ISO_8601 format, e.g:

"2020-06-25T15:29:37"

Usage:

DateTime dt("2020-06-25T15:29:37");
Note
The year must be > 2000, as only the yOff is considered.
Parameters
iso8601dateTimeA dateTime string in iso8601 format, e.g. "2020-06-25T15:29:37".

Member Function Documentation

◆ isValid()

bool DateTime::isValid ( ) const

Check whether this DateTime is valid.

Returns
true if valid, false if not.

◆ toString()

char * DateTime::toString ( char *  buffer)

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

◆ secondstime()

uint32_t DateTime::secondstime ( void  ) const

Convert the DateTime to seconds since 1 Jan 2000.

The result can be converted back to a DateTime with:

Returns
Number of seconds since 2000-01-01 00:00:00.

◆ unixtime()

uint32_t DateTime::unixtime ( void  ) const

Return Unix time: seconds since 1 Jan 1970.

See also
The DateTime::DateTime(uint32_t) constructor is the converse of this method.
Returns
Number of seconds since 1970-01-01 00:00:00.

◆ timestamp()

String DateTime::timestamp ( timestampOpt  opt = TIMESTAMP_FULL)

Return a ISO 8601 timestamp as a String object.

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.
Parameters
optFormat of the timestamp
Returns
Timestamp string, e.g. "2020-04-16T18:34:56".

◆ operator+()

DateTime DateTime::operator+ ( const TimeSpan span)

Add a TimeSpan to the DateTime object.

Parameters
spanTimeSpan object
Returns
New DateTime object with span added to it.

◆ operator-() [1/2]

DateTime DateTime::operator- ( const TimeSpan span)

Subtract a TimeSpan from the DateTime object.

Parameters
spanTimeSpan object
Returns
New DateTime object with span subtracted from it.

◆ operator-() [2/2]

TimeSpan DateTime::operator- ( const DateTime right)

Subtract one DateTime from another.

Note
Since a TimeSpan cannot be negative, the subtracted DateTime should be less (earlier) than or equal to the one it is subtracted from.
Parameters
rightThe DateTime object to subtract from self (the left object)
Returns
TimeSpan of the difference between DateTimes.

◆ operator<()

bool DateTime::operator< ( const DateTime right) const

Test if one DateTime is less (earlier) than another.

Author
Anton Rieutskyi
Warning
if one or both DateTime objects are invalid, returned value is meaningless
See also
use isValid() method to check if DateTime object is valid
Parameters
rightComparison DateTime object
Returns
True if the left DateTime is earlier than the right one, false otherwise.

◆ operator>()

bool DateTime::operator> ( const DateTime right) const
inline

Test if one DateTime is greater (later) than another.

Warning
if one or both DateTime objects are invalid, returned value is meaningless
See also
use isValid() method to check if DateTime object is valid
Parameters
rightDateTime object to compare
Returns
True if the left DateTime is later than the right one, false otherwise

◆ operator<=()

bool DateTime::operator<= ( const DateTime right) const
inline

Test if one DateTime is less (earlier) than or equal to another.

Warning
if one or both DateTime objects are invalid, returned value is meaningless
See also
use isValid() method to check if DateTime object is valid
Parameters
rightDateTime object to compare
Returns
True if the left DateTime is earlier than or equal to the right one, false otherwise

◆ operator>=()

bool DateTime::operator>= ( const DateTime right) const
inline

Test if one DateTime is greater (later) than or equal to another.

Warning
if one or both DateTime objects are invalid, returned value is meaningless
See also
use isValid() method to check if DateTime object is valid
Parameters
rightDateTime object to compare
Returns
True if the left DateTime is later than or equal to the right one, false otherwise

◆ operator==()

bool DateTime::operator== ( const DateTime right) const

Test if two DateTime objects are equal.

Author
Anton Rieutskyi
Warning
if one or both DateTime objects are invalid, returned value is meaningless
See also
use isValid() method to check if DateTime object is valid
Parameters
rightComparison DateTime object
Returns
True if both DateTime objects are the same, false otherwise.

◆ operator!=()

bool DateTime::operator!= ( const DateTime right) const
inline

Test if two DateTime objects are not equal.

Warning
if one or both DateTime objects are invalid, returned value is meaningless
See also
use isValid() method to check if DateTime object is valid
Parameters
rightDateTime object to compare
Returns
True if the two objects are not equal, false if they are

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