C++ Utilities  5.3.0
Useful C++ classes and routines such as argument parser, IO and conversion utilities
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 Member Functions

constexpr DateTime ()
 Constructs a DateTime. More...
 
constexpr DateTime (std::uint64_t ticks)
 Constructs a DateTime with the specified number of ticks. More...
 
constexpr std::uint64_t & ticks ()
 Returns a mutable reference to the total ticks. More...
 
constexpr std::uint64_t totalTicks () const
 Returns the number of ticks which represent the value of the current instance. More...
 
int year () const
 Returns the year component of the date represented by this instance. More...
 
int month () const
 Returns the month component of the date represented by this instance. More...
 
int day () const
 Returns the day component of the date represented by this instance. More...
 
int dayOfYear () const
 Returns the day of the year represented by this instance. More...
 
constexpr DayOfWeek dayOfWeek () const
 Returns the day of the week represented by this instance. More...
 
constexpr int hour () const
 Returns the hour component of the date represented by this instance. More...
 
constexpr int minute () const
 Returns the minute component of the date represented by this instance. More...
 
constexpr int second () const
 Returns the second component of the date represented by this instance. More...
 
constexpr int millisecond () const
 Returns the millisecond component of the date represented by this instance. More...
 
constexpr int microsecond () const
 Returns the microsecond component of the date represented by this instance. More...
 
constexpr int nanosecond () const
 Returns the nanosecond component of the date represented by this instance. More...
 
constexpr bool isNull () const
 Returns ture if the date represented by the current DateTime class is null. More...
 
constexpr TimeSpan timeOfDay () const
 Returns the time of day as TimeSpan for this instance. More...
 
bool isLeapYear () const
 Returns an indication whether the year represented by this instance is a leap year. More...
 
constexpr bool isEternity () const
 Returns whether the instance has the maximal number of ticks. More...
 
constexpr bool isSameDay (const DateTime &other) const
 Returns and indication whether two DateTime instances represent the same day. More...
 
std::string toString (DateTimeOutputFormat format=DateTimeOutputFormat::DateAndTime, bool noMilliseconds=false) const
 Returns the string representation of the current instance using the specified format. More...
 
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. More...
 
std::string toIsoString (TimeSpan timeZoneDelta=TimeSpan()) const
 Returns the string representation of the current instance in the ISO format, eg. More...
 
constexpr std::time_t toTimeStamp () const
 Returns the UNIX timestamp for the current instance. More...
 
constexpr bool operator== (const DateTime &other) const
 Indicates whether two DateTime instances are equal. More...
 
constexpr bool operator!= (const DateTime &other) const
 Indicates whether two DateTime instances are not equal. More...
 
constexpr bool operator< (const DateTime &other) const
 Indicates whether a specified DateTime is less than another specified DateTime. More...
 
constexpr bool operator> (const DateTime &other) const
 Indicates whether a specified DateTime is greater than another specified DateTime. More...
 
constexpr bool operator<= (const DateTime &other) const
 Indicates whether a specified DateTime is less or equal than another specified DateTime. More...
 
constexpr bool operator>= (const DateTime &other) const
 Indicates whether a specified DateTime is greater or equal than another specified DateTime. More...
 
constexpr DateTime operator+ (const TimeSpan &timeSpan) const
 Adds another instance. More...
 
constexpr DateTime operator- (const TimeSpan &timeSpan) const
 Substracts another instance. More...
 
constexpr TimeSpan operator+ (const DateTime &other) const
 Adds two instances. More...
 
constexpr TimeSpan operator- (const DateTime &other) const
 Substracts two DateTime instances. More...
 
DateTimeoperator+= (const TimeSpan &timeSpan)
 Adds a TimeSpan to the current instance. More...
 
DateTimeoperator-= (const TimeSpan &timeSpan)
 Substracts a TimeSpan from the current instance. More...
 
template<typename TimePoint >
constexpr DateTime fromChronoTimePointGmt (TimePoint timePoint)
 Constructs a new DateTime object with the GMT time from the specified std::chrono::time_point. More...
 

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. More...
 
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. More...
 
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. More...
 
static DateTime fromString (const std::string &str)
 Parses the given std::string as DateTime. More...
 
static DateTime fromString (const char *str)
 Parses the given C-style string as DateTime. More...
 
static std::pair< DateTime, TimeSpanfromIsoString (const char *str)
 Parses the specified ISO date time denotation provided as C-style string. More...
 
static DateTime fromIsoStringGmt (const char *str)
 Parses the specified ISO date time denotation provided as C-style string. More...
 
static DateTime fromIsoStringLocal (const char *str)
 Parses the specified ISO date time denotation provided as C-style string. More...
 
static DateTime fromTimeStamp (std::time_t timeStamp)
 Constructs a new DateTime object with the local time from the specified UNIX timeStamp. More...
 
constexpr static DateTime fromTimeStampGmt (std::time_t timeStamp)
 Constructs a new DateTime object with the GMT time from the specified UNIX timeStamp. More...
 
template<typename TimePoint >
static DateTime fromChronoTimePoint (TimePoint timePoint)
 Constructs a new DateTime object with the local time from the specified std::chrono::time_point. More...
 
template<typename TimePoint >
constexpr static DateTime fromChronoTimePointGmt (TimePoint timePoint)
 
static const char * printDayOfWeek (DayOfWeek dayOfWeek, bool abbreviation=false)
 Returns the string representation as C-style string for the given day of week. More...
 
static constexpr DateTime eternity ()
 Constructs a new instance of the DateTime class with the maximal number of ticks. More...
 
static constexpr DateTime unixEpochStart ()
 Returns the DateTime object for the "1970-01-01T00:00:00Z". More...
 
static DateTime now ()
 Returns a DateTime object that is set to the current date and time on this computer, expressed as the local time. More...
 
static DateTime gmtNow ()
 Returns a DateTime object that is set to the current date and time on this computer, expressed as the GMT time. More...
 
constexpr static bool isLeapYear (int year)
 Returns an indication whether the specified year is a leap year. More...
 
static int daysInMonth (int year, int month)
 Returns the number of days in the specified month and year. More...
 

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:
  • Add method for parsing custom string formats.
  • Add method for printing to custom string formats.
  • Allow to determine the date part for each compontent at once to prevent multiple invocations of getDatePart().

Definition at line 51 of file datetime.h.

Constructor & Destructor Documentation

◆ DateTime() [1/2]

constexpr CppUtilities::DateTime::DateTime ( )
inlineexplicitconstexpr

Constructs a DateTime.

Definition at line 137 of file datetime.h.

◆ DateTime() [2/2]

constexpr CppUtilities::DateTime::DateTime ( std::uint64_t  ticks)
inlineexplicitconstexpr

Constructs a DateTime with the specified number of ticks.

Definition at line 145 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 281 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 298 of file datetime.h.

◆ dayOfYear()

int CppUtilities::DateTime::dayOfYear ( ) const
inline

Returns the day of the year represented by this instance.

Definition at line 289 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 397 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 433 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 231 of file datetime.h.

◆ fromChronoTimePointGmt() [1/2]

template<typename TimePoint >
constexpr static DateTime CppUtilities::DateTime::fromChronoTimePointGmt ( TimePoint  timePoint)
staticconstexpr

◆ fromChronoTimePointGmt() [2/2]

template<typename TimePoint >
constexpr DateTime CppUtilities::DateTime::fromChronoTimePointGmt ( TimePoint  timePoint)
constexpr

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 241 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 154 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 173 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 a time span which can be subtracted from the first value to get the UTC time.
Remarks
Not all variants allowed by ISO 8601 are supported right now, eg. delimiters can not be omitted. The common form (something like "2016-08-29T21:32:31.588539814+02:00") is supported of course.
See also
https://en.wikipedia.org/wiki/ISO_8601

Definition at line 119 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 201 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 213 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 79 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 190 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 163 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 59 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 221 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 459 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 306 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 381 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 373 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 389 of file datetime.h.

◆ isNull()

constexpr bool CppUtilities::DateTime::isNull ( ) const
inlineconstexpr

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

See also
DateTime

Definition at line 357 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 405 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 338 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 330 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 314 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 273 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 348 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 450 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 475 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 534 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 516 of file datetime.h.

◆ operator+=()

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

Adds a TimeSpan to the current instance.

Definition at line 553 of file datetime.h.

◆ operator-() [1/2]

constexpr TimeSpan CppUtilities::DateTime::operator- ( const DateTime other) const
inlineconstexpr

Substracts 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 545 of file datetime.h.

◆ operator-() [2/2]

constexpr DateTime CppUtilities::DateTime::operator- ( const TimeSpan timeSpan) const
inlineconstexpr

Substracts another instance.

Returns
The result is another DateTime.

Definition at line 525 of file datetime.h.

◆ operator-=()

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

Substracts a TimeSpan from the current instance.

Definition at line 562 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 483 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 499 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 467 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 491 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 507 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 253 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 322 of file datetime.h.

◆ ticks()

constexpr std::uint64_t & CppUtilities::DateTime::ticks ( )
inlineconstexpr

Returns a mutable reference to the total ticks.

Definition at line 249 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 365 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 216 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 415 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 189 of file datetime.cpp.

◆ totalTicks()

constexpr std::uint64_t CppUtilities::DateTime::totalTicks ( ) const
inlineconstexpr

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

Definition at line 257 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 425 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 441 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 265 of file datetime.h.


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