chrono.rst revision 14299
111986Sandreas.sandberg@arm.comChrono 211986Sandreas.sandberg@arm.com====== 311986Sandreas.sandberg@arm.com 411986Sandreas.sandberg@arm.comWhen including the additional header file :file:`pybind11/chrono.h` conversions 511986Sandreas.sandberg@arm.comfrom C++11 chrono datatypes to python datetime objects are automatically enabled. 611986Sandreas.sandberg@arm.comThis header also enables conversions of python floats (often from sources such 712037Sandreas.sandberg@arm.comas ``time.monotonic()``, ``time.perf_counter()`` and ``time.process_time()``) 812037Sandreas.sandberg@arm.cominto durations. 911986Sandreas.sandberg@arm.com 1011986Sandreas.sandberg@arm.comAn overview of clocks in C++11 1111986Sandreas.sandberg@arm.com------------------------------ 1211986Sandreas.sandberg@arm.com 1311986Sandreas.sandberg@arm.comA point of confusion when using these conversions is the differences between 1411986Sandreas.sandberg@arm.comclocks provided in C++11. There are three clock types defined by the C++11 1511986Sandreas.sandberg@arm.comstandard and users can define their own if needed. Each of these clocks have 1611986Sandreas.sandberg@arm.comdifferent properties and when converting to and from python will give different 1711986Sandreas.sandberg@arm.comresults. 1811986Sandreas.sandberg@arm.com 1911986Sandreas.sandberg@arm.comThe first clock defined by the standard is ``std::chrono::system_clock``. This 2011986Sandreas.sandberg@arm.comclock measures the current date and time. However, this clock changes with to 2111986Sandreas.sandberg@arm.comupdates to the operating system time. For example, if your time is synchronised 2211986Sandreas.sandberg@arm.comwith a time server this clock will change. This makes this clock a poor choice 2311986Sandreas.sandberg@arm.comfor timing purposes but good for measuring the wall time. 2411986Sandreas.sandberg@arm.com 2511986Sandreas.sandberg@arm.comThe second clock defined in the standard is ``std::chrono::steady_clock``. 2611986Sandreas.sandberg@arm.comThis clock ticks at a steady rate and is never adjusted. This makes it excellent 2711986Sandreas.sandberg@arm.comfor timing purposes, however the value in this clock does not correspond to the 2811986Sandreas.sandberg@arm.comcurrent date and time. Often this clock will be the amount of time your system 2911986Sandreas.sandberg@arm.comhas been on, although it does not have to be. This clock will never be the same 3011986Sandreas.sandberg@arm.comclock as the system clock as the system clock can change but steady clocks 3111986Sandreas.sandberg@arm.comcannot. 3211986Sandreas.sandberg@arm.com 3311986Sandreas.sandberg@arm.comThe third clock defined in the standard is ``std::chrono::high_resolution_clock``. 3411986Sandreas.sandberg@arm.comThis clock is the clock that has the highest resolution out of the clocks in the 3511986Sandreas.sandberg@arm.comsystem. It is normally a typedef to either the system clock or the steady clock 3611986Sandreas.sandberg@arm.combut can be its own independent clock. This is important as when using these 3711986Sandreas.sandberg@arm.comconversions as the types you get in python for this clock might be different 3811986Sandreas.sandberg@arm.comdepending on the system. 3911986Sandreas.sandberg@arm.comIf it is a typedef of the system clock, python will get datetime objects, but if 4011986Sandreas.sandberg@arm.comit is a different clock they will be timedelta objects. 4111986Sandreas.sandberg@arm.com 4211986Sandreas.sandberg@arm.comProvided conversions 4311986Sandreas.sandberg@arm.com-------------------- 4411986Sandreas.sandberg@arm.com 4511986Sandreas.sandberg@arm.com.. rubric:: C++ to Python 4611986Sandreas.sandberg@arm.com 4711986Sandreas.sandberg@arm.com- ``std::chrono::system_clock::time_point`` → ``datetime.datetime`` 4811986Sandreas.sandberg@arm.com System clock times are converted to python datetime instances. They are 4911986Sandreas.sandberg@arm.com in the local timezone, but do not have any timezone information attached 5011986Sandreas.sandberg@arm.com to them (they are naive datetime objects). 5111986Sandreas.sandberg@arm.com 5211986Sandreas.sandberg@arm.com- ``std::chrono::duration`` → ``datetime.timedelta`` 5311986Sandreas.sandberg@arm.com Durations are converted to timedeltas, any precision in the duration 5411986Sandreas.sandberg@arm.com greater than microseconds is lost by rounding towards zero. 5511986Sandreas.sandberg@arm.com 5611986Sandreas.sandberg@arm.com- ``std::chrono::[other_clocks]::time_point`` → ``datetime.timedelta`` 5711986Sandreas.sandberg@arm.com Any clock time that is not the system clock is converted to a time delta. 5811986Sandreas.sandberg@arm.com This timedelta measures the time from the clocks epoch to now. 5911986Sandreas.sandberg@arm.com 6011986Sandreas.sandberg@arm.com.. rubric:: Python to C++ 6111986Sandreas.sandberg@arm.com 6214299Sbbruce@ucdavis.edu- ``datetime.datetime`` or ``datetime.date`` or ``datetime.time`` → ``std::chrono::system_clock::time_point`` 6311986Sandreas.sandberg@arm.com Date/time objects are converted into system clock timepoints. Any 6411986Sandreas.sandberg@arm.com timezone information is ignored and the type is treated as a naive 6511986Sandreas.sandberg@arm.com object. 6611986Sandreas.sandberg@arm.com 6711986Sandreas.sandberg@arm.com- ``datetime.timedelta`` → ``std::chrono::duration`` 6811986Sandreas.sandberg@arm.com Time delta are converted into durations with microsecond precision. 6911986Sandreas.sandberg@arm.com 7011986Sandreas.sandberg@arm.com- ``datetime.timedelta`` → ``std::chrono::[other_clocks]::time_point`` 7111986Sandreas.sandberg@arm.com Time deltas that are converted into clock timepoints are treated as 7211986Sandreas.sandberg@arm.com the amount of time from the start of the clocks epoch. 7311986Sandreas.sandberg@arm.com 7411986Sandreas.sandberg@arm.com- ``float`` → ``std::chrono::duration`` 7511986Sandreas.sandberg@arm.com Floats that are passed to C++ as durations be interpreted as a number of 7611986Sandreas.sandberg@arm.com seconds. These will be converted to the duration using ``duration_cast`` 7711986Sandreas.sandberg@arm.com from the float. 7811986Sandreas.sandberg@arm.com 7911986Sandreas.sandberg@arm.com- ``float`` → ``std::chrono::[other_clocks]::time_point`` 8011986Sandreas.sandberg@arm.com Floats that are passed to C++ as time points will be interpreted as the 8111986Sandreas.sandberg@arm.com number of seconds from the start of the clocks epoch. 82