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) const
	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) const
	Return a ISO 8601 timestamp as a `String` object. More...

DateTime	operator+ (const TimeSpan &span) const
	Add a TimeSpan to the DateTime object. More...

DateTime	operator- (const TimeSpan &span) const
	Subtract a TimeSpan from the DateTime object. More...

TimeSpan	operator- (const DateTime &right) const
	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

enum DateTime::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

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

◆ DateTime() [3/6]

DateTime::DateTime ( const DateTime & copy )

Copy constructor.

Parameters

copy	DateTime 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

date	Date string, e.g. "Apr 16 2020".
time	Time 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

date	Date PROGMEM string, e.g. F("Apr 16 2020").
time	Time 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

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

◆ 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:

DateTime(SECONDS_FROM_1970_TO_2000 + value)

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

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

opt	Format of the timestamp

Returns: Timestamp string, e.g. "2020-04-16T18:34:56".

◆ operator+()

DateTime DateTime::operator+ ( const TimeSpan & span ) const

Add a TimeSpan to the DateTime object.

Parameters

span	TimeSpan object

Returns: New DateTime object with span added to it.

◆ operator-() [1/2]

DateTime DateTime::operator- ( const TimeSpan & span ) const

Subtract a TimeSpan from the DateTime object.

Parameters

span	TimeSpan object

Returns: New DateTime object with span subtracted from it.

◆ operator-() [2/2]

TimeSpan DateTime::operator- ( const DateTime & right ) const

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

right The 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

right Comparison 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

right DateTime 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

right DateTime 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

right DateTime 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

right Comparison 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

right DateTime 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:

src/RTClib.h
src/RTClib.cpp

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ timestampOpt

Constructor & Destructor Documentation

◆ DateTime() [1/6]

◆ DateTime() [2/6]

◆ DateTime() [3/6]

◆ DateTime() [4/6]

◆ DateTime() [5/6]

◆ DateTime() [6/6]

Member Function Documentation

◆ isValid()

◆ toString()

◆ year()

◆ month()

◆ day()

◆ hour()

◆ twelveHour()

◆ isPM()

◆ minute()

◆ second()

◆ dayOfTheWeek()

◆ secondstime()

◆ unixtime()

◆ timestamp()

◆ operator+()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ operator<()

◆ operator>()

◆ operator<=()

◆ operator>=()

◆ operator==()

◆ operator!=()