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; 30time_duration td(1,2,3,4); //01:02:03.000000004 when resolution is nano seconds 31time_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 41time_duration td = hours(1) + seconds(10); //01:00:10 42td = 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> 52count*(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> 58int number_of_tenths = 5; 59//create a resolution independent count -- divide by 10 since there are 60//10 tenths in a second. 61int count = number_of_tenths*(time_duration::ticks_per_second()/10); 62time_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 70or 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 99time_duration td2(1,2,3,123456789); 100time_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(), 112fractional_seconds(), total_nanoseconds(), 113total_microseconds(), total_milliseconds(), 114total_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" => 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"); 212time_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); 242time_duration neg_td(-1,2,3); 243td.hours(); // --> 1 244neg_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); 253time_duration neg_td(-1,2,3); 254td.minutes(); // --> 2 255neg_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); 264time_duration neg_td(-1,2,3); 265td.seconds(); // --> 3 266neg_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); 275td.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); 286td.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); 299td.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); 312td.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); 326td.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); 335td.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); 344td.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); 353td.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); 362td.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); 371td.abs(); // --> 01:00:00</screen></entry> 372 <entry><screen>time_duration td(+1,0,0); 373td.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; 390secs = 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 << 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); 408td.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); 425td.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); 434td.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); 443td.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); 452time_duration td2(not_a_date_time); 453time_duration td3(2,5,10); 454td.is_special(); // --> true 455td2.is_special(); // --> true 456td3.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<<, operator>></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); 522stringstream ss("14:23:11.345678"); 523ss >> td; 524std::cout << td; // "14:23:11.345678" 525 </screen> 526 </entry> 527 </row> 528 529 <row> 530 <entry valign="top" morerows="1"><screen>operator==, operator!=, 531operator>, operator<, 532operator>=, operator<=</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)); 546time_duration td2(seconds(10)); 547time_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)); 557time_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); 567nanosecond(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); 604tm 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_isdst => -1 */</screen> 614 </entry> 615 </row> 616 617 </tbody> 618 </tgroup> 619 </informaltable> 620 621</section> 622
