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">
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)
10 <section id=
"date_time.posix_time.time_duration">
11 <title>Time Duration
</title>
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>
23 <anchor id=
"time_duration_intro" />
24 <bridgehead renderas=
"sect3">Introduction
</bridgehead>
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.
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>
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.
36 <imagedata fileref=
"../../libs/date_time/doc/time_duration_inherit.png" />
39 <programlisting>using namespace boost::posix_time;
41 time_duration td = hours(
1) + seconds(
10); //
01:
00:
01
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.
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:
52 count*(time_duration_ticks_per_second / count_ticks_per_second)
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.
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
66 <anchor id=
"time_duration_header" />
67 <bridgehead renderas=
"sect3">Header
</bridgehead>
69 <programlisting>#include
"boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o
71 #include
"boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types
</programlisting>
74 <anchor id=
"time_duration_constr" />
75 <bridgehead renderas=
"sect3">Construction
</bridgehead>
77 <informaltable frame=
"all">
81 <entry valign=
"top" morerows=
"1">Syntax
</entry>
82 <entry>Description
</entry>
85 <entry>Example
</entry>
90 <entry valign=
"top" morerows=
"1"><screen>time_duration(hours,
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>
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>
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>
123 <anchor id=
"time_duration_count_constr" />
124 <bridgehead renderas=
"sect3">Count Based Construction
</bridgehead>
126 <informaltable frame=
"all">
130 <entry valign=
"top" morerows=
"1">Syntax
</entry>
131 <entry>Description
</entry>
134 <entry>Example
</entry>
139 <entry valign=
"top" morerows=
"1"><screen>hours(long)
</screen></entry>
140 <entry>Number of hours
</entry>
143 <entry><screen>time_duration td = hours(
3);
</screen></entry>
147 <entry valign=
"top" morerows=
"1"><screen>minutes(long)
</screen></entry>
148 <entry>Number of minutes
</entry>
151 <entry><screen>time_duration td = minutes(
3);
</screen></entry>
155 <entry valign=
"top" morerows=
"1"><screen>seconds(long)
</screen></entry>
156 <entry> Number of seconds
</entry>
159 <entry><screen>time_duration td = seconds(
3);
</screen></entry>
163 <entry valign=
"top" morerows=
"1"><screen>milliseconds(long)
</screen></entry>
164 <entry>Number of milliseconds.
</entry>
167 <entry><screen>time_duration td = milliseconds(
3);
</screen></entry>
171 <entry valign=
"top" morerows=
"1"><screen>microseconds(long)
</screen></entry>
172 <entry>Number of microseconds.
</entry>
175 <entry><screen>time_duration td = microseconds(
3);
</screen></entry>
179 <entry valign=
"top" morerows=
"1"><screen>nanoseconds(long)
</screen></entry>
180 <entry>Number of nanoseconds.
</entry>
183 <entry><screen>time_duration td = nanoseconds(
3);
</screen></entry>
191 <anchor id=
"time_duration_from_string" />
192 <bridgehead renderas=
"sect3">Construct from String
</bridgehead>
194 <informaltable frame=
"all">
198 <entry valign=
"top" morerows=
"1">Syntax
</entry>
199 <entry>Description
</entry>
202 <entry>Example
</entry>
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>
211 <entry><screen>std::string ts(
"23:59:59.000");
212 time_duration td(duration_from_string(ts));
</screen>
221 <anchor id=
"time_duration_accessors" />
222 <bridgehead renderas=
"sect3">Accessors
</bridgehead>
224 <informaltable frame=
"all">
228 <entry valign=
"top" morerows=
"1">Syntax
</entry>
229 <entry>Description
</entry>
232 <entry>Example
</entry>
237 <entry valign=
"top" morerows=
"1"><screen>long 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>
241 <entry><screen>time_duration td(
1,
2,
3);
242 time_duration neg_td(-
1,
2,
3);
244 neg_td.hours(); // --> -
1</screen></entry>
248 <entry valign=
"top" morerows=
"1"><screen>long 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>
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>
259 <entry valign=
"top" morerows=
"1"><screen>long seconds()
</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>
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>
270 <entry valign=
"top" morerows=
"1"><screen>long total_seconds()
</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>
274 <entry><screen>time_duration td(
1,
2,
3,
10);
276 // --> (
1*
3600) + (
2*
60) +
3 ==
3723</screen>
281 <entry valign=
"top" morerows=
"1"><screen>long total_milliseconds()
</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>
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>
294 <entry valign=
"top" morerows=
"1"><screen>long total_microseconds()
</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>
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>
307 <entry valign=
"top" morerows=
"1"><screen>long total_nanoseconds()
</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>
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>
321 <entry valign=
"top" morerows=
"1"><screen>long fractional_seconds()
</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>
325 <entry><screen>time_duration td(
1,
2,
3,
1000);
326 td.fractional_seconds(); // -->
1000</screen></entry>
330 <entry valign=
"top" morerows=
"1"><screen>bool is_negative()
</screen></entry>
331 <entry>True if duration is negative.
</entry>
334 <entry><screen>time_duration td(-
1,
0,
0);
335 td.is_negative(); // --> true
</screen></entry>
339 <entry valign=
"top" morerows=
"1"><screen>time_duration invert_sign()
</screen></entry>
340 <entry>Generate a new duration with the sign inverted/
</entry>
343 <entry><screen>time_duration td(-
1,
0,
0);
344 td.invert_sign(); // -->
01:
00:
00</screen></entry>
348 <entry valign=
"top" morerows=
"1"><screen>date_time::time_resolutions resolution()
</screen></entry>
349 <entry>Describes the resolution capability of the time_duration class. time_resolutions is an enum of resolution possibilities ranging from seconds to nanoseconds.
</entry>
352 <entry><screen>time_duration::resolution() --> nano
</screen></entry>
356 <entry valign=
"top" morerows=
"1"><screen>time_duration::num_fractional_digits()
</screen></entry>
357 <entry>Returns an unsigned short holding the number of fractional digits the time resolution has.
</entry>
360 <entry><screen>unsigned short secs;
361 secs = time_duration::num_fractional_digits();
362 //
9 for nano,
6 for micro, etc.
</screen></entry>
366 <entry valign=
"top" morerows=
"1"><screen>time_duration::ticks_per_second()
</screen></entry>
367 <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>
370 <entry><screen>std::cout
<< time_duration::ticks_per_second();
</screen></entry>
374 <entry valign=
"top" morerows=
"1"><screen>boost::int64_t ticks()
</screen></entry>
375 <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>
378 <entry><screen>time_duration td(
0,
0,
0,
1000);
379 td.ticks() // -->
1000</screen></entry>
383 <entry valign=
"top" morerows=
"1"><screen>time_duration unit()
</screen></entry>
384 <entry>Return smallest possible unit of duration type (
1 nanosecond).
</entry>
387 <entry><screen>time_duration::unit() --> time_duration(
0,
0,
0,
1)
</screen></entry>
391 <entry valign=
"top" morerows=
"1"><screen>bool is_neg_infinity() const
</screen></entry>
392 <entry>Returns true if time_duration is negative infinity
</entry>
395 <entry><screen>time_duration td(neg_infin);
396 td.is_neg_infinity(); // --> true
</screen></entry>
400 <entry valign=
"top" morerows=
"1"><screen>bool is_pos_infinity() const
</screen></entry>
401 <entry>Returns true if time_duration is positive infinity
</entry>
404 <entry><screen>time_duration td(pos_infin);
405 td.is_pos_infinity(); // --> true
</screen></entry>
409 <entry valign=
"top" morerows=
"1"><screen>bool is_not_a_date_time() const
</screen></entry>
410 <entry>Returns true if value is not a time
</entry>
413 <entry><screen>time_duration td(not_a_date_time);
414 td.is_not_a_date_time(); // --> true
</screen></entry>
418 <entry valign=
"top" morerows=
"1"><screen>bool is_special() const
</screen></entry>
419 <entry>Returns true if time_duration is any
<code>special_value
</code></entry>
422 <entry><screen>time_duration td(pos_infin);
423 time_duration td2(not_a_date_time);
424 time_duration td3(
2,
5,
10);
425 td.is_special(); // --> true
426 td2.is_special(); // --> true
427 td3.is_special(); // --> false
</screen></entry>
436 <anchor id=
"time_duration_to_string" />
437 <bridgehead renderas=
"sect3">Conversion To String
</bridgehead>
439 <informaltable frame=
"all">
443 <entry valign=
"top" morerows=
"1">Syntax
</entry>
444 <entry>Description
</entry>
447 <entry>Example
</entry>
452 <entry valign=
"top" morerows=
"1"><screen>std::string to_simple_string(time_duration)
</screen></entry>
453 <entry>To
<code>HH:MM:SS.fffffffff
</code> were
<code>fff
</code> is fractional seconds that are only included if non-zero.
</entry>
456 <entry><screen>10:
00:
01.123456789</screen></entry>
460 <entry valign=
"top" morerows=
"1"><screen>std::string to_iso_string(time_duration)
</screen></entry>
461 <entry>Convert to form
<code>HHMMSS,fffffffff
</code>.
</entry>
464 <entry><screen>100001,
123456789</screen></entry>
472 <anchor id=
"time_duration_operators" />
473 <bridgehead renderas=
"sect3">Operators
</bridgehead>
475 <informaltable frame=
"all">
479 <entry valign=
"top" morerows=
"1">Syntax
</entry>
480 <entry>Description
</entry>
483 <entry>Example
</entry>
488 <entry valign=
"top" morerows=
"1"><screen>operator
<<, operator
>></screen></entry>
489 <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>
492 <entry><screen>time_duration td(
0,
0,
0);
493 stringstream ss(
"14:23:11.345678");
495 std::cout
<< td; //
"14:23:11.345678"
501 <entry valign=
"top" morerows=
"1"><screen>operator==, operator!=,
502 operator
>, operator
<,
503 operator
>=, operator
<=
</screen>
505 <entry>A full complement of comparison operators
</entry>
508 <entry><screen>dd1 == dd2, etc
</screen></entry>
512 <entry valign=
"top" morerows=
"1"><screen>time_duration operator+(time_duration)
</screen></entry>
513 <entry>Add durations.
</entry>
516 <entry><screen>time_duration td1(hours(
1)+minutes(
2));
517 time_duration td2(seconds(
10));
518 time_duration td3 = td1 + td2;
</screen>
523 <entry valign=
"top" morerows=
"1"><screen>time_duration operator-(time_duration)
</screen></entry>
524 <entry>Subtract durations.
</entry>
527 <entry><screen>time_duration td1(hours(
1)+nanoseconds(
2));
528 time_duration td2 = td1 - minutes(
1);
</screen>
533 <entry valign=
"top" morerows=
"1"><screen>time_duration operator/(int)
</screen></entry>
534 <entry>Divide the length of a duration by an integer value. Discards any remainder.
</entry>
537 <entry><screen>hours(
3)/
2 == time_duration(
1,
30,
0);
538 nanosecond(
3)/
2 == nanosecond(
1);
</screen>
543 <entry valign=
"top" morerows=
"1"><screen>time_duration operator*(int)
</screen></entry>
544 <entry>Multiply the length of a duration by an integer value.
</entry>
547 <entry><screen>hours(
3)*
2 == hours(
6);
</screen></entry>
554 <anchor id=
"time_duration_struct_tm" />
555 <bridgehead renderas=
"sect3">Struct tm, time_t, and FILETIME Functions
</bridgehead>
556 <para>Function for converting a time_duration to a
<code>tm
</code> struct is provided.
</para>
557 <informaltable frame=
"all">
561 <entry valign=
"top" morerows=
"1">Syntax
</entry>
562 <entry>Description
</entry>
565 <entry>Example
</entry>
570 <entry valign=
"top" morerows=
"1"><screen>tm to_tm(time_duration)
</screen></entry>
571 <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>
574 <entry><screen>time_duration td(
1,
2,
3);
575 tm td_tm = to_tm(td);
584 tm_isddst =
> -
1 */
</screen>