]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
92f5a8d4 | 41 | time_duration td = hours(1) + seconds(10); //01:00:10 |
7c673cae FG |
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" => 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> | |
11fdf7f2 | 237 | <entry valign="top" morerows="1"><screen>boost::int64_t hours()</screen></entry> |
7c673cae FG |
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> | |
11fdf7f2 | 248 | <entry valign="top" morerows="1"><screen>boost::int64_t minutes()</screen></entry> |
7c673cae FG |
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> | |
92f5a8d4 | 259 | <entry valign="top" morerows="1"><screen>boost::int64_t seconds() const</screen></entry> |
7c673cae FG |
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> | |
92f5a8d4 | 270 | <entry valign="top" morerows="1"><screen>boost::int64_t total_seconds() const</screen></entry> |
7c673cae FG |
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> | |
92f5a8d4 | 281 | <entry valign="top" morerows="1"><screen>boost::int64_t total_milliseconds() const</screen></entry> |
7c673cae FG |
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> | |
92f5a8d4 | 294 | <entry valign="top" morerows="1"><screen>boost::int64_t total_microseconds() const</screen></entry> |
7c673cae FG |
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> | |
92f5a8d4 | 307 | <entry valign="top" morerows="1"><screen>boost::int64_t total_nanoseconds() const</screen></entry> |
7c673cae FG |
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> | |
92f5a8d4 | 321 | <entry valign="top" morerows="1"><screen>boost::int64_t fractional_seconds() const</screen></entry> |
7c673cae FG |
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> | |
92f5a8d4 TL |
330 | <entry valign="top" morerows="1"><screen>bool is_negative() const</screen></entry> |
331 | <entry>True if and only if duration is negative.</entry> | |
7c673cae FG |
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> | |
92f5a8d4 TL |
339 | <entry valign="top" morerows="1"><screen>bool is_zero() const</screen></entry> |
340 | <entry>True if and only if duration is zero.</entry> | |
7c673cae FG |
341 | </row> |
342 | <row> | |
92f5a8d4 TL |
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); | |
7c673cae FG |
362 | td.invert_sign(); // --> 01:00:00</screen></entry> |
363 | </row> | |
364 | ||
365 | <row> | |
92f5a8d4 TL |
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> | |
7c673cae FG |
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> | |
92f5a8d4 TL |
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> | |
7c673cae FG |
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> | |
92f5a8d4 | 395 | <entry valign="top" morerows="1"><screen>boost::int64_t time_duration::ticks_per_second()</screen></entry> |
7c673cae FG |
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); | |
408 | td.ticks() // --> 1000</screen></entry> | |
409 | </row> | |
410 | ||
411 | <row> | |
92f5a8d4 | 412 | <entry valign="top" morerows="1"><screen>time_duration time_duration::unit()</screen></entry> |
7c673cae FG |
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<<, 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); | |
522 | stringstream ss("14:23:11.345678"); | |
523 | ss >> td; | |
524 | std::cout << 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<, | |
532 | operator>=, 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)); | |
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 | |
f67539c2 | 613 | tm_isdst => -1 */</screen> |
7c673cae FG |
614 | </entry> |
615 | </row> | |
616 | ||
617 | </tbody> | |
618 | </tgroup> | |
619 | </informaltable> | |
620 | ||
621 | </section> |