Detailed Description

This class represents a point in time, both a date and a time.

It can be used to store date-time values, add or subtract time, compare times and convert to/from string representations. Time is stored as the number of seconds (with fractions) from 1970-01-01 0:00:00 UTC ignoring leap seconds.

Date today = Date::now();                     // the current date and time
String stoday = today.toString();             // an ISO-8601 formatted representation
String compact = today.toString(Date::SHORT); // without '-' or ':' symbols
 
Date fileTime = File("x.txt").lastModified();
double age = today - fileTime;                // file modified 'age' seconds ago

Dates can be initialized by parsing formatted strings, and can be encoded as strings. The format can be ISO-8601 or the fixed-length RFC2616 format used in the HTTP protocol, or any format, given a format specification:

Date future("1/05/2030 12:30", "D/M/Y?h:m");    // specific format
Date httptime("Tue, 30 Nov 2021 00:31:10 GMT"); // as in HTTP (only GMT)
Date isotime("2021-11-29T23:31:10.25+01:30");   // ISO 8601

Dates can be created by their components, either as local time or UTC time:

Date d1(2016, 12, 31, 12, 30, 00); // Local 2016-12-31 12:30:00

Date d2(Date::UTC, 2016, 12, 31, 12, 30, 00); // UTC 2016-12-31 12:30:00Z

And its components (year, month, etc.) can be extracted with the functions year(), month(), day(), etc. These always return them in local time. But if many components or UTC are needed, it is faster to use the split() or splitUTC() functions. These two return all components in a struct.

int year = d2.year(), month = d2.month(), day = d2.day(), hours = d2.hours();
 
DateData d = d2.split();
int y = d.year, month = d.month, day = d.day, hours = d.hours;

#include <Date.h>

Public Types
enum	Format { LONG , SHORT , DATE_ONLY , HTTP , FULL }
	Format for toString() and toUTCString() More...

Public Member Functions
	Date (const String &s)
	Constructs a Date from a string representation in ISO-8601 format ("yyyy-mm-ddThh:mm:ss") or in RFC 1123 format (like HTTP, "Thu, 18 May 2017 03:24:12 GMT"). More...

	Date (const String &s, const String &fmt)
	Constructs a Date from the string `s` using `fmt` as format specification. More...

	Date (int y, int m, int d, int h=0, int mn=0, int s=0)
	Creates a date-time from the given components, from year to seconds.

	Date (Zone z, int y, int m, int d, int h=0, int mn=0, int s=0)
	Creates a date-time from the given components, from year to seconds, in LOCAL or UTC time, depending on specified zone.

	operator String () const
	Returns a string representation of this date in ISO-8601 format.

String	toString (Format f=LONG) const
	Returns a string representation of this date in ISO-8601 format. More...

String	toUTCString (Format f=LONG) const
	Returns a string representation of this date in UTC in ISO-8601 format. More...

double	time () const
	Returns the time value of this date-time (in seconds)

DateData	split () const
	Splits this date into components year, month, day, hour, etc in local time.

DateData	splitUTC () const
	Splits this date into components year, month, day, hour, etc in UTC time zone.

int	year () const
	Returns the year of this date.

int	month () const
	Returns the month of this date.

int	day () const
	Returns the day of this date.

int	hours () const
	Returns the hours of this date-time.

int	minutes () const
	Returns the minutes of this date-time.

int	seconds () const
	Returns the seconds of this date-time.

int	weekDay () const
	Returns the week day number of this date (0=Sunday)

bool	operator== (const Date &d) const
	Compares two date-times for equality within a millisecond.

bool	operator< (const Date &d) const
	Compares two date-times returning true if this is before date `d`

Date	operator+ (double dt) const
	Adds `dt` seconds to this date-time and returns the resulting future date-time.

Date	operator- (double dt) const
	Subtracts `dt` seconds to this date-time and returns the resulting past date-time.

double	operator- (const Date &d) const
	Returns the time difference between two date times in seconds.

double	localOffset () const
	Returns the local time offset.

Static Public Member Functions
static Date	now ()
	Returns the current date-time.

Member Enumeration Documentation

◆ Format

enum Format

Format for toString() and toUTCString()

Enumerator
LONG	"2021-11-29T23:31:10.25Z"
SHORT	"20211129T233110.25Z"
DATE_ONLY	"2021-11-29"
HTTP	"Mon, 29 Nov 2021 23:31:10 GMT"
FULL	"2021-11-29T23:31:10.253Z" (with milliseconds)

Constructor & Destructor Documentation

◆ Date() [1/2]

Date ( const String & s )

Constructs a Date from a string representation in ISO-8601 format ("yyyy-mm-ddThh:mm:ss") or in RFC 1123 format (like HTTP, "Thu, 18 May 2017 03:24:12 GMT").

The last time components can be omitted and will be zero.

◆ Date() [2/2]

Date	(	const String &	s,
		const String &	fmt
	)

Constructs a Date from the string s using fmt as format specification.

The format can include characers Y, M, D, h, m, s as place holders for year, month, day, hour, minute, second. Any other characters will be matched literally except character '?', which matches any character.

Member Function Documentation

◆ toString()

String toString ( Format f = LONG ) const

inline

Returns a string representation of this date in ISO-8601 format.

The format argument is one of LONG (default): full ISO-8601, SHORT: compact ISO-8601 (no separators), DATE_ONLY: just the date part with separators, HTTP HTTP long format in GMT, FULL like long but with milliseconds.

◆ toUTCString()

String toUTCString ( Format f = LONG ) const

inline

Returns a string representation of this date in UTC in ISO-8601 format.

The format argument is one of LONG (default): full ISO-8601, SHORT: compact ISO-8601 (no separators), DATE_ONLY: just the date part with separators, FULL like long but with milliseconds.

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

Date.h