Class for performing date/time arithmetic, comparisons and formatting.
Thread-safety: This class is re-entrant.
This class represents points in a time continuum by
- a linear day counter, counting days passed since some fictitious "day zero", and
- a linear seconds counter, counting seconds since 0:00 am.
The class can represent a pure date, pure time and date-time.
In case of a pure time representation, year, month and day return zero because of backward compatibility. The same is true for a pure date representation.
The class provides member functions to convert between the internal representation and the usual one using year, month, day, hour, minute and second. There are also functions to compare two dates and to perform simple arithmetic, as adding/subtracting a number of days or seconds and computing the difference between two dates in either days or seconds.
Years, months, days, hours, minutes are represented by the type DateTime::DateTimeIntType which is a normal integer type.
Seconds and fractions of other time units are represented as DateTime::DateTimeFloatType, a normal floating point type.
The seconds counter is implemented as a double precision variable, hence it is able to measure fractions of a second with a precision in the nanosecond range.
The linear day counter counts days passed since the (non-existing) date 01-Jan-0000, assuming that the modern leap year rules would have been valid since the beginning of Common Era. It is well known that this is not true, so computations involving dates before 1752 (the year the Gregorian calendar has been established) are
A year is considered a leap year if
- it is a multiple of 400, or
- it is a multiple of 4 but not of 100.
Leap seconds and time zones are not supported.
The class supports three different time and date representations:
- Linear time: This is the internal representation using linear day and seconds counter as described above.
Calendar time: This is the usual representation using integer values for year, month, day, hour and minute and a double precision value for seconds. The valid ranges for these values are:
1 <= month <= 12 1 <= day <= Number of days in month 0 <= hour <= 23 0 <= minute <= 59 0 <= second < 60
The year number can be arbitrary, although numbers smaller than 1752 might make no sense (cf above). There is no implicit assumption on the century, i.e., the year 99 is NOT the year 1999, and 01 is NOT 2001.
Specifications outside the valid range are signaled as invalid and the value is not accepted. E.g. the date 2000-02-30 or the time stamp 12:61:00 are not accepted.
String representation: There are get() and set() methods for formatting the time as a string and for reading the time from a string. Only a complete date, a complete time or a complete date-time specification is accepted. In both cases, the format of the string has to specified using the following field specifiers:
%y : Year, two digits (only get())
%Y : Year, four digits
%m : Month
%d, %D : Day
%h, %H : Hour
%M : Minute
%s, %S : Second (as an integer)
%t, %T : Milliseconds, three digits
%r, %R : Microseconds, six digits (you can only use either
milliseconds or microseconds, not both) If no format is specified, the default format
%Y-%m-%d %H:%M:%S
is used.
Note that because of how the format string works, if you call
set("01.23", "%S.%T") you will get 1.023 seconds, because there were 23 milliseconds specified.
Definition at line 141 of file mlDateTime.h.
1.10.0