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.ptime_class"> 11 <title>Ptime</title> 12 13 <link linkend="ptime_intro">Introduction</link> -- 14 <link linkend="ptime_header">Header</link> -- 15 <link linkend="ptime_constr">Construction</link> -- 16 <link linkend="ptime_from_string">Construct from String</link> -- 17 <link linkend="ptime_from_clock">Construct from Clock</link> -- 18 <link linkend="ptime_from_funcs">Construct using Conversion functions</link> -- 19 <link linkend="ptime_accessors">Accessors</link> -- 20 <link linkend="ptime_to_string">Conversion To String</link> -- 21 <link linkend="ptime_operators">Operators</link> -- 22 <link linkend="ptime_struct_tm">Struct tm, time_t, and FILETIME Functions</link> 23 24 <anchor id="ptime_intro" /> 25 <bridgehead renderas="sect3">Introduction</bridgehead> 26 <para> 27 The class boost::posix_time::ptime is the primary interface for time point manipulation. In general, the ptime class is immutable once constructed although it does allow assignment. 28 </para> 29 <para> 30 Class ptime is dependent on <link linkend="date_time.gregorian.date_class">gregorian::date</link> for the interface to the date portion of a time point. 31 </para> 32 <para> 33 Other techniques for creating times include <link linkend="date_time.posix_time.time_iterators">time iterators</link>. 34 </para> 35 36 <anchor id="ptime_header" /> 37 <bridgehead renderas="sect3">Header</bridgehead> 38 <para> 39 <programlisting>#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o 40or 41#include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types</programlisting> 42 </para> 43 44 <anchor id="ptime_constr" /> 45 <bridgehead renderas="sect3">Construction</bridgehead> 46 <para> 47 <informaltable frame="all"> 48 <tgroup cols="2"> 49 <thead> 50 <row> 51 <entry valign="top" morerows="1">Syntax</entry> 52 <entry>Description</entry> 53 </row> 54 <row> 55 <entry>Example</entry> 56 </row> 57 </thead> 58 <tbody> 59 <row> 60 <entry valign="top" morerows="1"><screen>ptime(date,time_duration)</screen></entry> 61 <entry>Construct from a date and offset</entry> 62 </row> 63 <row> 64 <entry><screen>ptime t1(date(2002,Jan,10), 65 time_duration(1,2,3)); 66ptime t2(date(2002,Jan,10), 67 hours(1)+nanosec(5));</screen> 68 </entry> 69 </row> 70 71 <row> 72 <entry valign="top" morerows="1"><screen>ptime(ptime)</screen></entry> 73 <entry>Copy constructor</entry> 74 </row> 75 <row> 76 <entry><screen>ptime t3(t1)</screen></entry> 77 </row> 78 79 <row> 80 <entry valign="top" morerows="1"><screen>ptime(special_values sv)</screen></entry> 81 <entry>Constructor for infinities, not-a-date-time, max_date_time, and min_date_time</entry> 82 </row> 83 <row> 84 <entry><screen>ptime d1(neg_infin); 85ptime d2(pos_infin); 86ptime d3(not_a_date_time); 87ptime d4(max_date_time); 88ptime d5(min_date_time);</screen></entry> 89 </row> 90 91 <row> 92 <entry valign="top" morerows="1"><screen>ptime;</screen></entry> 93 <entry>Default constructor. Creates a ptime object initialized to not_a_date_time. NOTE: this constructor can be disabled by defining DATE_TIME_NO_DEFAULT_CONSTRUCTOR (see compiler_config.hpp)</entry> 94 </row> 95 <row> 96 <entry><screen>ptime p; // p => not_a_date_time</screen></entry> 97 </row> 98 </tbody> 99 </tgroup> 100 </informaltable> 101 </para> 102 103 104 <anchor id="ptime_from_string" /> 105 <bridgehead renderas="sect3">Construct from String</bridgehead> 106 <para> 107 <informaltable frame="all"> 108 <tgroup cols="2"> 109 <thead> 110 <row> 111 <entry valign="top" morerows="1">Syntax</entry> 112 <entry>Description</entry> 113 </row> 114 <row> 115 <entry>Example</entry> 116 </row> 117 </thead> 118 <tbody> 119 <row> 120 <entry valign="top" morerows="1"><screen>ptime time_from_string(std::string)</screen></entry> 121 <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> 122 </row> 123 <row> 124 <entry><screen>std::string ts("2002-01-20 23:59:59.000"); 125ptime t(time_from_string(ts))</screen></entry> 126 </row> 127 128 <row> 129 <entry valign="top" morerows="1"><screen>ptime from_iso_string(std::string)</screen></entry> 130 <entry>From non delimited iso form string.</entry> 131 </row> 132 <row> 133 <entry><screen>std::string ts("20020131T235959"); 134ptime t(from_iso_string(ts))</screen></entry> 135 </row> 136 137 <row> 138 <entry valign="top" morerows="1"><screen>ptime from_iso_extended_string(std::string)</screen></entry> 139 <entry>From delimited iso form string.</entry> 140 </row> 141 <row> 142 <entry><screen>std::string ts("2020-01-31T23:59:59.123"); 143ptime t(from_iso_extended_string(ts))</screen></entry> 144 </row> 145 </tbody> 146 </tgroup> 147 </informaltable> 148 </para> 149 150 151 <anchor id="ptime_from_clock" /> 152 <bridgehead renderas="sect3">Construct from Clock</bridgehead> 153 <para> 154 <informaltable frame="all"> 155 <tgroup cols="2"> 156 <thead> 157 <row> 158 <entry valign="top" morerows="1">Syntax</entry> 159 <entry>Description</entry> 160 </row> 161 <row> 162 <entry>Example</entry> 163 </row> 164 </thead> 165 <tbody> 166 <row> 167 <entry valign="top" morerows="1"><screen>ptime second_clock::local_time()</screen></entry> 168 <entry>Get the local time, second level resolution, based on the time zone settings of the computer.</entry> 169 </row> 170 <row> 171 <entry><screen>ptime t(second_clock::local_time());</screen></entry> 172 </row> 173 174 <row> 175 <entry valign="top" morerows="1"><screen>ptime second_clock::universal_time()</screen></entry> 176 <entry>Get the UTC time.</entry> 177 </row> 178 <row> 179 <entry><screen>ptime t(second_clock::universal_time())</screen></entry> 180 </row> 181 182 <row> 183 <entry valign="top" morerows="1"><screen>ptime microsec_clock::local_time()</screen></entry> 184 <entry>Get the local time using a sub second resolution clock. On Unix systems this is implemented using gettimeofday. On most Win32 platforms it is implemented using ftime. Win32 systems often do not achieve microsecond resolution via this API. If higher resolution is critical to your application test your platform to see the achieved resolution.</entry> 185 </row> 186 <row> 187 <entry><screen>ptime t(microsec_clock::local_time());</screen></entry> 188 </row> 189 190 <row> 191 <entry valign="top" morerows="1"><screen>ptime microsec_clock::universal_time()</screen></entry> 192 <entry>Get the UTC time using a sub second resolution clock. On Unix systems this is implemented using gettimeofday. On most Win32 platforms it is implemented using ftime. Win32 systems often do not achieve microsecond resolution via this API. If higher resolution is critical to your application test your platform to see the achieved resolution.</entry> 193 </row> 194 <row> 195 <entry><screen>ptime t(microsec_clock::universal_time());</screen></entry> 196 </row> 197 </tbody> 198 </tgroup> 199 </informaltable> 200 </para> 201 202 203 <anchor id="ptime_from_funcs" /> 204 <bridgehead renderas="sect3">Construct using Conversion Functions</bridgehead> 205 <para> 206 <informaltable frame="all"> 207 <tgroup cols="2"> 208 <thead> 209 <row> 210 <entry valign="top" morerows="1">Syntax</entry> 211 <entry>Description</entry> 212 </row> 213 <row> 214 <entry>Example</entry> 215 </row> 216 </thead> 217 <tbody> 218 <row> 219 <entry valign="top" morerows="1"><screen>ptime from_time_t(time_t t);</screen></entry> 220 <entry>Converts a time_t into a ptime.</entry> 221 </row> 222 <row> 223 <entry><screen>ptime t = from_time_t(tt);</screen></entry> 224 </row> 225 226 <row> 227 <entry valign="top" morerows="1"><screen>ptime from_ftime<ptime>(FILETIME ft);</screen></entry> 228 <entry>Creates a ptime object from a FILETIME structure.</entry> 229 </row> 230 <row> 231 <entry><screen>ptime t = from_ftime<ptime>(ft);</screen></entry> 232 </row> 233 </tbody> 234 </tgroup> 235 </informaltable> 236 </para> 237 238 239 <anchor id="ptime_accessors" /> 240 <bridgehead renderas="sect3">Accessors</bridgehead> 241 <para> 242 <informaltable frame="all"> 243 <tgroup cols="2"> 244 <thead> 245 <row> 246 <entry valign="top" morerows="1">Syntax</entry> 247 <entry>Description</entry> 248 </row> 249 <row> 250 <entry>Example</entry> 251 </row> 252 </thead> 253 <tbody> 254 <row> 255 <entry valign="top" morerows="1"><screen>date date()</screen></entry> 256 <entry>Get the date part of a time.</entry> 257 </row> 258 <row> 259 <entry><screen>date d(2002,Jan,10); 260ptime t(d, hour(1)); 261t.date() --> 2002-Jan-10;</screen> 262 </entry> 263 </row> 264 265 <row> 266 <entry valign="top" morerows="1"><screen>time_duration time_of_day()</screen></entry> 267 <entry>Get the time offset in the day.</entry> 268 </row> 269 <row> 270 <entry><screen>date d(2002,Jan,10); 271ptime t(d, hour(1)); 272t.time_of_day() --> 01:00:00;</screen> 273 </entry> 274 </row> 275 276 <row> 277 <entry valign="top" morerows="1"><screen>bool is_infinity() const</screen></entry> 278 <entry>Returns true if ptime is either positive or negative infinity</entry> 279 </row> 280 <row> 281 <entry><screen>ptime pt(pos_infin); 282pt.is_infinity(); // --> true</screen></entry> 283 </row> 284 285 <row> 286 <entry valign="top" morerows="1"><screen>bool is_neg_infinity() const</screen></entry> 287 <entry>Returns true if ptime is negative infinity</entry> 288 </row> 289 <row> 290 <entry><screen>ptime pt(neg_infin); 291pt.is_neg_infinity(); // --> true</screen></entry> 292 </row> 293 294 <row> 295 <entry valign="top" morerows="1"><screen>bool is_pos_infinity() const</screen></entry> 296 <entry>Returns true if ptime is positive infinity</entry> 297 </row> 298 <row> 299 <entry><screen>ptime pt(neg_infin); 300pt.is_pos_infinity(); // --> true</screen></entry> 301 </row> 302 303 <row> 304 <entry valign="top" morerows="1"><screen>bool is_not_a_date_time() const</screen></entry> 305 <entry>Returns true if value is not a ptime</entry> 306 </row> 307 <row> 308 <entry><screen>ptime pt(not_a_date_time); 309pt.is_not_a_date_time(); // --> true</screen></entry> 310 </row> 311 312 <row> 313 <entry valign="top" morerows="1"><screen>bool is_special() const</screen></entry> 314 <entry>Returns true if ptime is any <code>special_value</code></entry> 315 </row> 316 <row> 317 <entry><screen>ptime pt(pos_infin); 318ptime pt2(not_a_date_time); 319ptime pt3(date(2005,Mar,1), hours(10)); 320pt.is_special(); // --> true 321pt2.is_special(); // --> true 322pt3.is_special(); // --> false</screen></entry> 323 </row> 324 325 </tbody> 326 </tgroup> 327 </informaltable> 328 </para> 329 330 331 <anchor id="ptime_to_string" /> 332 <bridgehead renderas="sect3">Conversion to String</bridgehead> 333 <para> 334 <informaltable frame="all"> 335 <tgroup cols="2"> 336 <thead> 337 <row> 338 <entry valign="top" morerows="1">Syntax</entry> 339 <entry>Description</entry> 340 </row> 341 <row> 342 <entry>Example</entry> 343 </row> 344 </thead> 345 <tbody> 346 <row> 347 <entry valign="top" morerows="1"><screen>std::string to_simple_string(ptime)</screen></entry> 348 <entry>To <code>YYYY-mmm-DD HH:MM:SS.fffffffff</code> string where <code>mmm</code> 3 char month name. Fractional seconds only included if non-zero.</entry> 349 </row> 350 <row> 351 <entry><screen>2002-Jan-01 10:00:01.123456789</screen></entry> 352 </row> 353 354 <row> 355 <entry valign="top" morerows="1"><screen>std::string to_iso_string(ptime)</screen></entry> 356 <entry>Convert to form <code>YYYYMMDDTHHMMSS,fffffffff</code> where <code>T</code> is the date-time separator</entry> 357 </row> 358 <row> 359 <entry><screen>20020131T100001,123456789</screen></entry> 360 </row> 361 362 <row> 363 <entry valign="top" morerows="1"><screen>std::string to_iso_extended_string(ptime)</screen></entry> 364 <entry>Convert to form <code>YYYY-MM-DDTHH:MM:SS,fffffffff</code> where <code>T</code> is the date-time separator</entry> 365 </row> 366 <row> 367 <entry><screen>2002-01-31T10:00:01,123456789</screen></entry> 368 </row> 369 </tbody> 370 </tgroup> 371 </informaltable> 372 </para> 373 374 375 <anchor id="ptime_operators" /> 376 <bridgehead renderas="sect3">Operators</bridgehead> 377 <para> 378 <informaltable frame="all"> 379 <tgroup cols="2"> 380 <thead> 381 <row> 382 <entry valign="top" morerows="1">Syntax</entry> 383 <entry>Description</entry> 384 </row> 385 <row> 386 <entry>Example</entry> 387 </row> 388 </thead> 389 <tbody> 390 <row> 391 <entry valign="top" morerows="1"><screen>operator<<, operator>></screen></entry> 392 <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> 393 </row> 394 <row> 395 <entry><screen>ptime pt(not_a_date_time); 396stringstream ss("2002-Jan-01 14:23:11"); 397ss >> pt; 398std::cout << pt; // "2002-Jan-01 14:23:11" 399 </screen> 400 </entry> 401 </row> 402 403 <row> 404 <entry valign="top" morerows="1"><screen>operator==, operator!=, 405operator>, operator<, 406operator>=, operator<=</screen> 407 </entry> 408 <entry>A full complement of comparison operators</entry> 409 </row> 410 <row> 411 <entry><screen>t1 == t2, etc</screen></entry> 412 </row> 413 414 <row> 415 <entry valign="top" morerows="1"><screen>ptime operator+(days)</screen></entry> 416 <entry>Return a ptime adding a day offset</entry> 417 </row> 418 <row> 419 <entry><screen>date d(2002,Jan,1); 420ptime t(d,minutes(5)); 421days dd(1); 422ptime t2 = t + dd;</screen> 423 </entry> 424 </row> 425 426 <row> 427 <entry valign="top" morerows="1"><screen>ptime operator-(days)</screen></entry> 428 <entry>Return a ptime subtracting a day offset</entry> 429 </row> 430 <row> 431 <entry><screen>date d(2002,Jan,1); 432ptime t(d,minutes(5)); 433days dd(1); 434ptime t2 = t - dd;</screen> 435 </entry> 436 </row> 437 438 <row> 439 <entry valign="top" morerows="1"><screen>ptime operator+(time_duration)</screen></entry> 440 <entry>Return a ptime adding a time duration</entry> 441 </row> 442 <row> 443 <entry><screen>date d(2002,Jan,1); 444ptime t(d,minutes(5)); 445ptime t2 = t + hours(1) + minutes(2);</screen> 446 </entry> 447 </row> 448 449 <row> 450 <entry valign="top" morerows="1"><screen>ptime operator-(time_duration)</screen></entry> 451 <entry>Return a ptime subtracting a time duration</entry> 452 </row> 453 <row> 454 <entry><screen>date d(2002,Jan,1); 455ptime t(d,minutes(5)); 456ptime t2 = t - minutes(2);</screen> 457 </entry> 458 </row> 459 460 <row> 461 <entry valign="top" morerows="1"><screen>time_duration operator-(ptime)</screen></entry> 462 <entry>Take the difference between two times.</entry> 463 </row> 464 <row> 465 <entry><screen>date d(2002,Jan,1); 466ptime t1(d,minutes(5)); 467ptime t2(d,seconds(5)); 468time_duration t3 = t2 - t1;//negative result</screen> 469 </entry> 470 </row> 471 </tbody> 472 </tgroup> 473 </informaltable> 474 </para> 475 476 <anchor id="ptime_struct_tm" /> 477 <bridgehead renderas="sect3">Struct tm, time_t, and FILETIME Functions</bridgehead> 478 <para>Functions for converting posix_time objects to, and from, <code>tm</code> structs are provided as well as conversion from <code>time_t</code> and <code>FILETIME</code>.</para> 479 <informaltable frame="all"> 480 <tgroup cols="2"> 481 <thead> 482 <row> 483 <entry valign="top" morerows="1">Syntax</entry> 484 <entry>Description</entry> 485 </row> 486 <row> 487 <entry>Example</entry> 488 </row> 489 </thead> 490 <tbody> 491 <row> 492 <entry valign="top" morerows="1"><screen>tm to_tm(ptime)</screen></entry> 493 <entry>A function for converting a <code>ptime</code> object to a <code>tm</code> struct. The <code>tm_isdst</code> field is set to -1.</entry> 494 </row> 495 <row> 496 <entry><screen>ptime pt(date(2005,Jan,1), time_duration(1,2,3)); 497tm pt_tm = to_tm(pt); 498/* tm_year => 105 499 tm_mon => 0 500 tm_mday => 1 501 tm_wday => 6 (Saturday) 502 tm_yday => 0 503 tm_hour => 1 504 tm_min => 2 505 tm_sec => 3 506 tm_isdst => -1 */</screen> 507 </entry> 508 </row> 509 510 <row> 511 <entry valign="top" morerows="1"><screen>ptime ptime_from_tm(tm timetm)</screen></entry> 512 <entry>A function for converting a <code>tm</code> struct to a <code>ptime</code> object. The fields: <code>tm_wday </code>, <code>tm_yday </code>, and <code>tm_isdst</code> are ignored.</entry> 513 </row> 514 <row> 515 <entry><screen>tm pt_tm; 516pt_tm.tm_year = 105; 517pt_tm.tm_mon = 0; 518pt_tm.tm_mday = 1; 519pt_tm.tm_hour = 1; 520pt_tm.tm_min = 2; 521pt_tm.tm_sec = 3; 522ptime pt = ptime_from_tm(pt_tm); 523// pt => 2005-Jan-01 01:02:03</screen> 524 </entry> 525 </row> 526 527 <row> 528 <entry valign="top" morerows="1"><screen>tm to_tm(time_duration)</screen></entry> 529 <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> 530 </row> 531 <row> 532 <entry><screen>time_duration td(1,2,3); 533tm td_tm = to_tm(td); 534/* tm_year => 0 535 tm_mon => 0 536 tm_mday => 0 537 tm_wday => 0 538 tm_yday => 0 539 tm_hour => 1 540 tm_min => 2 541 tm_sec => 3 542 tm_isdst => -1 */</screen> 543 </entry> 544 </row> 545 546 <row> 547 <entry valign="top" morerows="1"><screen>ptime from_time_t(std::time_t)</screen></entry> 548 <entry>Creates a <code>ptime</code> from the time_t parameter. The seconds held in the time_t are added to a time point of 1970-Jan-01.</entry> 549 </row> 550 <row> 551 <entry><screen>ptime pt(not_a_date_time); 552std::time_t t; 553t = 1118158776; 554pt = from_time_t(t); 555// pt => 2005-Jun-07 15:39:36</screen></entry> 556 </row> 557 558 <row> 559 <entry valign="top" morerows="1"><screen>ptime from_ftime<ptime>(FILETIME)</screen></entry> 560 <entry>A template function that constructs a <code>ptime</code> from a FILETIME struct.</entry> 561 </row> 562 <row> 563 <entry><screen>FILETIME ft; 564ft.dwHighDateTime = 29715317; 565ft.dwLowDateTime = 3865122988UL; 566ptime pt = from_ftime<ptime>(ft); 567// pt => 2005-Jun-07 15:30:57.039582000</screen></entry> 568 </row> 569 570 </tbody> 571 </tgroup> 572 </informaltable> 573 574</section> 575