C++ Utilities  4.10.0
Common C++ classes and routines used by my applications such as argument parser, IO and conversion utilities
Public Member Functions | Static Public Member Functions | List of all members
ChronoUtilities::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 (uint64 ticks)
 Constructs a DateTime with the specified number of ticks. More...
 
constexpr uint64 totalTicks () const
 Gets the number of ticks which represent the value of the current instance. More...
 
int year () const
 Gets the year component of the date represented by this instance. More...
 
int month () const
 Gets the month component of the date represented by this instance. More...
 
int day () const
 Gets the day component of the date represented by this instance. More...
 
int dayOfYear () const
 Gets the day of the year represented by this instance. More...
 
constexpr DayOfWeek dayOfWeek () const
 Gets the day of the week represented by this instance. More...
 
constexpr int hour () const
 Gets the hour component of the date represented by this instance. More...
 
constexpr int minute () const
 Gets the minute component of the date represented by this instance. More...
 
constexpr int second () const
 Gets the second component of the date represented by this instance. More...
 
constexpr int millisecond () const
 Gets the millisecond component of the date represented by this instance. More...
 
constexpr int microsecond () const
 Gets the microsecond component of the date represented by this instance. More...
 
constexpr int nanosecond () const
 Gets 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
 Gets the time of day as TimeSpan for this instance. More...
 
bool isLeapYear () const
 Returns an indication whether the year of the dae 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 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...
 

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 (time_t timeStamp)
 Constructs a new DateTime object with the local time from the specified UNIX timeStamp. More...
 
static DateTime fromTimeStampGmt (time_t timeStamp)
 Constructs a new DateTime object with the GMT time from the specified UNIX timeStamp. More...
 
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...
 
static constexpr 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 GregorianCalendar calendar (excluding ticks that would be added by leap seconds).
  • There is no time zone information associated. Hence different time zones are not taken into account when comparing two instances. For instance the expression (DateTime::now() - DateTime::gmtNow()) returns one hour in Germany (instead of zero).

Definition at line 51 of file datetime.h.

Constructor & Destructor Documentation

◆ DateTime() [1/2]

constexpr ChronoUtilities::DateTime::DateTime ( )
inlineexplicit

Constructs a DateTime.

Definition at line 133 of file datetime.h.

◆ DateTime() [2/2]

constexpr ChronoUtilities::DateTime::DateTime ( uint64  ticks)
inlineexplicit

Constructs a DateTime with the specified number of ticks.

Definition at line 141 of file datetime.h.

Member Function Documentation

◆ day()

int ChronoUtilities::DateTime::day ( ) const
inline

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

Definition at line 229 of file datetime.h.

◆ dayOfWeek()

constexpr DayOfWeek ChronoUtilities::DateTime::dayOfWeek ( ) const
inline

Gets the day of the week represented by this instance.

See also
DayOfWeek

Definition at line 246 of file datetime.h.

◆ dayOfYear()

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

Gets the day of the year represented by this instance.

Definition at line 237 of file datetime.h.

◆ daysInMonth()

int ChronoUtilities::DateTime::daysInMonth ( int  year,
int  month 
)
inlinestatic

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

Definition at line 345 of file datetime.h.

◆ eternity()

constexpr DateTime ChronoUtilities::DateTime::eternity ( )
inlinestatic

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

Definition at line 361 of file datetime.h.

◆ fromDate()

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

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

Definition at line 149 of file datetime.h.

◆ fromDateAndTime()

DateTime ChronoUtilities::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.

Definition at line 165 of file datetime.h.

◆ fromIsoString()

std::pair< DateTime, TimeSpan > 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 sure whether it is actually ISO conform, but it parses denotations like "2016-08-29T21:32:31.588539814+02:00".

Definition at line 116 of file datetime.cpp.

◆ fromIsoStringGmt()

DateTime ChronoUtilities::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.
See also
fromIsoString()

Definition at line 186 of file datetime.h.

◆ fromIsoStringLocal()

DateTime ChronoUtilities::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.
See also
fromIsoString()

Definition at line 197 of file datetime.h.

◆ fromString() [1/2]

DateTime ChronoUtilities::DateTime::fromString ( const std::string &  str)
inlinestatic

Parses the given std::string as DateTime.

Definition at line 176 of file datetime.h.

◆ fromString() [2/2]

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

Parses the given C-style string as DateTime.

Definition at line 78 of file datetime.cpp.

◆ fromTime()

DateTime ChronoUtilities::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.

Definition at line 157 of file datetime.h.

◆ fromTimeStamp()

DateTime DateTime::fromTimeStamp ( time_t  timeStamp)
static

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

Definition at line 56 of file datetime.cpp.

◆ fromTimeStampGmt()

DateTime DateTime::fromTimeStampGmt ( time_t  timeStamp)
static

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

Definition at line 70 of file datetime.cpp.

◆ gmtNow()

DateTime ChronoUtilities::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 387 of file datetime.h.

◆ hour()

constexpr int ChronoUtilities::DateTime::hour ( ) const
inline

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

Definition at line 254 of file datetime.h.

◆ isEternity()

constexpr bool ChronoUtilities::DateTime::isEternity ( ) const
inline

Returns whether the instance has the maximal number of ticks.

Definition at line 329 of file datetime.h.

◆ isLeapYear() [1/2]

bool ChronoUtilities::DateTime::isLeapYear ( ) const
inline

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

Definition at line 321 of file datetime.h.

◆ isLeapYear() [2/2]

constexpr bool ChronoUtilities::DateTime::isLeapYear ( int  year)
inlinestatic

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

Definition at line 337 of file datetime.h.

◆ isNull()

constexpr bool ChronoUtilities::DateTime::isNull ( ) const
inline

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

See also
DateTime

Definition at line 305 of file datetime.h.

◆ isSameDay()

constexpr bool ChronoUtilities::DateTime::isSameDay ( const DateTime other) const
inline

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

Definition at line 353 of file datetime.h.

◆ microsecond()

constexpr int ChronoUtilities::DateTime::microsecond ( ) const

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

Definition at line 286 of file datetime.h.

◆ millisecond()

constexpr int ChronoUtilities::DateTime::millisecond ( ) const
inline

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

Definition at line 278 of file datetime.h.

◆ minute()

constexpr int ChronoUtilities::DateTime::minute ( ) const
inline

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

Definition at line 262 of file datetime.h.

◆ month()

int ChronoUtilities::DateTime::month ( ) const
inline

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

Definition at line 221 of file datetime.h.

◆ nanosecond()

constexpr int ChronoUtilities::DateTime::nanosecond ( ) const

Gets 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 296 of file datetime.h.

◆ now()

DateTime ChronoUtilities::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 378 of file datetime.h.

◆ operator!=()

constexpr bool ChronoUtilities::DateTime::operator!= ( const DateTime other) const
inline

Indicates whether two DateTime instances are not equal.

Definition at line 403 of file datetime.h.

◆ operator+() [1/2]

constexpr DateTime ChronoUtilities::DateTime::operator+ ( const TimeSpan timeSpan) const
inline

Adds another instance.

Returns
The result is another DateTime.

Definition at line 444 of file datetime.h.

◆ operator+() [2/2]

constexpr TimeSpan ChronoUtilities::DateTime::operator+ ( const DateTime other) const
inline

Adds two instances.

Returns
The result is a TimeSpan.

Definition at line 462 of file datetime.h.

◆ operator+=()

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

Adds a TimeSpan to the current instance.

Definition at line 479 of file datetime.h.

◆ operator-() [1/2]

constexpr DateTime ChronoUtilities::DateTime::operator- ( const TimeSpan timeSpan) const
inline

Substracts another instance.

Returns
The result is another DateTime.

Definition at line 453 of file datetime.h.

◆ operator-() [2/2]

constexpr TimeSpan ChronoUtilities::DateTime::operator- ( const DateTime other) const
inline

Substracts two DateTime instances.

Returns
The result is a TimeSpan.

Definition at line 471 of file datetime.h.

◆ operator-=()

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

Substracts a TimeSpan from the current instance.

Definition at line 488 of file datetime.h.

◆ operator<()

constexpr bool ChronoUtilities::DateTime::operator< ( const DateTime other) const
inline

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

Definition at line 411 of file datetime.h.

◆ operator<=()

constexpr bool ChronoUtilities::DateTime::operator<= ( const DateTime other) const
inline

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

Definition at line 427 of file datetime.h.

◆ operator==()

constexpr bool ChronoUtilities::DateTime::operator== ( const DateTime other) const
inline

Indicates whether two DateTime instances are equal.

Definition at line 395 of file datetime.h.

◆ operator>()

constexpr bool ChronoUtilities::DateTime::operator> ( const DateTime other) const
inline

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

Definition at line 419 of file datetime.h.

◆ operator>=()

constexpr bool ChronoUtilities::DateTime::operator>= ( const DateTime other) const
inline

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

Definition at line 435 of file datetime.h.

◆ printDayOfWeek()

const char * 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 252 of file datetime.cpp.

◆ second()

constexpr int ChronoUtilities::DateTime::second ( ) const
inline

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

Definition at line 270 of file datetime.h.

◆ timeOfDay()

constexpr TimeSpan ChronoUtilities::DateTime::timeOfDay ( ) const
inline

Gets the time of day as TimeSpan for this instance.

Definition at line 313 of file datetime.h.

◆ toIsoString()

string 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 220 of file datetime.cpp.

◆ toString() [1/2]

string DateTime::toString ( 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 181 of file datetime.cpp.

◆ toString() [2/2]

void 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 193 of file datetime.cpp.

◆ totalTicks()

constexpr uint64 ChronoUtilities::DateTime::totalTicks ( ) const
inline

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

Definition at line 205 of file datetime.h.

◆ unixEpochStart()

constexpr DateTime ChronoUtilities::DateTime::unixEpochStart ( )
inlinestatic

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

Definition at line 369 of file datetime.h.

◆ year()

int ChronoUtilities::DateTime::year ( ) const
inline

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

Definition at line 213 of file datetime.h.


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