libs/date_time/xmldoc/time_duration.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3 "../../../tools/boostbook/dtd/boostbook.dtd">
   4
   5 <!-- Copyright (c) 2001-2005 CrystalClear Software, Inc.
   6      Subject to the Boost Software License, Version 1.0.
   7      (See accompanying file LICENSE_1_0.txt or  http://www.boost.org/LICENSE_1_0.txt)
   8 -->
   9
  10 <section id="date_time.posix_time.time_duration">
  11   <title>Time Duration</title>
  12
  13   <link linkend="time_duration_intro">Introduction</link> --
  14   <link linkend="time_duration_header">Header</link> --
  15   <link linkend="time_duration_constr">Construction</link> --
  16   <link linkend="time_duration_count_constr">Count Based Construction</link> --
  17   <link linkend="time_duration_from_string">Construct from String</link> --
  18   <link linkend="time_duration_accessors">Accessors</link> --
  19   <link linkend="time_duration_to_string">Conversion To String</link> --
  20   <link linkend="time_duration_operators">Operators</link> --
  21   <link linkend="time_duration_struct_tm">Struct tm Functions</link>
  22
  23   <anchor id="time_duration_intro" />
  24   <bridgehead renderas="sect3">Introduction</bridgehead>
  25   <para>
  26     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 <link linkend="date_time.buildinfo">Build-Compiler Information</link> for more information.
  27   </para>
  28   <para>
  29     <programlisting>using namespace boost::posix_time;
  30 time_duration td(1,2,3,4); //01:02:03.000000004 when resolution is nano seconds
  31 time_duration td(1,2,3,4); //01:02:03.000004 when resolution is micro seconds</programlisting>
  32   </para>
  33   <para>
  34     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.
  35   </para>
  36   <imagedata fileref="../../libs/date_time/doc/time_duration_inherit.png" />
  37   <para>
  38     As an example:
  39     <programlisting>using namespace boost::posix_time;
  40
  41 time_duration td = hours(1) + seconds(10); //01:00:10
  42 td = hours(1) + nanoseconds(5); //01:00:00.000000005</programlisting>
  43     Note that the existence of the higher resolution classes (eg: nanoseconds) depends on the installation of the library. See <link linkend="date_time.buildinfo">Build-Compiler Information</link> for more information.
  44   </para>
  45
  46   <para>
  47      Another way to handle this is to utilize the ticks_per_second() method of time_duration to
  48      write code that is portable no matter how the library is compiled.   The general equation
  49      for calculating a resolution independent count is as follows:
  50
  51     <programlisting>
  52 count*(time_duration_ticks_per_second / count_ticks_per_second)
  53     </programlisting>
  54
  55      For example, let's suppose we want to construct using a count that represents tenths
  56      of a second.  That is, each tick is 0.1 second.
  57     <programlisting>
  58 int number_of_tenths = 5;
  59 //create a resolution independent count -- divide by 10 since there are
  60 //10 tenths in a second.
  61 int count = number_of_tenths*(time_duration::ticks_per_second()/10);
  62 time_duration td(1,2,3,count); //01:02:03.5 //no matter the resolution settings
  63     </programlisting>
  64   </para>
  65
  66   <anchor id="time_duration_header" />
  67   <bridgehead renderas="sect3">Header</bridgehead>
  68   <para>
  69     <programlisting>#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o
  70 or
  71 #include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types</programlisting>
  72   </para>
  73
  74   <anchor id="time_duration_constr" />
  75   <bridgehead renderas="sect3">Construction</bridgehead>
  76   <para>
  77     <informaltable frame="all">
  78       <tgroup cols="2">
  79         <thead>
  80           <row>
  81             <entry valign="top" morerows="1">Syntax</entry>
  82             <entry>Description</entry>
  83           </row>
  84           <row>
  85             <entry>Example</entry>
  86           </row>
  87         </thead>
  88         <tbody>
  89           <row>
  90             <entry valign="top" morerows="1"><screen>time_duration(hours,
  91               minutes,
  92               seconds,
  93               fractional_seconds)</screen></entry>
  94           <entry>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 <link linkend="compile_options">Build-Compiler Information</link>). 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.</entry>
  95           </row>
  96           <row>
  97             <entry><screen>time_duration td(1,2,3,9);
  98 //1 hr 2 min 3 sec 9 nanoseconds
  99 time_duration td2(1,2,3,123456789);
 100 time_duration td3(1,2,3,1000);
 101 // with microsecond resolution (6 digits)
 102 // td2 => "01:04:06.456789"
 103 // td3 => "01:02:03.001000"
 104 // with nanosecond resolution (9 digits)
 105 // td2 => "01:02:03.123456789"
 106 // td3 => "01:02:03.000001000"</screen></entry>
 107           </row>
 108
 109           <row>
 110             <entry valign="top"><screen>time_duration(special_value sv)</screen></entry>
 111             <entry>Special values constructor. <emphasis role="strong">Important note</emphasis>: When a time_duration is a special value, either by construction or other means, the following accessor functions will give unpredictable results: <screen>hours(), minutes(), seconds(), ticks(),
 112 fractional_seconds(), total_nanoseconds(),
 113 total_microseconds(), total_milliseconds(),
 114 total_seconds()</screen>The remaining accessor functions will work as expected.</entry>
 115           </row>
 116
 117         </tbody>
 118       </tgroup>
 119     </informaltable>
 120   </para>
 121
 122
 123   <anchor id="time_duration_count_constr" />
 124   <bridgehead renderas="sect3">Count Based Construction</bridgehead>
 125   <para>
 126     <informaltable frame="all">
 127       <tgroup cols="2">
 128         <thead>
 129           <row>
 130             <entry valign="top" morerows="1">Syntax</entry>
 131             <entry>Description</entry>
 132           </row>
 133           <row>
 134             <entry>Example</entry>
 135           </row>
 136         </thead>
 137         <tbody>
 138           <row>
 139             <entry valign="top" morerows="1"><screen>hours(long)</screen></entry>
 140             <entry>Number of hours</entry>
 141           </row>
 142           <row>
 143             <entry><screen>time_duration td = hours(3);</screen></entry>
 144           </row>
 145
 146           <row>
 147             <entry valign="top" morerows="1"><screen>minutes(long)</screen></entry>
 148             <entry>Number of minutes</entry>
 149           </row>
 150           <row>
 151             <entry><screen>time_duration td = minutes(3);</screen></entry>
 152           </row>
 153
 154           <row>
 155             <entry valign="top" morerows="1"><screen>seconds(long)</screen></entry>
 156             <entry> Number of seconds</entry>
 157           </row>
 158           <row>
 159             <entry><screen>time_duration td = seconds(3);</screen></entry>
 160           </row>
 161
 162           <row>
 163             <entry valign="top" morerows="1"><screen>milliseconds(long)</screen></entry>
 164             <entry>Number of milliseconds.</entry>
 165           </row>
 166           <row>
 167             <entry><screen>time_duration td = milliseconds(3);</screen></entry>
 168           </row>
 169
 170           <row>
 171             <entry valign="top" morerows="1"><screen>microseconds(long)</screen></entry>
 172             <entry>Number of microseconds.</entry>
 173           </row>
 174           <row>
 175             <entry><screen>time_duration td = microseconds(3);</screen></entry>
 176           </row>
 177
 178           <row>
 179             <entry valign="top" morerows="1"><screen>nanoseconds(long)</screen></entry>
 180             <entry>Number of nanoseconds.</entry>
 181           </row>
 182           <row>
 183             <entry><screen>time_duration td = nanoseconds(3);</screen></entry>
 184           </row>
 185         </tbody>
 186       </tgroup>
 187     </informaltable>
 188   </para>
 189
 190
 191   <anchor id="time_duration_from_string" />
 192   <bridgehead renderas="sect3">Construct from String</bridgehead>
 193   <para>
 194     <informaltable frame="all">
 195       <tgroup cols="2">
 196         <thead>
 197           <row>
 198             <entry valign="top" morerows="1">Syntax</entry>
 199             <entry>Description</entry>
 200           </row>
 201           <row>
 202             <entry>Example</entry>
 203           </row>
 204         </thead>
 205         <tbody>
 206           <row>
 207             <entry valign="top" morerows="1"><screen>time_duration duration_from_string(std::string)</screen></entry>
 208             <entry>From delimited string. NOTE: Excess digits in fractional seconds will be dropped. Ex: "1:02:03.123456999" =&gt; 1:02:03.123456. This behavior is affected by the precision the library is compiled with (see <link linkend="date_time.buildinfo">Build-Compiler Information</link>.</entry>
 209           </row>
 210           <row>
 211             <entry><screen>std::string ts("23:59:59.000");
 212 time_duration td(duration_from_string(ts));</screen>
 213             </entry>
 214           </row>
 215         </tbody>
 216       </tgroup>
 217     </informaltable>
 218   </para>
 219
 220
 221   <anchor id="time_duration_accessors" />
 222   <bridgehead renderas="sect3">Accessors</bridgehead>
 223   <para>
 224     <informaltable frame="all">
 225       <tgroup cols="2">
 226         <thead>
 227           <row>
 228             <entry valign="top" morerows="1">Syntax</entry>
 229             <entry>Description</entry>
 230           </row>
 231           <row>
 232             <entry>Example</entry>
 233           </row>
 234         </thead>
 235         <tbody>
 236           <row>
 237             <entry valign="top" morerows="1"><screen>boost::int64_t hours()</screen></entry>
 238             <entry>Get the number of normalized hours (will give unpredictable results if calling <code>time_duration</code> is a <code>special_value</code>).</entry>
 239           </row>
 240           <row>
 241             <entry><screen>time_duration td(1,2,3);
 242 time_duration neg_td(-1,2,3);
 243 td.hours(); // --> 1
 244 neg_td.hours(); // --> -1</screen></entry>
 245           </row>
 246
 247           <row>
 248             <entry valign="top" morerows="1"><screen>boost::int64_t minutes()</screen></entry>
 249             <entry>Get the number of minutes normalized +/-(0..59) (will give unpredictable results if calling <code>time_duration</code> is a <code>special_value</code>).</entry>
 250           </row>
 251           <row>
 252             <entry><screen>time_duration td(1,2,3);
 253 time_duration neg_td(-1,2,3);
 254 td.minutes(); // --> 2
 255 neg_td.minutes(); // --> -2</screen></entry>
 256         </row>
 257
 258           <row>
 259             <entry valign="top" morerows="1"><screen>boost::int64_t seconds() const</screen></entry>
 260             <entry>Get the normalized number of second +/-(0..59) (will give unpredictable results if calling <code>time_duration</code> is a <code>special_value</code>).</entry>
 261           </row>
 262           <row>
 263             <entry><screen>time_duration td(1,2,3);
 264 time_duration neg_td(-1,2,3);
 265 td.seconds(); // --> 3
 266 neg_td.seconds(); // --> -3</screen></entry>
 267         </row>
 268
 269           <row>
 270             <entry valign="top" morerows="1"><screen>boost::int64_t total_seconds() const</screen></entry>
 271             <entry>Get the total number of seconds truncating any fractional seconds (will give unpredictable results if calling <code>time_duration</code> is a <code>special_value</code>).</entry>
 272           </row>
 273           <row>
 274             <entry><screen>time_duration td(1,2,3,10);
 275 td.total_seconds();
 276 // --> (1*3600) + (2*60) + 3 == 3723</screen>
 277             </entry>
 278           </row>
 279
 280           <row>
 281             <entry valign="top" morerows="1"><screen>boost::int64_t total_milliseconds() const</screen></entry>
 282             <entry>Get the total number of milliseconds truncating any remaining digits (will give unpredictable results if calling <code>time_duration</code> is a <code>special_value</code>).</entry>
 283           </row>
 284           <row>
 285             <entry><screen>time_duration td(1,2,3,123456789);
 286 td.total_milliseconds();
 287 // HMS --> (1*3600) + (2*60) + 3 == 3723 seconds
 288 // milliseconds is 3 decimal places
 289 // (3723 * 1000) + 123 == 3723123</screen>
 290             </entry>
 291           </row>
 292
 293           <row>
 294             <entry valign="top" morerows="1"><screen>boost::int64_t total_microseconds() const</screen></entry>
 295             <entry>Get the total number of microseconds truncating any remaining digits (will give unpredictable results if calling <code>time_duration</code> is a <code>special_value</code>).</entry>
 296           </row>
 297           <row>
 298             <entry><screen>time_duration td(1,2,3,123456789);
 299 td.total_microseconds();
 300 // HMS --> (1*3600) + (2*60) + 3 == 3723 seconds
 301 // microseconds is 6 decimal places
 302 // (3723 * 1000000) + 123456 == 3723123456</screen>
 303             </entry>
 304           </row>
 305
 306           <row>
 307             <entry valign="top" morerows="1"><screen>boost::int64_t total_nanoseconds() const</screen></entry>
 308             <entry>Get the total number of nanoseconds truncating any remaining digits (will give unpredictable results if calling <code>time_duration</code> is a <code>special_value</code>).</entry>
 309           </row>
 310           <row>
 311             <entry><screen>time_duration td(1,2,3,123456789);
 312 td.total_nanoseconds();
 313 // HMS --> (1*3600) + (2*60) + 3 == 3723 seconds
 314 // nanoseconds is 9 decimal places
 315 // (3723 * 1000000000) + 123456789
 316 //                              == 3723123456789</screen>
 317             </entry>
 318           </row>
 319
 320           <row>
 321             <entry valign="top" morerows="1"><screen>boost::int64_t fractional_seconds() const</screen></entry>
 322             <entry>Get the number of fractional seconds (will give unpredictable results if calling <code>time_duration</code> is a <code>special_value</code>).</entry>
 323           </row>
 324           <row>
 325             <entry><screen>time_duration td(1,2,3, 1000);
 326 td.fractional_seconds(); // --> 1000</screen></entry>
 327           </row>
 328
 329           <row>
 330             <entry valign="top" morerows="1"><screen>bool is_negative() const</screen></entry>
 331             <entry>True if and only if duration is negative.</entry>
 332           </row>
 333           <row>
 334             <entry><screen>time_duration td(-1,0,0);
 335 td.is_negative(); // --> true</screen></entry>
 336           </row>
 337
 338           <row>
 339             <entry valign="top" morerows="1"><screen>bool is_zero() const</screen></entry>
 340             <entry>True if and only if duration is zero.</entry>
 341           </row>
 342           <row>
 343             <entry><screen>time_duration td(0,0,0);
 344 td.is_zero(); // --> true</screen></entry>
 345           </row>
 346
 347           <row>
 348             <entry valign="top" morerows="1"><screen>bool is_positive() const</screen></entry>
 349             <entry>True if and only if duration is positive.</entry>
 350           </row>
 351           <row>
 352             <entry><screen>time_duration td(1,0,0);
 353 td.is_positive(); // --> true</screen></entry>
 354           </row>
 355
 356           <row>
 357             <entry valign="top" morerows="1"><screen>time_duration invert_sign() const</screen></entry>
 358             <entry>Generate a new duration with the sign inverted.</entry>
 359           </row>
 360           <row>
 361             <entry><screen>time_duration td(-1,0,0);
 362 td.invert_sign(); // --> 01:00:00</screen></entry>
 363           </row>
 364
 365           <row>
 366             <entry valign="top" morerows="1"><screen>time_duration abs() const</screen></entry>
 367             <entry>Generate a new duration with the absolute value of the time duration.</entry>
 368           </row>
 369           <row>
 370             <entry><screen>time_duration td(-1,0,0);
 371 td.abs(); // --> 01:00:00</screen></entry>
 372             <entry><screen>time_duration td(+1,0,0);
 373 td.abs(); // --> 01:00:00</screen></entry>
 374           </row>
 375
 376           <row>
 377             <entry valign="top" morerows="1"><screen>date_time::time_resolutions time_duration::resolution()</screen></entry>
 378             <entry>Describes the resolution capability of the time_duration class. time_resolutions is an enum of resolution possibilities ranging from seconds to nanoseconds.</entry>
 379           </row>
 380           <row>
 381             <entry><screen>time_duration::resolution() --> nano</screen></entry>
 382           </row>
 383
 384           <row>
 385             <entry valign="top" morerows="1"><screen>unsigned short time_duration::num_fractional_digits()</screen></entry>
 386             <entry>Returns the number of fractional digits the time resolution has.</entry>
 387           </row>
 388           <row>
 389             <entry><screen>unsigned short secs;
 390 secs = time_duration::num_fractional_digits();
 391 // 9 for nano, 6 for micro, etc.</screen></entry>
 392           </row>
 393
 394           <row>
 395             <entry valign="top" morerows="1"><screen>boost::int64_t time_duration::ticks_per_second()</screen></entry>
 396             <entry>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).</entry>
 397           </row>
 398           <row>
 399             <entry><screen>std::cout &lt;&lt; time_duration::ticks_per_second();</screen></entry>
 400           </row>
 401
 402           <row>
 403             <entry valign="top" morerows="1"><screen>boost::int64_t ticks()</screen></entry>
 404             <entry>Return the raw count of the duration type (will give unpredictable results if calling <code>time_duration</code> is a <code>special_value</code>).</entry>
 405           </row>
 406           <row>
 407             <entry><screen>time_duration td(0,0,0, 1000);
 408 td.ticks() // --> 1000</screen></entry>
 409           </row>
 410
 411           <row>
 412             <entry valign="top" morerows="1"><screen>time_duration time_duration::unit()</screen></entry>
 413             <entry>Return smallest possible unit of duration type (1 nanosecond).</entry>
 414           </row>
 415           <row>
 416             <entry><screen>time_duration::unit() --> time_duration(0,0,0,1)</screen></entry>
 417           </row>
 418
 419           <row>
 420             <entry valign="top" morerows="1"><screen>bool is_neg_infinity() const</screen></entry>
 421             <entry>Returns true if time_duration is negative infinity</entry>
 422           </row>
 423           <row>
 424             <entry><screen>time_duration td(neg_infin);
 425 td.is_neg_infinity(); // --> true</screen></entry>
 426           </row>
 427
 428           <row>
 429             <entry valign="top" morerows="1"><screen>bool is_pos_infinity() const</screen></entry>
 430             <entry>Returns true if time_duration is positive infinity</entry>
 431           </row>
 432           <row>
 433             <entry><screen>time_duration td(pos_infin);
 434 td.is_pos_infinity(); // --> true</screen></entry>
 435           </row>
 436
 437           <row>
 438             <entry valign="top" morerows="1"><screen>bool is_not_a_date_time() const</screen></entry>
 439             <entry>Returns true if value is not a time</entry>
 440           </row>
 441           <row>
 442             <entry><screen>time_duration td(not_a_date_time);
 443 td.is_not_a_date_time(); // --> true</screen></entry>
 444           </row>
 445
 446           <row>
 447             <entry valign="top" morerows="1"><screen>bool is_special() const</screen></entry>
 448             <entry>Returns true if time_duration is any <code>special_value</code></entry>
 449           </row>
 450           <row>
 451             <entry><screen>time_duration td(pos_infin);
 452 time_duration td2(not_a_date_time);
 453 time_duration td3(2,5,10);
 454 td.is_special(); // --> true
 455 td2.is_special(); // --> true
 456 td3.is_special(); // --> false</screen></entry>
 457           </row>
 458
 459         </tbody>
 460       </tgroup>
 461     </informaltable>
 462   </para>
 463
 464
 465   <anchor id="time_duration_to_string" />
 466   <bridgehead renderas="sect3">Conversion To String</bridgehead>
 467   <para>
 468     <informaltable frame="all">
 469       <tgroup cols="2">
 470         <thead>
 471           <row>
 472             <entry valign="top" morerows="1">Syntax</entry>
 473             <entry>Description</entry>
 474           </row>
 475           <row>
 476             <entry>Example</entry>
 477           </row>
 478         </thead>
 479         <tbody>
 480           <row>
 481             <entry valign="top" morerows="1"><screen>std::string to_simple_string(time_duration)</screen></entry>
 482             <entry>To <code>HH:MM:SS.fffffffff</code> were <code>fff</code> is fractional seconds that are only included if non-zero.</entry>
 483           </row>
 484           <row>
 485             <entry><screen>10:00:01.123456789</screen></entry>
 486           </row>
 487
 488           <row>
 489             <entry valign="top" morerows="1"><screen>std::string to_iso_string(time_duration)</screen></entry>
 490             <entry>Convert to form <code>HHMMSS,fffffffff</code>.</entry>
 491           </row>
 492           <row>
 493             <entry><screen>100001,123456789</screen></entry>
 494           </row>
 495         </tbody>
 496       </tgroup>
 497     </informaltable>
 498   </para>
 499
 500
 501   <anchor id="time_duration_operators" />
 502   <bridgehead renderas="sect3">Operators</bridgehead>
 503   <para>
 504     <informaltable frame="all">
 505       <tgroup cols="2">
 506         <thead>
 507           <row>
 508             <entry valign="top" morerows="1">Syntax</entry>
 509             <entry>Description</entry>
 510           </row>
 511           <row>
 512             <entry>Example</entry>
 513           </row>
 514         </thead>
 515         <tbody>
 516           <row>
 517             <entry valign="top" morerows="1"><screen>operator&lt;&lt;, operator&gt;&gt;</screen></entry>
 518             <entry>Streaming operators. <emphasis role="strong">Note:</emphasis> As of version 1.33, streaming operations have been greatly improved. See <link linkend="date_time.date_time_io">Date Time IO System</link> for more details (including exceptions and error conditions).</entry>
 519           </row>
 520           <row>
 521             <entry><screen>time_duration td(0,0,0);
 522 stringstream ss("14:23:11.345678");
 523 ss &gt;&gt; td;
 524 std::cout &lt;&lt; td; // "14:23:11.345678"
 525   </screen>
 526             </entry>
 527           </row>
 528
 529           <row>
 530             <entry valign="top" morerows="1"><screen>operator==, operator!=,
 531 operator>, operator&lt;,
 532 operator>=, operator&lt;=</screen>
 533             </entry>
 534             <entry>A full complement of comparison operators</entry>
 535           </row>
 536           <row>
 537             <entry><screen>dd1 == dd2, etc</screen></entry>
 538           </row>
 539
 540           <row>
 541             <entry valign="top" morerows="1"><screen>time_duration operator+(time_duration)</screen></entry>
 542             <entry>Add durations.</entry>
 543           </row>
 544           <row>
 545             <entry><screen>time_duration td1(hours(1)+minutes(2));
 546 time_duration td2(seconds(10));
 547 time_duration td3 = td1 + td2;</screen>
 548             </entry>
 549           </row>
 550
 551           <row>
 552             <entry valign="top" morerows="1"><screen>time_duration operator-(time_duration)</screen></entry>
 553             <entry>Subtract durations.</entry>
 554           </row>
 555           <row>
 556             <entry><screen>time_duration td1(hours(1)+nanoseconds(2));
 557 time_duration td2 = td1 - minutes(1);</screen>
 558             </entry>
 559           </row>
 560
 561           <row>
 562             <entry valign="top" morerows="1"><screen>time_duration operator/(int)</screen></entry>
 563             <entry>Divide the length of a duration by an integer value. Discards any remainder.</entry>
 564           </row>
 565           <row>
 566             <entry><screen>hours(3)/2 == time_duration(1,30,0);
 567 nanosecond(3)/2 == nanosecond(1);</screen>
 568             </entry>
 569           </row>
 570
 571           <row>
 572             <entry valign="top" morerows="1"><screen>time_duration operator*(int)</screen></entry>
 573             <entry>Multiply the length of a duration by an integer value.</entry>
 574           </row>
 575           <row>
 576             <entry><screen>hours(3)*2 == hours(6);</screen></entry>
 577           </row>
 578         </tbody>
 579       </tgroup>
 580     </informaltable>
 581   </para>
 582
 583   <anchor id="time_duration_struct_tm" />
 584   <bridgehead renderas="sect3">Struct tm, time_t, and FILETIME Functions</bridgehead>
 585   <para>Function for converting a time_duration to a <code>tm</code> struct is provided.</para>
 586   <informaltable frame="all">
 587     <tgroup cols="2">
 588       <thead>
 589         <row>
 590           <entry valign="top" morerows="1">Syntax</entry>
 591           <entry>Description</entry>
 592         </row>
 593         <row>
 594           <entry>Example</entry>
 595         </row>
 596       </thead>
 597       <tbody>
 598         <row>
 599           <entry valign="top" morerows="1"><screen>tm to_tm(time_duration)</screen></entry>
 600           <entry>A function for converting a <code>time_duration</code> object to a <code>tm</code> struct. The fields: <code>tm_year</code>, <code>tm_mon</code>, <code>tm_mday</code>, <code>tm_wday</code>, <code>tm_yday</code> are set to zero. The <code>tm_isdst</code> field is set to -1.</entry>
 601         </row>
 602         <row>
 603           <entry><screen>time_duration td(1,2,3);
 604 tm td_tm = to_tm(td);
 605 /* tm_year => 0
 606    tm_mon  => 0
 607    tm_mday => 0
 608    tm_wday => 0
 609    tm_yday => 0
 610    tm_hour => 1
 611    tm_min  => 2
 612    tm_sec  => 3
 613    tm_isddst => -1 */</screen>
 614           </entry>
 615         </row>
 616
 617       </tbody>
 618     </tgroup>
 619   </informaltable>
 620
 621 </section>