# Time Duration

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` where `fffffffff` 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` where the fractional seconds are only included if non-zero.

    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_isdst => -1 */