<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>posix_time::time_duration Documentation</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head>
<body>
<a href="../../../index.htm">
<img align="left" src="../../../c++boost.gif" alt="C++ Boost">
</a>
<h1>posix_time::time_duration</h1>
<p> <p>
<hr>
<p>
<p>
<a href="index.html">Overall Index</a> --
<a href="gregorian.html">Gregorian Index</a> --
<a href="posix_time.html">Posix Time Index</a>
<p>
<font class="bold">Time Duration Documentation</font>
<p>
<a href="class_time_duration.html#header">Header</a> --
<a href="class_time_duration.html#construct">Construction</a> --
<a href="class_time_duration.html#countbasedconstruct">Count Based Construction</a> --
<a href="class_time_duration.html#constructfromstring">Construct from String</a> --
<a href="class_time_duration.html#accessors">Accessors</a> --
<a href="class_time_duration.html#conversiontostring">Conversion To String</a> --
<a href="class_time_duration.html#operators">Operators</a>
<p>
<h2><a name="intro">Introduction</a></h2>
<p>
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 configureable at compile time. See
<a href="BuildInfo.html">Build-Compiler Information</a> for more
information.
<div class="fragment"><pre>
<font class="keyword">using namespace</font> boost::posix_time;
time_duration td(1,2,3,4); <font class="comment">//01:02:03.000000004 when resolution is nano seconds</font>
time_duration td(1,2,3,4); <font class="comment">//01:02:03.000004 when resolution is micro seconds</font>
</pre></div>
<p>
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.
<p>
<img align="middle" src="time_duration_inherit.png" alt="inherit">
<p>
As an example:
<div class="fragment"><pre>
<font class="keyword">using namespace</font> boost::posix_time;
time_duration td = hours(1) + seconds(10); <font class="comment">//01:00:01</font>
td = hours(1) + nanosec(5); <font class="comment">//01:00:00.000000005</font>
</pre></div>
<p>
Note that the existence of the higher resolution classes (eg: nanosec)
depends on the installation of the library. See
<a href="BuildInfo.html">Build-Compiler Information</a> for more
information.
<p>
<h2><a name="header">Header</a></h2>
<pre>
#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o
or
#include "boost/date_time/posix_time/posix_time/posix_time_types.hpp" //no i/o just types
</pre>
<p>
<h2><a name="construct">Construction</a></h2>
<p>
<table border=1 cellspacing=3 cellpadding=3>
<tr><td><b>Syntax</b></td><td><b>Description</b></td><td><b>Example</b></td></tr>
<tr><td>time_duration(hours,minutes,seconds,fractional_seconds)</td>
<td>Construct a duration from the counts</td>
<td>time_duration td(1,2,3,9); //1 hr 2 min 3 sec 9 nanoseconds</td></tr>
<tr><td>time_duration(special_values)</td>
<td>Construct a time duration with a special value such as not_a_date_time, pos_infin, or neg_infin.</td>
<td>time_duration td(not_a_date_time); //invalid value</td></tr>
</table>
<p>
<h2><a name="countbasedconstruct">Construction By Count</a></h2>
<table border=1 cellspacing=3 cellpadding=3>
<tr><td><b>Syntax</b></td><td><b>Description</b></td><td><b>Example</b></td></tr>
<tr><td class="nowrap">hours(long)</td>
<td>Number of hours</td>
<td class="nowrap">time_duration td = hours(3);</td></tr>
<tr><td>minutes(long)</td>
<td>Number of minutes</td>
<td>time_duration td = minutes(3);</td></tr>
<tr><td>seconds(long)</td>
<td>Number of seconds</td>
<td>time_duration td = seconds(3);</td></tr>
<tr><td>milliseconds(long)</td>
<td>Number of milliseconds.</td>
<td>time_duration td = milliseconds(3);</td></tr>
<tr><td>microseconds(long)</td>
<td>Number of microseconds.</td>
<td>time_duration td = microseconds(3);</td></tr>
<tr><td class="nowrap">nanoseconds(long)</td>
<td>Number of nanoseconds.</td>
<td class="nowrap">time_duration td = nanoseconds(3);</td></tr>
</table>
<p>
<h2><a name="constructfromstring">Construction From String</a></h2>
<p>
<table border=1 cellspacing=3 cellpadding=3>
<tr><td><b>Syntax</b></td><td><b>Description</b></td><td><b>Example</b></td></tr>
<tr><td>time_duration <font class="func">duration_from_string</font>(const std::string&)</td>
<td>From delimited string.</td>
<td>std::string ts("23:59:59.000");
<br>
time_duraton td(duration_from_string(ts))</td></tr>
</table>
<p>
<h2><a name="accessors">Accessors</a></h2>
<p>
<table border=1 cellspacing=3 cellpadding=3>
<tr><td><b>Syntax</b></td><td><b>Description</b></td><td><b>Example</b></td></tr>
<tr><td class="nowrap">long <font class="func">hours</font>() const</td>
<td>Get the number of normalized hours.</td>
<td>time_duration td(1,2,3); td.hours() --> 1</td></tr>
<tr><td class="nowrap">long <font class="func">minutes</font>() const</td>
<td>Get the number of minutes normalized (0..59).</td>
<td>time_duration td(1,2,3); td.minutes() --> 2</td></tr>
<tr><td class="nowrap">long <font class="func">seconds</font>() const</td>
<td>Get the normalized number of second (0..59).</td>
<td>time_duration td(1,2,3); td.seconds() --> 3</td></tr>
<tr><td class="nowrap">bool <font class="func">is_special</font>() const</td>
<td>Returns true if the value of the duration is a special value, otherwise false.</td>
<td>time_duration td(neg_infin); <br>
td.is_special() --> true</td></tr>
<tr><td class="nowrap">bool <font class="func">is_neg_infinity</font>() const</td>
<td>Returns true if the value of the duration is negative infinity, otherwise false.</td>
<td>time_duration td(neg_inifin); <br>
td.is_neg_infinity() --> true</td></tr>
<tr><td class="nowrap">bool <font class="func">is_pos_infinity</font>() const</td>
<td>Returns true if the value of the duration is positive infinity, otherwise false.</td>
<td>hours h(5); <br>
h.is_pos_infinity() --> false</td></tr>
<tr><td class="nowrap">long <font class="func">total_seconds</font>() const</td>
<td>Get the total number of seconds truncating
any fractional seconds.</td>
<td class="nowrap">time_duration td(1,2,3,10); <br>
td.total_seconds() --> (1*3600) + (2*60) + 3 == 3723</td></tr>
<tr><td class="nowrap">long <font class="func">total_microseconds</font>() const</td>
<td>Return the total number of microseconds in the duration
truncating any fractional lower resolution (eg: nano
second counts).
</td>
<td>seconds(1).total_microseconds() == 1000000</td></tr>
<tr><td class="nowrap">long <font class="func">total_milliseconds</font>() const</td>
<td>Return the total number of milliseconds in the duration
truncating any fractional lower resolution (eg: micro or nano
second counts).
</td>
<td>seconds(1).total_milliseconds() == 1000</td></tr>
<tr><td class="nowrap">long <font class="func">total_nanoseconds</font>() const</td>
<td>Return the total number of nanoseconds in the duration.
</td>
<td>seconds(1).total_nanoseconds() == 1000000000</td></tr>
<tr><td class="nowrap">long <font class="func">fractional_seconds</font>() const</td>
<td>Get the fractional seconds count. Note that the results of this
method vary based on the resolution of template instantiation
for the time duration (Normally either a nano-second or millisecond
count).
</td>
<td class="nowrap">time_duration td(1,2,3, 1000); <br>
td.fractional_seconds() --> 1000</td></tr>
<tr><td class="nowrap">bool <font class="func">is_negative</font>() const</td>
<td>True if duration is negative.</td>
<td>time_duration td(-1,0,0); td.is_negative() --> true</td></tr>
<tr><td>boost::int64_t <font class="func">ticks</font>()</td>
<td>Return the raw count of the duration type.</td>
<td class="nowrap">time_duration td(0,0,0, 1000); td.ticks() --> 1000</td></tr>
<tr><td class="nowrap">static boost::int64_t <font class="func">ticks_per_second</font>()</td>
<td>Return the number of ticks held internally to represent a second, which is
driven by the resolution settings. For nano second resolution the value
1000000000.
</td>
<td class="nowrap">time_duration::ticks_per_second() == 1000000000 //nano second resolution</td></tr>
<tr><td class="nowrap">static time_duration <font class="func">unit</font>()</td>
<td>Return smallest possible unit of duration type (1 nanosecond).</td>
<td class="nowrap">time_duration::unit() --> time_duration(0,0,0,1)</td></tr>
</table>
<p>
<p>
<h2><a name="conversiontostring">Conversion To String</a></h2>
<p>
<table border=1 cellspacing=3 cellpadding=3>
<tr><td><b>Syntax</b></td><td><b>Description</b></td><td><b>Example</b></td></tr>
<tr><td>std::string <font class="func">to_simple_string</font>(time_duration)</td>
<td>To HH:MM:SS.fffffffff were fff is fractional seconds that are only included if non-zero.</td>
<td>10:00:01.123456789</td></tr>
<tr><td>std::string <font class="func">to_iso_string</font>(time_duration)</td>
<td>Convert to form HHMMSS,fffffffff.</td>
<td>100001,123456789</td></tr>
</table>
<p>
<h2><a name="operators">Operators</a></h2>
<p>
<table border=1 cellspacing=3 cellpadding=3>
<tr><td><b>Syntax</b></td><td><b>Description</b></td><td><b>Example</b></td></tr>
<tr><td>operator==, operator!=,<br>
operator>, operator< <br>
operator>=, operator<=</td>
<td>A full complement of comparison operators</td>
<td>td1 == td2, etc</td></tr>
<tr><td class="nowrap">time_duration operator+(time_duration) const</td>
<td>Add durations.</td>
<td class="nowrap">time_duration td1(hours(1)+minutes(2));
<br>time_duration td2(seconds(10));
<br>time_duration td3 = td1 + td2;</td></tr>
<tr><td class="nowrap">time_duration operator-(time_duration) const</td>
<td>Subtract durations.</td>
<td class="nowrap">time_duration td1(hours(1)+nanosec(2)); <br>
time_duration td2 = td1 - minutes(1);</td></tr>
<tr><td>time_duration operator-() const</td>
<td>Invert sign.</td>
<td>time_duration td1(hours(1)); <br>
-td1; //equal -1 hour</td></tr>
<tr><td class="nowrap">time_duration operator/(int) const</td>
<td>Divide the length of a duration by an integer value. Discards
any remainder.</td>
<td class="nowrap">hours(3)/2 == time_duration(1,30,0);<br>
nanosec(3)/2 == nanosec(1)</td></tr>
<tr><td>time_duration operator*(int) const</td>
<td>Multiply the length of a duration by an integer value. </td>
<td>hours(3)*2 == hours(6);</td></tr>
</table>
<p>
<hr>
<address><small>
<!-- hhmts start -->
Last modified: Mon Jan 19 19:44:14 MST 2004
<!-- hhmts end -->
by <a href="mailto:jeff@crystalclearsoftware.com">Jeff Garland</a> © 2000-2003
</small></address>
</body>
</html>
