1Chrono
2======
3
4When including the additional header file :file:`pybind11/chrono.h` conversions
5from C++11 chrono datatypes to python datetime objects are automatically enabled.
6This header also enables conversions of python floats (often from sources such
7as ``time.monotonic()``, ``time.perf_counter()`` and ``time.process_time()``)
8into durations.
9
10An overview of clocks in C++11
11------------------------------
12
13A point of confusion when using these conversions is the differences between
14clocks provided in C++11. There are three clock types defined by the C++11
15standard and users can define their own if needed. Each of these clocks have
16different properties and when converting to and from python will give different
17results.
18
19The first clock defined by the standard is ``std::chrono::system_clock``. This
20clock measures the current date and time. However, this clock changes with to
21updates to the operating system time. For example, if your time is synchronised
22with a time server this clock will change. This makes this clock a poor choice
23for timing purposes but good for measuring the wall time.
24
25The second clock defined in the standard is ``std::chrono::steady_clock``.
26This clock ticks at a steady rate and is never adjusted. This makes it excellent
27for timing purposes, however the value in this clock does not correspond to the
28current date and time. Often this clock will be the amount of time your system
29has been on, although it does not have to be. This clock will never be the same
30clock as the system clock as the system clock can change but steady clocks
31cannot.
32
33The third clock defined in the standard is ``std::chrono::high_resolution_clock``.
34This clock is the clock that has the highest resolution out of the clocks in the
35system. It is normally a typedef to either the system clock or the steady clock
36but can be its own independent clock. This is important as when using these
37conversions as the types you get in python for this clock might be different
38depending on the system.
39If it is a typedef of the system clock, python will get datetime objects, but if
40it is a different clock they will be timedelta objects.
41
42Provided conversions
43--------------------
44
45.. rubric:: C++ to Python
46
47- ``std::chrono::system_clock::time_point`` → ``datetime.datetime``
48    System clock times are converted to python datetime instances. They are
49    in the local timezone, but do not have any timezone information attached
50    to them (they are naive datetime objects).
51
52- ``std::chrono::duration`` → ``datetime.timedelta``
53    Durations are converted to timedeltas, any precision in the duration
54    greater than microseconds is lost by rounding towards zero.
55
56- ``std::chrono::[other_clocks]::time_point`` → ``datetime.timedelta``
57    Any clock time that is not the system clock is converted to a time delta.
58    This timedelta measures the time from the clocks epoch to now.
59
60.. rubric:: Python to C++
61
62- ``datetime.datetime`` or ``datetime.date`` or ``datetime.time`` → ``std::chrono::system_clock::time_point``
63    Date/time objects are converted into system clock timepoints. Any
64    timezone information is ignored and the type is treated as a naive
65    object.
66
67- ``datetime.timedelta`` → ``std::chrono::duration``
68    Time delta are converted into durations with microsecond precision.
69
70- ``datetime.timedelta`` → ``std::chrono::[other_clocks]::time_point``
71    Time deltas that are converted into clock timepoints are treated as
72    the amount of time from the start of the clocks epoch.
73
74- ``float`` → ``std::chrono::duration``
75    Floats that are passed to C++ as durations be interpreted as a number of
76    seconds. These will be converted to the duration using ``duration_cast``
77    from the float.
78
79- ``float`` → ``std::chrono::[other_clocks]::time_point``
80    Floats that are passed to C++ as time points will be interpreted as the
81    number of seconds from the start of the clocks epoch.
82