Introduction -- Header -- Construction -- Count Based Construction -- Construct from String -- Accessors -- Conversion To String -- Operators -- Struct tm Functions Introduction The class boost::posix_time::time_duration the base type responsible for representing a length of time. A duration can be either positive or negative. The general time_duration class provides a constructor that takes a count of the number of hours, minutes, seconds, and fractional seconds count as shown in the code fragment below. The resolution of the time_duration is configure able at compile time. See Build-Compiler Information for more information. using namespace boost::posix_time; time_duration td(1,2,3,4); //01:02:03.000000004 when resolution is nano seconds time_duration td(1,2,3,4); //01:02:03.000004 when resolution is micro seconds Several small helper classes that derive from a base time_duration, as shown below, to adjust for different resolutions. These classes can shorten code and make the intent clearer. As an example: using namespace boost::posix_time; time_duration td = hours(1) + seconds(10); //01:00:10 td = hours(1) + nanoseconds(5); //01:00:00.000000005 Note that the existence of the higher resolution classes (eg: nanoseconds) depends on the installation of the library. See Build-Compiler Information for more information. Another way to handle this is to utilize the ticks_per_second() method of time_duration to write code that is portable no matter how the library is compiled. The general equation for calculating a resolution independent count is as follows: count*(time_duration_ticks_per_second / count_ticks_per_second) For example, let's suppose we want to construct using a count that represents tenths of a second. That is, each tick is 0.1 second. int number_of_tenths = 5; //create a resolution independent count -- divide by 10 since there are //10 tenths in a second. int count = number_of_tenths*(time_duration::ticks_per_second()/10); time_duration td(1,2,3,count); //01:02:03.5 //no matter the resolution settings Header #include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o or #include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types Construction Syntax Description Example time_duration(hours, minutes, seconds, fractional_seconds) Construct a duration from the counts. The fractional_second parameter is a number of units and is therefore affected by the resolution the application is compiled with (see Build-Compiler Information). If the fractional_seconds argument exceeds the limit of the compiled precision, the excess value will be "carried over" into the seconds field. See above for techniques to creating a resolution independent count. time_duration td(1,2,3,9); //1 hr 2 min 3 sec 9 nanoseconds time_duration td2(1,2,3,123456789); time_duration td3(1,2,3,1000); // with microsecond resolution (6 digits) // td2 => "01:04:06.456789" // td3 => "01:02:03.001000" // with nanosecond resolution (9 digits) // td2 => "01:02:03.123456789" // td3 => "01:02:03.000001000" time_duration(special_value sv) Special values constructor. Important note: When a time_duration is a special value, either by construction or other means, the following accessor functions will give unpredictable results: hours(), minutes(), seconds(), ticks(), fractional_seconds(), total_nanoseconds(), total_microseconds(), total_milliseconds(), total_seconds()The remaining accessor functions will work as expected. Count Based Construction Syntax Description Example hours(long) Number of hours time_duration td = hours(3); minutes(long) Number of minutes time_duration td = minutes(3); seconds(long) Number of seconds time_duration td = seconds(3); milliseconds(long) Number of milliseconds. time_duration td = milliseconds(3); microseconds(long) Number of microseconds. time_duration td = microseconds(3); nanoseconds(long) Number of nanoseconds. time_duration td = nanoseconds(3); Construct from String Syntax Description Example time_duration duration_from_string(std::string) From delimited string. NOTE: Excess digits in fractional seconds will be dropped. Ex: "1:02:03.123456999" => 1:02:03.123456. This behavior is affected by the precision the library is compiled with (see Build-Compiler Information. std::string ts("23:59:59.000"); time_duration td(duration_from_string(ts)); Accessors Syntax Description Example boost::int64_t hours() Get the number of normalized hours (will give unpredictable results if calling time_duration is a special_value). time_duration td(1,2,3); time_duration neg_td(-1,2,3); td.hours(); // --> 1 neg_td.hours(); // --> -1 boost::int64_t minutes() Get the number of minutes normalized +/-(0..59) (will give unpredictable results if calling time_duration is a special_value). time_duration td(1,2,3); time_duration neg_td(-1,2,3); td.minutes(); // --> 2 neg_td.minutes(); // --> -2 boost::int64_t seconds() const Get the normalized number of second +/-(0..59) (will give unpredictable results if calling time_duration is a special_value). time_duration td(1,2,3); time_duration neg_td(-1,2,3); td.seconds(); // --> 3 neg_td.seconds(); // --> -3 boost::int64_t total_seconds() const Get the total number of seconds truncating any fractional seconds (will give unpredictable results if calling time_duration is a special_value). time_duration td(1,2,3,10); td.total_seconds(); // --> (1*3600) + (2*60) + 3 == 3723 boost::int64_t total_milliseconds() const Get the total number of milliseconds truncating any remaining digits (will give unpredictable results if calling time_duration is a special_value). time_duration td(1,2,3,123456789); td.total_milliseconds(); // HMS --> (1*3600) + (2*60) + 3 == 3723 seconds // milliseconds is 3 decimal places // (3723 * 1000) + 123 == 3723123 boost::int64_t total_microseconds() const Get the total number of microseconds truncating any remaining digits (will give unpredictable results if calling time_duration is a special_value). time_duration td(1,2,3,123456789); td.total_microseconds(); // HMS --> (1*3600) + (2*60) + 3 == 3723 seconds // microseconds is 6 decimal places // (3723 * 1000000) + 123456 == 3723123456 boost::int64_t total_nanoseconds() const Get the total number of nanoseconds truncating any remaining digits (will give unpredictable results if calling time_duration is a special_value). time_duration td(1,2,3,123456789); td.total_nanoseconds(); // HMS --> (1*3600) + (2*60) + 3 == 3723 seconds // nanoseconds is 9 decimal places // (3723 * 1000000000) + 123456789 // == 3723123456789 boost::int64_t fractional_seconds() const Get the number of fractional seconds (will give unpredictable results if calling time_duration is a special_value). time_duration td(1,2,3, 1000); td.fractional_seconds(); // --> 1000 bool is_negative() const True if and only if duration is negative. time_duration td(-1,0,0); td.is_negative(); // --> true bool is_zero() const True if and only if duration is zero. time_duration td(0,0,0); td.is_zero(); // --> true bool is_positive() const True if and only if duration is positive. time_duration td(1,0,0); td.is_positive(); // --> true time_duration invert_sign() const Generate a new duration with the sign inverted. time_duration td(-1,0,0); td.invert_sign(); // --> 01:00:00 time_duration abs() const Generate a new duration with the absolute value of the time duration. time_duration td(-1,0,0); td.abs(); // --> 01:00:00 time_duration td(+1,0,0); td.abs(); // --> 01:00:00 date_time::time_resolutions time_duration::resolution() Describes the resolution capability of the time_duration class. time_resolutions is an enum of resolution possibilities ranging from seconds to nanoseconds. time_duration::resolution() --> nano unsigned short time_duration::num_fractional_digits() Returns the number of fractional digits the time resolution has. unsigned short secs; secs = time_duration::num_fractional_digits(); // 9 for nano, 6 for micro, etc. boost::int64_t time_duration::ticks_per_second() Return the number of ticks in a second. For example, if the duration supports nanoseconds then the returned result will be 1,000,000,000 (1e+9). std::cout << time_duration::ticks_per_second(); boost::int64_t ticks() Return the raw count of the duration type (will give unpredictable results if calling time_duration is a special_value). time_duration td(0,0,0, 1000); td.ticks() // --> 1000 time_duration time_duration::unit() Return smallest possible unit of duration type (1 nanosecond). time_duration::unit() --> time_duration(0,0,0,1) bool is_neg_infinity() const Returns true if time_duration is negative infinity time_duration td(neg_infin); td.is_neg_infinity(); // --> true bool is_pos_infinity() const Returns true if time_duration is positive infinity time_duration td(pos_infin); td.is_pos_infinity(); // --> true bool is_not_a_date_time() const Returns true if value is not a time time_duration td(not_a_date_time); td.is_not_a_date_time(); // --> true bool is_special() const Returns true if time_duration is any special_value time_duration td(pos_infin); time_duration td2(not_a_date_time); time_duration td3(2,5,10); td.is_special(); // --> true td2.is_special(); // --> true td3.is_special(); // --> false Conversion To String Syntax Description Example std::string to_simple_string(time_duration) To HH:MM:SS.fffffffff were fff is fractional seconds that are only included if non-zero. 10:00:01.123456789 std::string to_iso_string(time_duration) Convert to form HHMMSS,fffffffff. 100001,123456789 Operators Syntax Description Example operator<<, operator>> Streaming operators. Note: As of version 1.33, streaming operations have been greatly improved. See Date Time IO System for more details (including exceptions and error conditions). time_duration td(0,0,0); stringstream ss("14:23:11.345678"); ss >> td; std::cout << td; // "14:23:11.345678" operator==, operator!=, operator>, operator<, operator>=, operator<= A full complement of comparison operators dd1 == dd2, etc time_duration operator+(time_duration) Add durations. time_duration td1(hours(1)+minutes(2)); time_duration td2(seconds(10)); time_duration td3 = td1 + td2; time_duration operator-(time_duration) Subtract durations. time_duration td1(hours(1)+nanoseconds(2)); time_duration td2 = td1 - minutes(1); time_duration operator/(int) Divide the length of a duration by an integer value. Discards any remainder. hours(3)/2 == time_duration(1,30,0); nanosecond(3)/2 == nanosecond(1); time_duration operator*(int) Multiply the length of a duration by an integer value. hours(3)*2 == hours(6); Struct tm, time_t, and FILETIME Functions Function for converting a time_duration to a tm struct is provided. Syntax Description Example tm to_tm(time_duration) A function for converting a time_duration object to a tm struct. The fields: tm_year, tm_mon, tm_mday, tm_wday, tm_yday are set to zero. The tm_isdst field is set to -1. time_duration td(1,2,3); tm td_tm = to_tm(td); /* tm_year => 0 tm_mon => 0 tm_mday => 0 tm_wday => 0 tm_yday => 0 tm_hour => 1 tm_min => 2 tm_sec => 3 tm_isddst => -1 */