advanced/cast/chrono.rst

0001 Chrono
0002 ======
0003
0004 When including the additional header file :file:`pybind11/chrono.h` conversions
0005 from C++11 chrono datatypes to python datetime objects are automatically enabled.
0006 This header also enables conversions of python floats (often from sources such
0007 as ``time.monotonic()``, ``time.perf_counter()`` and ``time.process_time()``)
0008 into durations.
0009
0010 An overview of clocks in C++11
0011 ------------------------------
0012
0013 A point of confusion when using these conversions is the differences between
0014 clocks provided in C++11. There are three clock types defined by the C++11
0015 standard and users can define their own if needed. Each of these clocks have
0016 different properties and when converting to and from python will give different
0017 results.
0018
0019 The first clock defined by the standard is ``std::chrono::system_clock``. This
0020 clock measures the current date and time. However, this clock changes with to
0021 updates to the operating system time. For example, if your time is synchronised
0022 with a time server this clock will change. This makes this clock a poor choice
0023 for timing purposes but good for measuring the wall time.
0024
0025 The second clock defined in the standard is ``std::chrono::steady_clock``.
0026 This clock ticks at a steady rate and is never adjusted. This makes it excellent
0027 for timing purposes, however the value in this clock does not correspond to the
0028 current date and time. Often this clock will be the amount of time your system
0029 has been on, although it does not have to be. This clock will never be the same
0030 clock as the system clock as the system clock can change but steady clocks
0031 cannot.
0032
0033 The third clock defined in the standard is ``std::chrono::high_resolution_clock``.
0034 This clock is the clock that has the highest resolution out of the clocks in the
0035 system. It is normally a typedef to either the system clock or the steady clock
0036 but can be its own independent clock. This is important as when using these
0037 conversions as the types you get in python for this clock might be different
0038 depending on the system.
0039 If it is a typedef of the system clock, python will get datetime objects, but if
0040 it is a different clock they will be timedelta objects.
0041
0042 Provided conversions
0043 --------------------
0044
0045 .. rubric:: C++ to Python
0046
0047 - ``std::chrono::system_clock::time_point`` → ``datetime.datetime``
0048     System clock times are converted to python datetime instances. They are
0049     in the local timezone, but do not have any timezone information attached
0050     to them (they are naive datetime objects).
0051
0052 - ``std::chrono::duration`` → ``datetime.timedelta``
0053     Durations are converted to timedeltas, any precision in the duration
0054     greater than microseconds is lost by rounding towards zero.
0055
0056 - ``std::chrono::[other_clocks]::time_point`` → ``datetime.timedelta``
0057     Any clock time that is not the system clock is converted to a time delta.
0058     This timedelta measures the time from the clocks epoch to now.
0059
0060 .. rubric:: Python to C++
0061
0062 - ``datetime.datetime`` or ``datetime.date`` or ``datetime.time`` → ``std::chrono::system_clock::time_point``
0063     Date/time objects are converted into system clock timepoints. Any
0064     timezone information is ignored and the type is treated as a naive
0065     object.
0066
0067 - ``datetime.timedelta`` → ``std::chrono::duration``
0068     Time delta are converted into durations with microsecond precision.
0069
0070 - ``datetime.timedelta`` → ``std::chrono::[other_clocks]::time_point``
0071     Time deltas that are converted into clock timepoints are treated as
0072     the amount of time from the start of the clocks epoch.
0073
0074 - ``float`` → ``std::chrono::duration``
0075     Floats that are passed to C++ as durations be interpreted as a number of
0076     seconds. These will be converted to the duration using ``duration_cast``
0077     from the float.
0078
0079 - ``float`` → ``std::chrono::[other_clocks]::time_point``
0080     Floats that are passed to C++ as time points will be interpreted as the
0081     number of seconds from the start of the clocks epoch.