David Tribble's Proposal for ISO C++
Extended-Precision Time Classes

Extended-Precision Time Functions

Types

The standard header <time> contains a declaration for the following class type:

    namespace std
    {
        Class ETime;
    }

The ETime class contains the following members:

    private:
        etime_t    ticks;       // Number of ticks since zero date

For purposes of conversions to and from other time encoding types (such as struct tmx), the time encoded in type ETime uses the Gregorian calendar^1,2. Other conversions adhere to the ISO-8601 standard for representing dates and times.

Arithmetic operations can be performed on ETime values since it embodies an integer type. The difference between two ETime values represents the difference in time between the two dates, i.e., the number of microsecond ticks between them.

Relational operations can also be performed, providing an ordered relation between time values. The ETIME_UNKNOWN value is guaranteed to compare less than any other time value (see below).

Constants

The ETime class contains declarations for the following member constants:

    ETIME_MAX
    ETIME_MIN
    ETIME_UNKNOWN

Constant ETIME_MIN

    public:
        static const ETime      ETIME_MIN;

The ETIME_MIN constant represents the lowest valid time value. It is equal to the value (etime_t)INT64_MIN+1. (The macro INT64_MIN is defined in the standard <inttypes.h> header.)

Constant ETIME_MAX

    public:
        static const ETime      ETIME_MAX;

The ETIME_MAX constant represents the highest valid time value. It is equal to the value (etime_t)INT64_MAX. (The macro INT64_MAX is defined in the standard <inttypes.h> header.)

Constant ETIME_UNKNOWN

    public:
        static const ETime      ETIME_UNKNOWN;

The ETIME_UNKNOWN constant represents an unknown time value. It is equal to the value (etime_t)INT64_MIN, and is guaranteed to compare less than any other (valid) ETime value. (The macro INT64_MIN is defined in the standard <inttypes.h> header.)

Functions

The ETime class contains declarations for the following member functions:

    current_time()
    set_time()
    from_gmtime()
    from_localtime()
    to_gmtime()
    to_localtime()
    etime()
    year()
    month()
    week()
    mday()
    yday()
    wkday()
    hour()
    minute()
    sec()
    usec()
    add()
    diff()
    cmp()

Function current_time()

    public:
        static bool  current_time(ETime *t);

The current_time() function determines the current system time, and sets the value pointed to by t to this time. The value returned represents the time to the nearest microsecond, but encodes the time to the precision that the system is capable of representing. The value is guaranteed to be accurate to at least the nearest second, provided that the system is capable of discerning time. If successful, the function returns true. If the system time is not available, or if an error occurs, the value pointed to by t is set to ETIME_UNKNOWN and the function returns false. If pointer t is a null pointer, no assignment is attempted, and the function returns true or false as stated previously³.

Function set_time()

    public:
        bool  set_time(const ETime &e);
        bool  set_time(time_t t);

The set_time() function sets the value of the ETime object. The function returns true upon success.

Argument e refers to another extended time object.

Argument t is a system time value.

Function from_gmtime()

    public:
        bool  from_gmtime(const struct tm *s);
        bool  from_gmtime(const struct tmx *sx);

The from_gmtime() function sets the value of the ETime object from the broken-down time value pointed to by s or sx, relative to UTC time. The function returns true upon success.

Function from_localtime()

    public:
        bool  from_localtime(const struct tm *s);
        bool  from_localtime(const struct tmx *sx);

The from_localtime() function sets the value of the ETime object from the broken-down time value pointed to by s or sx, according to the local timezone. The function returns true upon success.

Function to_gmtime()

    public:
        bool  to_gmtime(struct tm *s);
        bool  to_gmtime(struct tmx *sx);

The to_gmtime() function sets the broken-down time value pointed to by s or sx from the value of the ETime object, relative to UTC time. The structure pointed to by s or sx will contain members with normalized date and time values. The function returns true upon success.

Function to_localtime()

    public:
        bool  to_localtime(struct tm *s);
        bool  to_localtime(struct tmx *sx);

The to_localtime() function sets the broken-down time value pointed to by s or sx from the value of the ETime object, relative to the local timezone. The structure pointed to by s or sx will contain members with normalized date and time values. The function returns true upon success.

Function etime()

    public:
        etime_t  etime() const;

The etime() function returns the extended time value (of type etime_t) of the ETime object. The function returns ETIME_UNKNOWN if the object does not represent a valid time value.

Function year()

    public:
        int  year() const;

The year() function returns the year number of the ETime object. The value shall cover at least the range [-17999,+17999]. Years prior to 1 A.D. are represented by values less than 1 (i.e., 1 B.C. is year number 0, 2 B.C. is year number -1, etc.). The function returns -1 if the object does not represent a valid time value (such as ETIME_UNKNOWN).

Function month()

    public:
        int  month() const;

The month() function returns the month number of the ETime object, in the range [0,11]. The function returns -1 if the object does not represent a valid time value (such as ETIME_UNKNOWN).

Function week()

    public:
        int  week() const;

The week() function returns the number of the week of the year of ETime object, in the range [0,53]. The first week of the year (i.e., week number 1) is the first week that contains a Thursday. The function returns -1 if the object does not represent a valid time value (such as ETIME_UNKNOWN).

Function mday()

    public:
        int  mday() const;

The mday() function returns the number of the day within the month of the ETime object, in the range [1,31]. The function returns -1 if the object does not represent a valid time value (such as ETIME_UNKNOWN).

Function yday()

    public:
        int  yday() const;

The yday() function returns the number of the day within the year of the ETime object, in the range [0,365]. The first day of the year (i.e., January 1st) is day number zero. The function returns -1 if the object does not represent a valid time value (such as ETIME_UNKNOWN).

Function wkday()

    public:
        int  wkday() const;

The wkday() function returns the number of the day of the week of the ETime object, in the range [0,6], where Sunday is day number zero. The function returns -1 if the object does not represent a valid time value (such as ETIME_UNKNOWN).

Function hour()

    public:
        int  hour() const;

The hour() function returns the hour of the ETime object, in the range [0,23]. The function returns -1 if the object does not represent a valid time value (such as ETIME_UNKNOWN).

Function minute()

    public:
        int  minute() const;

The minute() function returns the minute of the ETime object, in the range [0,59]. The function returns -1 if the object does not represent a valid time value (such as ETIME_UNKNOWN).

Function sec()

    public:
        int  sec() const;

The sec() function returns the second of the ETime object, in the range [0,60]. (This allows for possible leap seconds.) The function returns -1 if the object does not represent a valid time value (such as ETIME_UNKNOWN).

Function usec()

    public:
        int  usec() const;

The usec() function returns the microsecond of the ETime object, in the range [0,999999]. The function returns -1 if the object does not represent a valid time value (such as ETIME_UNKNOWN).

Function add()

    public:
        ETime &  add(const struct tmx *s);

The add() function adds the incremental time represented by the members of the broken-down time value pointed to by s to the ETime object, and returns a reference to the resulting time object. Adding a time increment to ETIME_UNKNOWN results in the value ETIME_UNKNOWN. The members of the structure pointed to by s are added to the time object in order of resolution, microseconds first, then seconds, and so on, ending in years. The tm_wday, tm_yday, and tm_isdst members of the structure are ignored.

Function diff()

    public:
        signed long long int  diff(const ETime &t);

The diff() function determines the difference in time between the ETime object and object t. The value returned is the number of ticks between the two times. If the this time object represents a time prior to time t, a negative value is returned. If either time value is equal to ETIME_UNKNOWN, the function returns ETIME_UNKNOWN.

    public:
        signed long long int  diff(const ETime &t, struct tmx *s);

The diff() function determines the difference in time between the ETime object and object t. The structure pointed to by s is filled with the difference, as measured in terms of years, months, days, hours, minutes, seconds, and subseconds, in that order. (Note that the resulting broken-down time structure will not represent a meaningful date, but rather serves to indicate the difference between two dates in a broken-down form.) The remaining members of the structure are set to zero. The function returns the difference between the two dates, represented as the number of ticks between them. If the this time object represents a time prior to time t, a negative value is returned. If either time value is equal to ETIME_UNKNOWN, the function returns ETIME_UNKNOWN.

...etc...

Operators

The ETime class contains declarations for the following member operator functions:

    operator =()
    operator +()
    operator -()
    operator ==()
    operator !=()
    operator >()
    operator >=()
    operator <()
    operator <=()

...etc...

Footnotes

1. The Gregorian calendar scheme is used regardless of the dates being represented, and regardless of the locale and regional calendars in use for the implementation. This provides a consistent and portable calendar encoding scheme.

2. Dates prior to 0001-01-01 (i.e., dates in the B.C. or B.C.E. era) are represented with negative year numbers, such that 1 B.C. is year number 0, 2 B.C. is year number -1, and so forth. (There being no year 0 A.D. or 0 B.C. in the Gregorian calendar.)

3. This is useful for determining if the implementation is capable of discerning time or not.

Prior Art

None.

References

• ISO C and C++ Proposal: Extended-Precision Time Functions by David R. Tribble, link to here or here.