C++ Utilities 5.24.7
Useful C++ classes and routines such as argument parser, IO and conversion utilities
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | List of all members
CppUtilities::DateTime Class Reference

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 TickTypeticks ()
 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.
 
DateTimeoperator+= (const TimeSpan &timeSpan)
 Adds a TimeSpan to the current instance.
 
DateTimeoperator-= (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, TimeSpanfromIsoString (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 charprintDayOfWeek (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

Definition at line 57 of file datetime.h.

Constructor & Destructor Documentation

◆ DateTime() [1/2]

constexpr CppUtilities::DateTime::DateTime ( )
inlineexplicitconstexpr

Constructs a DateTime.

Definition at line 194 of file datetime.h.

◆ DateTime() [2/2]

constexpr 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()

constexpr 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()

constexpr 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 >
constexpr 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
Throwsa 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
Throwsa 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
Throwsa 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
Throwsa 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
Throwsa 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
Throwsa 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
Throwsa 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
Throwsa 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()

constexpr 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()

constexpr 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()

constexpr 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]

constexpr 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()

constexpr 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()

constexpr 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()

constexpr 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()

constexpr 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()

constexpr 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()

constexpr 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!=()

constexpr 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]

constexpr 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]

constexpr 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]

constexpr 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]

constexpr 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<()

constexpr 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<=()

constexpr 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==()

constexpr 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>()

constexpr 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>=()

constexpr 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()

constexpr 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()

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

Returns a mutable reference to the total ticks.

Definition at line 302 of file datetime.h.

◆ timeOfDay()

constexpr 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()

constexpr 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()

constexpr 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()

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