DateTime is an immutable class representing a datetime without a time zone in the ISO-8601 calendar system, such as "2017-12-31, 22:34:55 UTC". More...

#include <datetime.hpp>

Public Types
Durations
using	Nanoseconds = Time::Nanoseconds
	Nanosecond duration.

using	Microseconds = Time::Microseconds
	Microsecond duration.

using	Milliseconds = Time::Milliseconds
	Millisecond duration.

using	Seconds = Time::Seconds
	Second duration.

using	Minutes = Time::Minutes
	Minute duration.

using	Hours = Time::Hours
	Hour duration.

using	Days = Date::Days
	Day duration.

using	Weeks = Date::Weeks
	Week duration.

Enumerations
using	Weekday = Date::Weekday
	Weekday enumeration.

using	Month = Date::Month
	Month enumeration.

Public Member Functions
Constructors and Destructors
	DateTime ()=default
	Constructs an invalid DateTime object with every field set to zero. More...

	DateTime (const DateTime &other)=default
	Copy-constructs a DateTime object from `other`.

	DateTime (DateTime &&other)=default
	Move-constructs a DateTime object from `other`.

	DateTime (const Duration &duration)
	Constructs a DateTime object from `duration` since the epoch "1970-01-01 00:00:00 UTC". More...

	DateTime (const std::chrono::system_clock::time_point &timePoint)
	Constructs a DateTime object from the standard library's chrono time point, `timePoint`.

	DateTime (const Date &date)
	Constructs a DateTime object from `date`, leaving the time part at midnight ("00:00:00").

	DateTime (const Date &date, const Time &time)
	Constructs a DateTime object from `date` and `time`.

	~DateTime ()=default
	Default destructor.

Assignment Operators
DateTime &	operator= (const DateTime &other)=default
	Copy assignment operator.

DateTime &	operator= (DateTime &&other)=default
	Move assignment operator.

Comparison Operators
bool	operator< (const DateTime &other) const
	Returns whether this datetime is earlier than `other`.

bool	operator<= (const DateTime &other) const
	Returns whether this datetime is earlier than `other` or equal to it.

bool	operator> (const DateTime &other) const
	Returns whether this datetime is later than `other`.

bool	operator>= (const DateTime &other) const
	Returns whether this datetime is later than `other` or equal to it.

bool	operator== (const DateTime &other) const
	Returns whether this datetime is equal to `other`.

bool	operator!= (const DateTime &other) const
	Returns whether this datetime is different from `other`.

Addition/Subtraction Operators
Nanoseconds	operator- (const DateTime &other) const
	Returns the result of subtracting `other` from this datetime as Nanoseconds duration.

DateTime	operator- (const Duration &duration) const
	Returns the result of subtracting `duration` from this datetime as a new DateTime object.

DateTime	operator+ (const Duration &duration) const
	Returns the result of adding `duration` to this datetime as a new DateTime object.

Querying Methods
bool	isValid () const
	Returns whether this datetime object represents a valid datetime. A DateTime object is valid if both the date and time parts are valid. For more information, see Date::isValid() and Time::isValid().

Date	date () const
	Returns the date part of this datetime.

Time	time () const
	Returns the time part of this datetime.

long	nanosecond () const
	Returns the nanosecond of second (0, 999999999).

long	microsecond () const
	Returns the microsecond of second (0, 999999).

int	millisecond () const
	Returns the millisecond of second (0, 999).

int	second () const
	Returns the second of minute (0, 59).

int	minute () const
	Returns the minute of hour (0, 59).

int	hour () const
	Returns the hour of day (0, 23).

int	day () const
	Returns the day of month (1, 31).

int	month () const
	Returns the month of year (1, 12), which corresponds to the enumeration Month.

int	year () const
	Returns the year as a number. There is no year 0. Negative numbers indicate years before 1 CE; that is, year -1 is year 1 BCE, year -2 is year 2 BCE, and so on.

void	getYearMonthDay (int year, int month, int *day) const
	Set the year, month, and day in the parameters `year`, `month`, and `day`, respectively.

int	dayOfWeek () const
	Returns the weekday as a number between 1 and 7, which corresponds to the enumeration Weekday.

int	dayOfYear () const
	Returns the day of the year as a number between 1 and 365 (1 to 366 on leap years).

int	daysInMonth () const
	Returns the number of days in the current month. It ranges between 28 and 31.

int	daysInYear () const
	Returns the number of days in the current year. It is either 365 or 366.

bool	isLeapYear () const
	Returns whether the year of this datetime is a leap year. For more information, see Date::isLeapYear(int).

int	weekOfYear (int *weekYear=nullptr) const
	Returns the week number of the year of this datetime, and optionally stores the year in `weekYear`. More...

std::string	dayOfWeekName (bool shortName=false) const
	Returns the name of the weekday of this datetime. More...

std::string	monthName (bool shortName=false) const
	Returns the name of the month of this datetime. More...

Addition/Subtraction Methods
DateTime	addNanoseconds (int nanoseconds) const
	Returns a new DateTime object representing this datetime with `nanoseconds` added to it.

DateTime	subtractNanoseconds (int nanoseconds) const
	Returns a new DateTime object representing this datetime with `nanoseconds` subtracted from it.

DateTime	addMicroseconds (int microseconds) const
	Returns a new DateTime object representing this datetime with `microseconds` added to it.

DateTime	subtractMicroseconds (int microseconds) const
	Returns a new DateTime object representing this datetime with `microseconds` subtracted from it.

DateTime	addMilliseconds (int milliseconds) const
	Returns a new DateTime object representing this datetime with `milliseconds` added to it.

DateTime	subtractMilliseconds (int milliseconds) const
	Returns a new DateTime object representing this datetime with `milliseconds` subtracted from it.

DateTime	addSeconds (int seconds) const
	Returns a new DateTime object representing this datetime with `seconds` added to it.

DateTime	subtractSeconds (int seconds) const
	Returns a new DateTime object representing this datetime with `seconds` subtracted from it.

DateTime	addMinutes (int minutes) const
	Returns a new DateTime object representing this datetime with `minutes` added to it.

DateTime	subtractMinutes (int minutes) const
	Returns a new DateTime object representing this datetime with `minutes` subtracted from it.

DateTime	addHours (int hours) const
	Returns a new DateTime object representing this datetime with `hours` added to it.

DateTime	subtractHours (int hours) const
	Returns a new DateTime object representing this datetime with `hours` subtracted from it.

DateTime	addDays (int days) const
	Returns a new DateTime object representing this datetime with `days` added to it.

DateTime	subtractDays (int days) const
	Returns a new DateTime object representing this datetime with `days` subtracted from it.

DateTime	addMonths (int months) const
	Returns a new DateTime object representing this datetime with `months` added to it. See Date::addMonths() for more information about how the operation is done.

DateTime	subtractMonths (int months) const
	Returns a new DateTime object representing this datetime with `months` subtracted from it. See Date::subtractMonths() for more information about how the operation is done.

DateTime	addYears (int years) const
	Returns a new DateTime object representing this datetime with `years` added to it.

DateTime	subtractYears (int years) const
	Returns a new DateTime object representing this datetime with `years` subtracted from it.

DateTime	addDuration (const Duration &duration) const
	Returns a new DateTime object representing this datetime with `duration` added to it.

DateTime	subtractDuration (const Duration &duration) const
	Returns a new DateTime object representing this datetime with `duration` subtracted from it.

Conversion Methods
long long	toNanosecondsSinceEpoch () const
	Returns the number of elapsed nanoseconds since "1970-01-01 00:00:00.000 UTC", not counting leap seconds.

long long	toMicrosecondsSinceEpoch () const
	Returns the number of elapsed microseconds since "1970-01-01 00:00:00.000 UTC", not counting leap seconds.

long long	toMillisecondsSinceEpoch () const
	Returns the number of elapsed milliseconds since "1970-01-01 00:00:00.000 UTC", not counting leap seconds.

long long	toSecondsSinceEpoch () const
	Returns the number of elapsed seconds since "1970-01-01 00:00:00.000 UTC, not counting leap seconds.

long	toMinutesSinceEpoch () const
	Returns the number of elapsed minutes since "1970-01-01 00:00:00.000 UTC, not counting leap seconds.

long	toHoursSinceEpoch () const
	Returns the number of elapsed hours since "1970-01-01 00:00:00.000 UTC, not counting leap seconds.

long	toDaysSinceEpoch () const
	Returns the number of elapsed days since "1970-01-01 00:00:00.000 UTC", not counting leap seconds.

Microseconds	toStdDurationSinceEpoch () const
	Returns a std::chrono::microseconds duration since "1970-01-01 00:00:00.000 UTC", not counting leap seconds.

std::chrono::system_clock::time_point	toStdTimePoint () const
	Returns a std::chrono::system_clock::time_point representation of this datetime.

std::tm	toBrokenStdTime () const
	Returns a std::tm representation of this datetime.

std::time_t	toScalarStdTime () const
	Returns a std::time_t representation of this datetime.

double	toJulianDay () const
	Returns the corresponding Julian Day Number (JDN) of this datetime as a double, where the integral part represents the day count and the fractional part represents the time since midday Universal Time (UT). More...

std::string	toString (const std::string &format="yyyy-MM-dd hh:mm:ss") const
	Returns the datetime as a string formatted according to the format string `format`. More...

Static Public Member Functions
static DateTime	current ()
	Returns a DateTime object set to the current datetime obtained from the system clock. More...

static DateTime	epoch ()
	Returns a DateTime object set to the epoch "1970-1-1T00:00:00".

static DateTime	fromString (const std::string &datetime, const std::string &format="yyyy-MM-dd hh:mm:ss")
	Returns a DateTime object from the string `datetime` formatted according to the format string `format`. More...

static DateTime	fromJulianDay (double julianDay)
	Returns a DateTime object corresponding to the Julian day `julianDay`. See toJulianDay() for information about Julian Days.

Calculation Methods
The following methods return the time difference between two datetimes: `from` and `to`. If `to` is earlier than (smaller than) `from`, then the difference is negative.
static long long	nanosecondsBetween (const DateTime &from, const DateTime &to)
	Returns the number of nanoseconds between `from` and `to`.

static long long	microsecondsBetween (const DateTime &from, const DateTime &to)
	Returns the number of microseconds between `from` and `to`.

static long long	millisecondsBetween (const DateTime &from, const DateTime &to)
	Returns the number of milliseconds between `from` and `to`.

static long long	secondsBetween (const DateTime &from, const DateTime &to)
	Returns the number of seconds between `from` and `to`.

static long	minutesBetween (const DateTime &from, const DateTime &to)
	Returns the number of minutes between `from` and `to`.

static long	hoursBetween (const DateTime &from, const DateTime &to)
	Returns the number of hours between `from` and `to`.

static long	daysBetween (const DateTime &from, const DateTime &to)
	Returns the number of days between `from` and `to`.

static long	weeksBetween (const DateTime &from, const DateTime &to)
	Returns the number of weeks between `from` and `to`.

Related Functions
(Note that these are not member functions.)
Input/Output Operators
std::ostream &	operator<< (std::ostream &os, const DateTime &dt)
	Writes `dt` to stream `os` in ISO-8601 date and time format "yyyy-MM-ddThh:mm:ss.fff". See toString() for information about the format patterns.

std::istream &	operator>> (std::istream &is, DateTime &dt)
	Reads a datetime in ISO-8601 date and time format "yyyy-MM-ddThh:mm:ss.fff" from stream `is` and stores it in `dt`. See toString() for information about the format patterns.

Detailed Description

DateTime is an immutable class representing a datetime without a time zone in the ISO-8601 calendar system, such as "2017-12-31, 22:34:55 UTC".

The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. It is equivalent to the proleptic Gregorian calendar system. DateTime describes the datetime as a Date part (year, month, day) and a Time part (hour, minute, second, subsecond).

Internally, DateTime describes a datetime as a combination of the number of days since the epoch "1970-01-01 00:00:00.000 UTC" plus the number of nanoseconds since midnight.

Default-constructed DateTime objects are invalid (calling isValid() on them returns false) and are set to "0000-00-00 00:00:00". DateTime objects can be created by giving a Date object and a Time object. It can also be created by giving only a Date object; in this case, the time part is considered to be at midnight. Also, a DateTime object can be created from a formatted string through fromString() or from a Julian day through fromJulianDay(). The method current() returns the current datetime obtained from the system clock.

The datetime fields can be accessed through the methods year(), month(), day(), hour(), minute(), second(), millisecond(), microsecond(), and nanosecond(). Other fields, such as day-of-year, day-of-week, and week-of-year, can also be accessed through dayOfYear(), dayOfWeek(), and weekOfYear(), respectively.

DateTime provides methods for manipulating datetimes. Years, months, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds can be added to a datetime (through addYears(), addMonths(), addDays(), addHours(), addMinutes(), addSeconds(), addMilliseconds(), addMicroseconds(), and addNanoseconds(), respectively). or subtracted from it (through subtractYears(), subtractMonths(), subtractDays(), subtractHours(), subtractMinutes(), subtractSeconds(), subtractMilliseconds(), subtractMicroseconds(), and subtractNanoseconds(), respectively).

It also has operators for comparison. DateTime A is considered earlier than DateTime B if A is smaller than B, and so on.

The methods weeksBetween(), daysBetween(), hoursBetween(), minutesBetween(), secondsBetween(), millisecondsBetween(), and microsecondsBetween() returns how many weeks, days, hours, minutes, seconds, milliseconds, and microseconds, respectively, are between two DateTime objects.

The toString() method can be used to get a textual representation of the datetime formatted according to a given format string.

See also: The unit tests in datetime.h for further details.

Constructor & Destructor Documentation

◆ DateTime() [1/2]

xclox::DateTime::DateTime ( )

default

Constructs an invalid DateTime object with every field set to zero.

See also: isValid()

◆ DateTime() [2/2]

xclox::DateTime::DateTime ( const Duration & duration )

inlineexplicit

Constructs a DateTime object from duration since the epoch "1970-01-01 00:00:00 UTC".

The constructed datetime has whatever precision it is given, down to nanoseconds.

Member Function Documentation

◆ current()

static DateTime xclox::DateTime::current ( )

inlinestatic

Returns a DateTime object set to the current datetime obtained from the system clock.

Note that the returned datetime is not the current local datetime but rather the current system datetime in Coordinated Universal Time (UTC).

◆ dayOfWeekName()

std::string xclox::DateTime::dayOfWeekName ( bool shortName = false ) const

inline

Returns the name of the weekday of this datetime.

The short and long names of the weekdays are named according to the following convention:

Weekday No.	Short Name	Long Name
1	Mon	Monday
2	Tue	Tuesday
3	Wed	Wednesday
4	Thu	Thursday
5	Fri	Friday
6	Sat	Saturday
7	Sun	Sunday

Parameters

shortName If true, returns the short name of the weekday, such as "Sat". If false (by default), returns the long name, such as "Saturday".

◆ fromString()

static DateTime xclox::DateTime::fromString	(	const std::string &	datetime,
		const std::string &	format = `"yyyy-MM-dd hh:mm:ss"`
	)

inlinestatic

Returns a DateTime object from the string datetime formatted according to the format string format.

The format patterns are the same patterns used in the method toString().

See also: toString()

◆ monthName()

std::string xclox::DateTime::monthName ( bool shortName = false ) const

inline

Returns the name of the month of this datetime.

The short and long names of the months are named according to the following convention:

Month No.	Short Name	Long Name
1	Jan	January
2	Feb	February
3	Mar	March
4	Apr	April
5	May	May
6	Jun	June
7	Jul	July
8	Aug	August
9	Sep	September
10	Oct	October
11	Nov	November
12	Dec	December

Parameters

shortName If true, returns the short name of the month, such as "Jan". If false (by default), returns the long name, such as "January".

◆ toJulianDay()

double xclox::DateTime::toJulianDay ( ) const

inline

Returns the corresponding Julian Day Number (JDN) of this datetime as a double, where the integral part represents the day count and the fractional part represents the time since midday Universal Time (UT).

The JDN is the consecutive numbering of days and fractions since noon Universal Time (UT) on 1 January 4713 BCE in the proleptic Julian calendar, which occurs on 24 November 4714 BCE in the proleptic Gregorian calendar. That is, the JDN 0 corresponds to "12:00:00 UTC, 24 November 4714 BCE", the JDN 1.5 represents "00:00:00 UTC, 26 November 4714 BCE", and the JDN of today at "00:09:35 UTC, 31 December 2017 CE" is 2458118.506655093. Note that the date to be converted is considered Gregorian. Also, the current Gregorian rules are extended backwards and forwards. There is no year 0. The first year before the common era (i.e., year 1 BCE) is year -1, year -2 is year 2 BCE, and so on.

◆ toString()

std::string xclox::DateTime::toString ( const std::string & format = "yyyy-MM-dd hh:mm:ss" ) const

inline

Returns the datetime as a string formatted according to the format string format.

The format string may contain the following patterns:

Pattern	Meaning
#	era of year as a positive sign(+) or negative sign(-)
E	era of year as CE or BCE
y	year as one digit or more (1, 9999+)
yy	year of era as two digits (00, 99)
yyyy	year as four digits (0000, 9999)
M	month of year as one digit or more (1, 12)
MM	month of year as two digits (01, 12)
MMM	month of year as short name (e.g. "Feb")
MMMM	month of year as long name (e.g. "February")
d	day of month as one digit or more (1, 31)
dd	day of month as two digits (00, 31)
ddd	day of week as short name (e.g. "Fri")
dddd	day of week as long name (e.g. "Friday")
h	one-digit hour (0, 23)
hh	two-digit hour (00, 23)
H	one-digit hour (1, 12)
HH	two-digit hour (01, 12)
m	one-digit minute (0, 59)
mm	two-digit minute (00, 59)
s	one-digit second (0, 59)
ss	two-digit second (00, 59)
f	one-digit subsecond (0, 9)
ff	two-digit subsecond (00, 99)
fff	three-digit subsecond (000, 999)
ffff	four-digit subsecond (0000, 9999)
fffff	five-digit subsecond (00000, 99999)
ffffff	six-digit subsecond (000000, 999999)
fffffff	seven-digit subsecond (0000000, 9999999)
ffffffff	eight-digit subsecond (00000000, 99999999)
fffffffff	nine-digit subsecond (000000000, 999999999)
a	before/after noon indicator(i.e. am or pm)
A	before/after noon indicator(i.e. AM or PM)

Any character in the format string not listed above will be inserted as-is into the output string. If the datetime is invalid, an empty string will be returned.

See also: dayOfWeekName(), monthName()

◆ weekOfYear()

int xclox::DateTime::weekOfYear ( int * weekYear = nullptr ) const

inline

Returns the week number of the year of this datetime, and optionally stores the year in weekYear.

The week of the year ranges between 1 and 53. Most years have 52 weeks, but some have 53. According to ISO-8601, weeks start on Monday, and the first Thursday of a year is always in week 1 of that year. weekYear is not always the same as year(). For example:

The date of "1 January 2000" falls in week 52 of the year 1999.
The date of "31 December 2002" falls in week 1 of the year 2003.
The date of "1 January 2010" falls in week 53 of the year 2009.

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

include/xclox/datetime.hpp

Public Types

Public Member Functions

Static Public Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

◆ DateTime() [1/2]

◆ DateTime() [2/2]

Member Function Documentation

◆ current()

◆ dayOfWeekName()

◆ fromString()

◆ monthName()

◆ toJulianDay()

◆ toString()

◆ weekOfYear()