Time Point

The starting point (epoch) and the additional time duration define the time point. It consists of two components, clock and time duration.

Time Point

Time point is a class template. std::chrono::time_point requires a clock. By default, the time duration is derived from the clock. 

template<
  class Clock,
  class Duration= typename Clock::duration
>
class time_point;

There a four special time points depending on the clock.

• epoch: The starting point of the clock.
• now: The current time.
• min: The minimum time point that the clock can display.
• max: The maximum time point that the clock can display.

The accuracy of the values depends on the used clock:  std::system::system_clock, std::chrono::steady_clock, or std::chrono::high_resolution_clock.

C++ gives no guarantee about a clock's accuracy, starting point, or valid time range. The starting point of std::chrono::system_clock is typically the 1.1.1970, the so-called UNIX-epoch. It holds further that the std::chrono::high_resolution clock has the highest accuracy.

Displaying a time duration as a date

If the time point uses internally std::chrono::system_clock, you can convert the time point with the help of std::chrono::system_clock::to_time_t in an object of type std::time_t. Thanks to further conversions with the functions std::gmtime and std::asctime, you have the time points as dates in textual representation available.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// timepoint.cpp

#include <chrono>
#include <ctime>
#include <iomanip>
#include <iostream>
#include <string>

int main(){  
    
    std::cout << std::endl;
    
    std::chrono::time_point<std::chrono::system_clock> sysTimePoint;
    std::time_t tp= std::chrono::system_clock::to_time_t(sysTimePoint);
    std::string sTp= std::asctime(std::gmtime(&tp));
    std::cout << "Epoch: " << sTp << std::endl;
    
    tp= std::chrono::system_clock::to_time_t(sysTimePoint.min());
    sTp= std::asctime(std::gmtime(&tp));
    std::cout << "Time min: " << sTp << std::endl;
    
    tp= std::chrono::system_clock::to_time_t(sysTimePoint.max());
    sTp= std::asctime(std::gmtime(&tp));
    std::cout << "Time max: " << sTp << std::endl;
    
    sysTimePoint= std::chrono::system_clock::now();
    tp= std::chrono::system_clock::to_time_t(sysTimePoint);
    sTp= std::asctime(std::gmtime(&tp));
    std::cout << "Time now: " << sTp << std::endl;
    
}

The output of the program shows the valid range of std::chrono::system_clock. std::chrono::system_clock has the UNIX-epoch as starting point and can have time points between 1677 and 2262.

You can add time durations to time points to get new time points. Now I'm curious. What will happen if I'm out of the valid range of the time points?

Beyond the boundaries of the valid time range

My experiment uses the current time and adds 1000 years or subtracts 1000 years from it. I ignore leap years and assume that the year has 365 days for simplicity.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// timepointAddition.cpp

#include <chrono>
#include <ctime>
#include <iomanip>
#include <iostream>
#include <string>

using namespace std::chrono;

std::string timePointAsString(const time_point<system_clock>& timePoint){
    std::time_t tp= system_clock::to_time_t(timePoint);
    return std::asctime(std::gmtime(&tp));
}

int main(){  
    
    std::cout << std::endl;
    
    time_point<system_clock> nowTimePoint= system_clock::now();
    std::cout << "Now:              " << timePointAsString(nowTimePoint) << std::endl;
     
    auto thousandYears=  hours(24*365*1000);
    time_point<system_clock>  historyTimePoint= nowTimePoint - thousandYears;
    std::cout << "Now - 1000 years: " << timePointAsString(historyTimePoint) << std::endl;
    
    time_point<system_clock>  futureTimePoint= nowTimePoint + thousandYears;
    std::cout << "Now + 1000 years: " << timePointAsString(futureTimePoint) << std::endl;
     
}

For the sake of readability, I introduced the namespace std::chrono. The program's output shows that an overflow of the time points in lines 24 and 27 causes wrong results. Subtracting 1000 years from the current time point gives a time point in the future; adding 1000 years to the current time point gives a time point in the past, respectively.

What's next?  

The difference between two time points is the time duration. Time durations support the basic arithmetic and can be displayed in different time ticks. How? Wait for the next post.