C++ Utilities  4.17.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
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...
 
uint64ticks ()
 Returns a mutable reference to the total ticks. More...
 
constexpr uint64 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 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 during winter time (instead of zero).
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().
  • Make more methods constexpr.

Definition at line 52 of file datetime.h.

Constructor & Destructor Documentation

◆ DateTime() [1/2]

constexpr ChronoUtilities::DateTime::DateTime ( )
inlineexplicit

Constructs a DateTime.

Definition at line 135 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 143 of file datetime.h.

Member Function Documentation

◆ day()

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

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

Definition at line 251 of file datetime.h.

◆ dayOfWeek()

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

Returns the day of the week represented by this instance.

See also
DayOfWeek

Definition at line 268 of file datetime.h.

◆ dayOfYear()

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

Returns the day of the year represented by this instance.

Definition at line 259 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 367 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 383 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.

Exceptions
Throwsa ConversionException if the specified year, month or day is out-of-range.

Definition at line 152 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.

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

Definition at line 171 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 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 127 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.
Exceptions
Throwsa ConversionException if the specified str does not match the expected time format.
See also
fromIsoString()

Definition at line 199 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.
Exceptions
Throwsa ConversionException if the specified str does not match the expected time format.
See also
fromIsoString()

Definition at line 211 of file datetime.h.

◆ fromString() [1/2]

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

◆ fromString() [2/2]

DateTime 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 87 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.

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

Definition at line 161 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 59 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 73 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 409 of file datetime.h.

◆ hour()

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

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

Definition at line 276 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 351 of file datetime.h.

◆ isLeapYear() [1/2]

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

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

Definition at line 343 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 359 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 327 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 375 of file datetime.h.

◆ microsecond()

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

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

Definition at line 308 of file datetime.h.

◆ millisecond()

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

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

Definition at line 300 of file datetime.h.

◆ minute()

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

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

Definition at line 284 of file datetime.h.

◆ month()

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

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

Definition at line 243 of file datetime.h.

◆ nanosecond()

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

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 318 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 400 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 425 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 466 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 484 of file datetime.h.

◆ operator+=()

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

Adds a TimeSpan to the current instance.

Definition at line 503 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 475 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.
Remarks
For expressing the delta between two concrete DateTime instances in terms of years, month and days, use Period::Period instead.

Definition at line 495 of file datetime.h.

◆ operator-=()

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

Substracts a TimeSpan from the current instance.

Definition at line 512 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 433 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 449 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 417 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 441 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 457 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 273 of file datetime.cpp.

◆ second()

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

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

Definition at line 292 of file datetime.h.

◆ ticks()

uint64 & ChronoUtilities::DateTime::ticks ( )
inline

Returns a mutable reference to the total ticks.

Definition at line 219 of file datetime.h.

◆ timeOfDay()

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

Returns the time of day as TimeSpan for this instance.

Definition at line 335 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 236 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 197 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 209 of file datetime.cpp.

◆ totalTicks()

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

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

Definition at line 227 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 391 of file datetime.h.

◆ year()

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

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

Definition at line 235 of file datetime.h.


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