Represents an instant in time, typically expressed as a date and time of day. More...

#include <datetime.h>

Public Types
using	TickType = std::uint64_t

Public Member Functions
constexpr	DateTime ()
	Constructs a DateTime.

constexpr	DateTime (TickType ticks)
	Constructs a DateTime with the specified number of ticks.

constexpr TickType &	ticks ()
	Returns a mutable reference to the total ticks.

constexpr TickType	totalTicks () const
	Returns the number of ticks which represent the value of the current instance.

int	year () const
	Returns the year component of the date represented by this instance.

int	month () const
	Returns the month component of the date represented by this instance.

int	day () const
	Returns the day component of the date represented by this instance.

int	dayOfYear () const
	Returns the day of the year represented by this instance.

constexpr DayOfWeek	dayOfWeek () const
	Returns the day of the week represented by this instance.

constexpr int	hour () const
	Returns the hour component of the date represented by this instance.

constexpr int	minute () const
	Returns the minute component of the date represented by this instance.

constexpr int	second () const
	Returns the second component of the date represented by this instance.

constexpr int	millisecond () const
	Returns the millisecond component of the date represented by this instance.

constexpr int	microsecond () const
	Returns the microsecond component of the date represented by this instance.

constexpr int	nanosecond () const
	Returns the nanosecond component of the date represented by this instance.

constexpr bool	isNull () const
	Returns true if the date represented by the current DateTime class is null.

constexpr TimeSpan	timeOfDay () const
	Returns the time of day as TimeSpan for this instance.

bool	isLeapYear () const
	Returns an indication whether the year represented by this instance is a leap year.

constexpr bool	isEternity () const
	Returns whether the instance has the maximal number of ticks.

constexpr bool	isSameDay (const DateTime &other) const
	Returns and indication whether two DateTime instances represent the same day.

std::string	toString (DateTimeOutputFormat format=DateTimeOutputFormat::DateAndTime, bool noMilliseconds=false) const
	Returns the string representation of the current instance using the specified format.

void	toString (std::string &result, DateTimeOutputFormat format=DateTimeOutputFormat::DateAndTime, bool noMilliseconds=false) const
	Returns the string representation of the current instance using the specified format.

std::string	toIsoStringWithCustomDelimiters (TimeSpan timeZoneDelta=TimeSpan(), char dateDelimiter='-', char timeDelimiter=':', char timeZoneDelimiter=':') const
	Returns the string representation of the current instance in the ISO format with custom delimiters, eg.

std::string	toIsoString (TimeSpan timeZoneDelta=TimeSpan()) const
	Returns the string representation of the current instance in the ISO format, eg.

constexpr std::time_t	toTimeStamp () const
	Returns the UNIX timestamp for the current instance.

constexpr bool	operator== (const DateTime &other) const
	Indicates whether two DateTime instances are equal.

constexpr bool	operator!= (const DateTime &other) const
	Indicates whether two DateTime instances are not equal.

constexpr bool	operator< (const DateTime &other) const
	Indicates whether a specified DateTime is less than another specified DateTime.

constexpr bool	operator> (const DateTime &other) const
	Indicates whether a specified DateTime is greater than another specified DateTime.

constexpr bool	operator<= (const DateTime &other) const
	Indicates whether a specified DateTime is less or equal than another specified DateTime.

constexpr bool	operator>= (const DateTime &other) const
	Indicates whether a specified DateTime is greater or equal than another specified DateTime.

constexpr DateTime	operator+ (const TimeSpan &timeSpan) const
	Adds another instance.

constexpr DateTime	operator- (const TimeSpan &timeSpan) const
	Subtracts another instance.

constexpr TimeSpan	operator+ (const DateTime &other) const
	Adds two instances.

constexpr TimeSpan	operator- (const DateTime &other) const
	Subtracts two DateTime instances.

DateTime &	operator+= (const TimeSpan &timeSpan)
	Adds a TimeSpan to the current instance.

DateTime &	operator-= (const TimeSpan &timeSpan)
	Subtracts a TimeSpan from the current instance.

Static Public Member Functions
static DateTime	fromDate (int year=1, int month=1, int day=1)
	Constructs a DateTime to the specified year, month, and day.

static DateTime	fromTime (int hour=0, int minute=0, int second=0, double millisecond=0.0)
	Constructs a DateTime to the specified hour, minute, second and millisecond.

static DateTime	fromDateAndTime (int year=1, int month=1, int day=1, int hour=0, int minute=0, int second=0, double millisecond=0.0)
	Constructs a DateTime to the specified year, month, day, hour, minute, second and millisecond.

static DateTime	fromString (const std::string &str)
	Parses the given std::string as DateTime.

static DateTime	fromString (const char *str)
	Parses the given C-style string as DateTime.

static std::pair< DateTime, TimeSpan >	fromIsoString (const char *str)
	Parses the specified ISO date time denotation provided as C-style string.

static DateTime	fromIsoStringGmt (const char *str)
	Parses the specified ISO date time denotation provided as C-style string.

static DateTime	fromIsoStringLocal (const char *str)
	Parses the specified ISO date time denotation provided as C-style string.

static DateTime	fromTimeStamp (std::time_t timeStamp)
	Constructs a new DateTime object with the local time from the specified UNIX timeStamp.

static constexpr DateTime	fromTimeStampGmt (std::time_t timeStamp)
	Constructs a new DateTime object with the GMT time from the specified UNIX timeStamp.

template<typename TimePoint >
static DateTime	fromChronoTimePoint (TimePoint timePoint)
	Constructs a new DateTime object with the local time from the specified std::chrono::time_point.

template<typename TimePoint >
static constexpr DateTime	fromChronoTimePointGmt (TimePoint timePoint)
	Constructs a new DateTime object with the GMT time from the specified std::chrono::time_point.

static const char *	printDayOfWeek (DayOfWeek dayOfWeek, bool abbreviation=false)
	Returns the string representation as C-style string for the given day of week.

static constexpr DateTime	eternity ()
	Constructs a new instance of the DateTime class with the maximal number of ticks.

static constexpr DateTime	unixEpochStart ()
	Returns the DateTime object for the "1970-01-01T00:00:00Z".

static DateTime	now ()
	Returns a DateTime object that is set to the current date and time on this computer, expressed as the local time.

static DateTime	gmtNow ()
	Returns a DateTime object that is set to the current date and time on this computer, expressed as the GMT time.

static constexpr bool	isLeapYear (int year)
	Returns an indication whether the specified year is a leap year.

static int	daysInMonth (int year, int month)
	Returns the number of days in the specified month and year.

Detailed Description

Represents an instant in time, typically expressed as a date and time of day.

Remarks

Time values are measured in 100-nanosecond units called ticks, and a particular date is the number of ticks since 12:00 midnight, January 1, 0001 A.D. (C.E.) in the Gregorian Calendar (excluding ticks that would be added by leap seconds).
There is no time zone information associated. You need to keep track of the used time zone separately. That can be done by keeping an additional TimeSpan around which represents the delta to GMT or by simply using GMT everywhere in the program.
When constructing an instance via DateTime::fromTimeStamp(), DateTime::fromChronoTimePoint() or DateTime::fromIsoStringLocal() the time zone deltas are "baked into" the DateTime instance. For instance, the expression (DateTime::now() - DateTime::gmtNow()) returns one hour in Germany during winter time (and not zero although both instances represent the current time).

Todo

Allow to determine the date part for each component at once to prevent multiple invocations of getDatePart().

Definition at line 55 of file datetime.h.

Member Typedef Documentation

◆ TickType

using CppUtilities::DateTime::TickType = std::uint64_t

Definition at line 57 of file datetime.h.

Constructor & Destructor Documentation

◆ DateTime() [1/2]

CppUtilities::DateTime::DateTime ( )

inlineexplicitconstexpr

Constructs a DateTime.

Definition at line 194 of file datetime.h.

◆ DateTime() [2/2]

CppUtilities::DateTime::DateTime ( TickType ticks )

inlineexplicitconstexpr

Constructs a DateTime with the specified number of ticks.

Definition at line 202 of file datetime.h.

Member Function Documentation

◆ day()

int CppUtilities::DateTime::day ( ) const

inline

Returns the day component of the date represented by this instance.

Definition at line 334 of file datetime.h.

◆ dayOfWeek()

DayOfWeek CppUtilities::DateTime::dayOfWeek ( ) const

inlineconstexpr

Returns the day of the week represented by this instance.

See also: DayOfWeek

Definition at line 351 of file datetime.h.

◆ dayOfYear()

int CppUtilities::DateTime::dayOfYear ( ) const

inline

Returns the day of the year represented by this instance.

Definition at line 342 of file datetime.h.

◆ daysInMonth()

int CppUtilities::DateTime::daysInMonth	(	int	year,
		int	month )

inlinestatic

Returns the number of days in the specified month and year.

Definition at line 450 of file datetime.h.

◆ eternity()

DateTime CppUtilities::DateTime::eternity ( )

inlinestaticconstexpr

Constructs a new instance of the DateTime class with the maximal number of ticks.

Definition at line 486 of file datetime.h.

◆ fromChronoTimePoint()

template<typename TimePoint >

DateTime CppUtilities::DateTime::fromChronoTimePoint ( TimePoint timePoint )

inlinestatic

Constructs a new DateTime object with the local time from the specified std::chrono::time_point.

Remarks: Works only with time points of std::chrono::system_clock so far. C++20 will fix this. Until then this function should be considered experimental.

Definition at line 284 of file datetime.h.

◆ fromChronoTimePointGmt()

template<typename TimePoint >

DateTime CppUtilities::DateTime::fromChronoTimePointGmt ( TimePoint timePoint )

staticconstexpr

Constructs a new DateTime object with the GMT time from the specified std::chrono::time_point.

Remarks: Works only with time points of std::chrono::system_clock so far. C++20 will fix this. Until then this function should be considered experimental.

Definition at line 294 of file datetime.h.

◆ fromDate()

DateTime CppUtilities::DateTime::fromDate	(	int	year = 1,
		int	month = 1,
		int	day = 1 )

inlinestatic

Constructs a DateTime to the specified year, month, and day.

Exceptions

Throws a ConversionException if the specified year, month or day is out-of-range.

Definition at line 211 of file datetime.h.

◆ fromDateAndTime()

DateTime CppUtilities::DateTime::fromDateAndTime	(	int	year = 1,
		int	month = 1,
		int	day = 1,
		int	hour = 0,
		int	minute = 0,
		int	second = 0,
		double	millisecond = 0.0 )

inlinestatic

Constructs a DateTime to the specified year, month, day, hour, minute, second and millisecond.

Exceptions

Throws a ConversionException if the specified year, month, day, hour, minute, second or millisecond is out-of-range.

Definition at line 230 of file datetime.h.

◆ fromIsoString()

std::pair< DateTime, TimeSpan > CppUtilities::DateTime::fromIsoString ( const char * str )

static

Parses the specified ISO date time denotation provided as C-style string.

Returns: Returns a pair where the first value is the parsed date time and the second value the time zone designator (a time span which can be subtracted from the first value to get the UTC time).

Exceptions

Throws a ConversionException if the specified str does not match the expected time format.

Remarks

Parsing durations and time intervals is not supported.
Truncated representations are not supported.
Standardised extensions (ISO 8601-2:2019) are not supported.

See also: https://en.wikipedia.org/wiki/ISO_8601

Definition at line 105 of file datetime.cpp.

◆ fromIsoStringGmt()

DateTime CppUtilities::DateTime::fromIsoStringGmt ( const char * str )

inlinestatic

Parses the specified ISO date time denotation provided as C-style string.

Returns: Returns the parsed UTC time. That means a possibly denoted time zone delta is subtracted from the time stamp.

Exceptions

Throws a ConversionException if the specified str does not match the expected time format.

See also: fromIsoString()

Definition at line 255 of file datetime.h.

◆ fromIsoStringLocal()

DateTime CppUtilities::DateTime::fromIsoStringLocal ( const char * str )

inlinestatic

Parses the specified ISO date time denotation provided as C-style string.

Returns: Returns the parsed local time. That means a possibly denoted time zone delta is discarded.

Exceptions

Throws a ConversionException if the specified str does not match the expected time format.

See also: fromIsoString()

Definition at line 266 of file datetime.h.

◆ fromString() [1/2]

DateTime CppUtilities::DateTime::fromString ( const char * str )

static

Parses the given C-style string as DateTime.

Exceptions

Throws a ConversionException if the specified str does not match the expected time format.

The expected format is something like "2012-02-29 15:34:20.033" or "2012/02/29 15:34:20.033". The delimiters '-', ':' and '/' are exchangeable.

See also: DateTime::fromIsoString()

Definition at line 89 of file datetime.cpp.

◆ fromString() [2/2]

DateTime CppUtilities::DateTime::fromString ( const std::string & str )

inlinestatic

Parses the given std::string as DateTime.

Exceptions

Throws a ConversionException if the specified str does not match the expected time format.

The expected format is something like "2012-02-29 15:34:20.033" or "2012/02/29 15:34:20.033". The delimiters '-', ':' and '/' are exchangeable.

See also: DateTime::fromIsoString()

Definition at line 244 of file datetime.h.

◆ fromTime()

DateTime CppUtilities::DateTime::fromTime	(	int	hour = 0,
		int	minute = 0,
		int	second = 0,
		double	millisecond = 0.0 )

inlinestatic

Constructs a DateTime to the specified hour, minute, second and millisecond.

Exceptions

Throws a ConversionException if the specified hour, minute, second or millisecond is out-of-range.

Definition at line 220 of file datetime.h.

◆ fromTimeStamp()

DateTime CppUtilities::DateTime::fromTimeStamp ( std::time_t timeStamp )

static

Constructs a new DateTime object with the local time from the specified UNIX timeStamp.

Definition at line 69 of file datetime.cpp.

◆ fromTimeStampGmt()

DateTime CppUtilities::DateTime::fromTimeStampGmt ( std::time_t timeStamp )

inlinestaticconstexpr

Constructs a new DateTime object with the GMT time from the specified UNIX timeStamp.

Definition at line 274 of file datetime.h.

◆ gmtNow()

DateTime CppUtilities::DateTime::gmtNow ( )

inlinestatic

Returns a DateTime object that is set to the current date and time on this computer, expressed as the GMT time.

Remarks: The time might be rounded to full seconds. Use exactGmtNow() for better precision.

Definition at line 512 of file datetime.h.

◆ hour()

int CppUtilities::DateTime::hour ( ) const

inlineconstexpr

Returns the hour component of the date represented by this instance.

Definition at line 359 of file datetime.h.

◆ isEternity()

bool CppUtilities::DateTime::isEternity ( ) const

inlineconstexpr

Returns whether the instance has the maximal number of ticks.

Definition at line 434 of file datetime.h.

◆ isLeapYear() [1/2]

bool CppUtilities::DateTime::isLeapYear ( ) const

inline

Returns an indication whether the year represented by this instance is a leap year.

Definition at line 426 of file datetime.h.

◆ isLeapYear() [2/2]

bool CppUtilities::DateTime::isLeapYear ( int year )

inlinestaticconstexpr

Returns an indication whether the specified year is a leap year.

Definition at line 442 of file datetime.h.

◆ isNull()

bool CppUtilities::DateTime::isNull ( ) const

inlineconstexpr

Returns true if the date represented by the current DateTime class is null.

See also: DateTime

Definition at line 410 of file datetime.h.

◆ isSameDay()

bool CppUtilities::DateTime::isSameDay ( const DateTime & other ) const

inlineconstexpr

Returns and indication whether two DateTime instances represent the same day.

Definition at line 458 of file datetime.h.

◆ microsecond()

int CppUtilities::DateTime::microsecond ( ) const

inlineconstexpr

Returns the microsecond component of the date represented by this instance.

Definition at line 391 of file datetime.h.

◆ millisecond()

int CppUtilities::DateTime::millisecond ( ) const

inlineconstexpr

Returns the millisecond component of the date represented by this instance.

Definition at line 383 of file datetime.h.

◆ minute()

int CppUtilities::DateTime::minute ( ) const

inlineconstexpr

Returns the minute component of the date represented by this instance.

Definition at line 367 of file datetime.h.

◆ month()

int CppUtilities::DateTime::month ( ) const

inline

Returns the month component of the date represented by this instance.

Definition at line 326 of file datetime.h.

◆ nanosecond()

int CppUtilities::DateTime::nanosecond ( ) const

inlineconstexpr

Returns the nanosecond component of the date represented by this instance.

Remarks: The accuracy of the DateTime class is 100-nanoseconds. Hence the returned value will always have two zeros at the end (in decimal representation).

Definition at line 401 of file datetime.h.

◆ now()

DateTime CppUtilities::DateTime::now ( )

inlinestatic

Returns a DateTime object that is set to the current date and time on this computer, expressed as the local time.

Remarks: The time might be rounded to full seconds. Use exactGmtNow() for better precision.

Definition at line 503 of file datetime.h.

◆ operator!=()

bool CppUtilities::DateTime::operator!= ( const DateTime & other ) const

inlineconstexpr

Indicates whether two DateTime instances are not equal.

Definition at line 528 of file datetime.h.

◆ operator+() [1/2]

TimeSpan CppUtilities::DateTime::operator+ ( const DateTime & other ) const

inlineconstexpr

Adds two instances.

Returns: The result is a TimeSpan.

Definition at line 587 of file datetime.h.

◆ operator+() [2/2]

DateTime CppUtilities::DateTime::operator+ ( const TimeSpan & timeSpan ) const

inlineconstexpr

Adds another instance.

Returns: The result is another DateTime.

Definition at line 569 of file datetime.h.

◆ operator+=()

DateTime & CppUtilities::DateTime::operator+= ( const TimeSpan & timeSpan )

inline

Adds a TimeSpan to the current instance.

Definition at line 606 of file datetime.h.

◆ operator-() [1/2]

TimeSpan CppUtilities::DateTime::operator- ( const DateTime & other ) const

inlineconstexpr

Subtracts two DateTime instances.

Returns: The result is a TimeSpan.

Remarks: For expressing the delta between two concrete DateTime instances in terms of years, month and days, use Period::Period instead.

Definition at line 598 of file datetime.h.

◆ operator-() [2/2]

DateTime CppUtilities::DateTime::operator- ( const TimeSpan & timeSpan ) const

inlineconstexpr

Subtracts another instance.

Returns: The result is another DateTime.

Definition at line 578 of file datetime.h.

◆ operator-=()

DateTime & CppUtilities::DateTime::operator-= ( const TimeSpan & timeSpan )

inline

Subtracts a TimeSpan from the current instance.

Definition at line 615 of file datetime.h.

◆ operator<()

bool CppUtilities::DateTime::operator< ( const DateTime & other ) const

inlineconstexpr

Indicates whether a specified DateTime is less than another specified DateTime.

Definition at line 536 of file datetime.h.

◆ operator<=()

bool CppUtilities::DateTime::operator<= ( const DateTime & other ) const

inlineconstexpr

Indicates whether a specified DateTime is less or equal than another specified DateTime.

Definition at line 552 of file datetime.h.

◆ operator==()

bool CppUtilities::DateTime::operator== ( const DateTime & other ) const

inlineconstexpr

Indicates whether two DateTime instances are equal.

Definition at line 520 of file datetime.h.

◆ operator>()

bool CppUtilities::DateTime::operator> ( const DateTime & other ) const

inlineconstexpr

Indicates whether a specified DateTime is greater than another specified DateTime.

Definition at line 544 of file datetime.h.

◆ operator>=()

bool CppUtilities::DateTime::operator>= ( const DateTime & other ) const

inlineconstexpr

Indicates whether a specified DateTime is greater or equal than another specified DateTime.

Definition at line 560 of file datetime.h.

◆ printDayOfWeek()

const char * CppUtilities::DateTime::printDayOfWeek	(	DayOfWeek	dayOfWeek,
		bool	abbreviation = false )

static

Returns the string representation as C-style string for the given day of week.

If abbreviation is true, only the first three letters of the string will be returned.

See also: DayOfWeek

Definition at line 234 of file datetime.cpp.

◆ second()

int CppUtilities::DateTime::second ( ) const

inlineconstexpr

Returns the second component of the date represented by this instance.

Definition at line 375 of file datetime.h.

◆ ticks()

DateTime::TickType & CppUtilities::DateTime::ticks ( )

inlineconstexpr

Returns a mutable reference to the total ticks.

Definition at line 302 of file datetime.h.

◆ timeOfDay()

TimeSpan CppUtilities::DateTime::timeOfDay ( ) const

inlineconstexpr

Returns the time of day as TimeSpan for this instance.

Definition at line 418 of file datetime.h.

◆ toIsoString()

string CppUtilities::DateTime::toIsoString ( TimeSpan timeZoneDelta = TimeSpan() ) const

Returns the string representation of the current instance in the ISO format, eg.

2016-08-29T21:32:31.588539814+02:00.

Definition at line 222 of file datetime.cpp.

◆ toIsoStringWithCustomDelimiters()

string CppUtilities::DateTime::toIsoStringWithCustomDelimiters	(	TimeSpan	timeZoneDelta = TimeSpan(),
		char	dateDelimiter = '-',
		char	timeDelimiter = ':',
		char	timeZoneDelimiter = ':' ) const

Returns the string representation of the current instance in the ISO format with custom delimiters, eg.

2016/08/29T21-32-31.588539814+02:00 with '/' as dateDelimiter and '-' as timeDelimiter.

Definition at line 188 of file datetime.cpp.

◆ toString() [1/2]

std::string CppUtilities::DateTime::toString	(	DateTimeOutputFormat	format = DateTimeOutputFormat::DateAndTime,
		bool	noMilliseconds = false ) const

inline

Returns the string representation of the current instance using the specified format.

Remarks: If noMilliseconds is true the date will be rounded to full seconds.

See also: toIsoString() for ISO format

Definition at line 468 of file datetime.h.

◆ toString() [2/2]

void CppUtilities::DateTime::toString	(	std::string &	result,
		DateTimeOutputFormat	format = DateTimeOutputFormat::DateAndTime,
		bool	noMilliseconds = false ) const

Returns the string representation of the current instance using the specified format.

Remarks: If noMilliseconds is true the date will be rounded to full seconds.

See also: toIsoString() for ISO format

Definition at line 116 of file datetime.cpp.

◆ totalTicks()

DateTime::TickType CppUtilities::DateTime::totalTicks ( ) const

inlineconstexpr

Returns the number of ticks which represent the value of the current instance.

Definition at line 310 of file datetime.h.

◆ toTimeStamp()

std::time_t CppUtilities::DateTime::toTimeStamp ( ) const

constexpr

Returns the UNIX timestamp for the current instance.

Definition at line 478 of file datetime.h.

◆ unixEpochStart()

DateTime CppUtilities::DateTime::unixEpochStart ( )

inlinestaticconstexpr

Returns the DateTime object for the "1970-01-01T00:00:00Z".

Definition at line 494 of file datetime.h.

◆ year()

int CppUtilities::DateTime::year ( ) const

inline

Returns the year component of the date represented by this instance.

Definition at line 318 of file datetime.h.

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

chrono/datetime.h
chrono/datetime.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ TickType

Constructor & Destructor Documentation

◆ DateTime() [1/2]

◆ DateTime() [2/2]

Member Function Documentation

◆ day()

◆ dayOfWeek()

◆ dayOfYear()

◆ daysInMonth()

◆ eternity()

◆ fromChronoTimePoint()

◆ fromChronoTimePointGmt()

◆ fromDate()

◆ fromDateAndTime()

◆ fromIsoString()

◆ fromIsoStringGmt()

◆ fromIsoStringLocal()

◆ fromString() [1/2]

◆ fromString() [2/2]

◆ fromTime()

◆ fromTimeStamp()

◆ fromTimeStampGmt()

◆ gmtNow()

◆ hour()

◆ isEternity()

◆ isLeapYear() [1/2]

◆ isLeapYear() [2/2]

◆ isNull()

◆ isSameDay()

◆ microsecond()

◆ millisecond()

◆ minute()

◆ month()

◆ nanosecond()

◆ now()

◆ operator!=()

◆ operator+() [1/2]

◆ operator+() [2/2]

◆ operator+=()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ operator-=()

◆ operator<()

◆ operator<=()

◆ operator==()

◆ operator>()

◆ operator>=()

◆ printDayOfWeek()

◆ second()

◆ ticks()

◆ timeOfDay()

◆ toIsoString()

◆ toIsoStringWithCustomDelimiters()

◆ toString() [1/2]

◆ toString() [2/2]

◆ totalTicks()

◆ toTimeStamp()

◆ unixEpochStart()

◆ year()