ceph/src/boost/libs/date_time/xmldoc/ptime_class.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.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
  40 or
  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));
  66 ptime 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);
  85 ptime d2(pos_infin);
  86 ptime d3(not_a_date_time);
  87 ptime d4(max_date_time);
  88 ptime 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 =&gt; 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" =&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>
 122           </row>
 123           <row>
 124             <entry><screen>std::string ts("2002-01-20 23:59:59.000");
 125 ptime 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");
 134 ptime t(from_iso_string(ts))</screen></entry>
 135           </row>
 136         </tbody>
 137       </tgroup>
 138     </informaltable>
 139   </para>
 140
 141
 142   <anchor id="ptime_from_clock" />
 143   <bridgehead renderas="sect3">Construct from Clock</bridgehead>
 144   <para>
 145     <informaltable frame="all">
 146       <tgroup cols="2">
 147         <thead>
 148           <row>
 149             <entry valign="top" morerows="1">Syntax</entry>
 150             <entry>Description</entry>
 151           </row>
 152           <row>
 153             <entry>Example</entry>
 154           </row>
 155         </thead>
 156         <tbody>
 157           <row>
 158             <entry valign="top" morerows="1"><screen>ptime second_clock::local_time()</screen></entry>
 159             <entry>Get the local time, second level resolution, based on the time zone settings of the computer.</entry>
 160           </row>
 161           <row>
 162             <entry><screen>ptime t(second_clock::local_time());</screen></entry>
 163           </row>
 164
 165           <row>
 166             <entry valign="top" morerows="1"><screen>ptime second_clock::universal_time()</screen></entry>
 167             <entry>Get the UTC time.</entry>
 168           </row>
 169           <row>
 170             <entry><screen>ptime t(second_clock::universal_time())</screen></entry>
 171           </row>
 172
 173           <row>
 174             <entry valign="top" morerows="1"><screen>ptime microsec_clock::local_time()</screen></entry>
 175             <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>
 176           </row>
 177           <row>
 178             <entry><screen>ptime t(microsec_clock::local_time());</screen></entry>
 179           </row>
 180
 181           <row>
 182             <entry valign="top" morerows="1"><screen>ptime microsec_clock::universal_time()</screen></entry>
 183             <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>
 184           </row>
 185           <row>
 186             <entry><screen>ptime t(microsec_clock::universal_time());</screen></entry>
 187           </row>
 188         </tbody>
 189       </tgroup>
 190     </informaltable>
 191   </para>
 192
 193
 194   <anchor id="ptime_from_funcs" />
 195   <bridgehead renderas="sect3">Construct using Conversion Functions</bridgehead>
 196   <para>
 197     <informaltable frame="all">
 198       <tgroup cols="2">
 199         <thead>
 200           <row>
 201             <entry valign="top" morerows="1">Syntax</entry>
 202             <entry>Description</entry>
 203           </row>
 204           <row>
 205             <entry>Example</entry>
 206           </row>
 207         </thead>
 208         <tbody>
 209           <row>
 210             <entry valign="top" morerows="1"><screen>ptime from_time_t(time_t t);</screen></entry>
 211             <entry>Converts a time_t into a ptime.</entry>
 212           </row>
 213           <row>
 214             <entry><screen>ptime t = from_time_t(tt);</screen></entry>
 215           </row>
 216
 217           <row>
 218             <entry valign="top" morerows="1"><screen>ptime from_ftime&lt;ptime&gt;(FILETIME ft);</screen></entry>
 219             <entry>Creates a ptime object from a FILETIME structure.</entry>
 220           </row>
 221           <row>
 222             <entry><screen>ptime t = from_ftime&lt;ptime&gt;(ft);</screen></entry>
 223           </row>
 224         </tbody>
 225       </tgroup>
 226     </informaltable>
 227   </para>
 228
 229
 230   <anchor id="ptime_accessors" />
 231   <bridgehead renderas="sect3">Accessors</bridgehead>
 232   <para>
 233     <informaltable frame="all">
 234       <tgroup cols="2">
 235         <thead>
 236           <row>
 237             <entry valign="top" morerows="1">Syntax</entry>
 238             <entry>Description</entry>
 239           </row>
 240           <row>
 241             <entry>Example</entry>
 242           </row>
 243         </thead>
 244         <tbody>
 245           <row>
 246             <entry valign="top" morerows="1"><screen>date date()</screen></entry>
 247             <entry>Get the date part of a time.</entry>
 248           </row>
 249           <row>
 250             <entry><screen>date d(2002,Jan,10);
 251 ptime t(d, hour(1));
 252 t.date() --> 2002-Jan-10;</screen>
 253             </entry>
 254           </row>
 255
 256           <row>
 257             <entry valign="top" morerows="1"><screen>time_duration time_of_day()</screen></entry>
 258             <entry>Get the time offset in the day.</entry>
 259           </row>
 260           <row>
 261             <entry><screen>date d(2002,Jan,10);
 262 ptime t(d, hour(1));
 263 t.time_of_day() --> 01:00:00;</screen>
 264             </entry>
 265           </row>
 266
 267           <row>
 268             <entry valign="top" morerows="1"><screen>bool is_infinity() const</screen></entry>
 269             <entry>Returns true if ptime is either positive or negative infinity</entry>
 270           </row>
 271           <row>
 272             <entry><screen>ptime pt(pos_infin);
 273 pt.is_infinity(); // --> true</screen></entry>
 274           </row>
 275
 276           <row>
 277             <entry valign="top" morerows="1"><screen>bool is_neg_infinity() const</screen></entry>
 278             <entry>Returns true if ptime is negative infinity</entry>
 279           </row>
 280           <row>
 281             <entry><screen>ptime pt(neg_infin);
 282 pt.is_neg_infinity(); // --> true</screen></entry>
 283           </row>
 284
 285           <row>
 286             <entry valign="top" morerows="1"><screen>bool is_pos_infinity() const</screen></entry>
 287             <entry>Returns true if ptime is positive infinity</entry>
 288           </row>
 289           <row>
 290             <entry><screen>ptime pt(neg_infin);
 291 pt.is_pos_infinity(); // --> true</screen></entry>
 292           </row>
 293
 294           <row>
 295             <entry valign="top" morerows="1"><screen>bool is_not_a_date_time() const</screen></entry>
 296             <entry>Returns true if value is not a ptime</entry>
 297           </row>
 298           <row>
 299             <entry><screen>ptime pt(not_a_date_time);
 300 pt.is_not_a_date_time(); // --> true</screen></entry>
 301           </row>
 302
 303           <row>
 304             <entry valign="top" morerows="1"><screen>bool is_special() const</screen></entry>
 305             <entry>Returns true if ptime is any <code>special_value</code></entry>
 306           </row>
 307           <row>
 308             <entry><screen>ptime pt(pos_infin);
 309 ptime pt2(not_a_date_time);
 310 ptime pt3(date(2005,Mar,1), hours(10));
 311 pt.is_special(); // --> true
 312 pt2.is_special(); // --> true
 313 pt3.is_special(); // --> false</screen></entry>
 314           </row>
 315
 316         </tbody>
 317       </tgroup>
 318     </informaltable>
 319   </para>
 320
 321
 322   <anchor id="ptime_to_string" />
 323   <bridgehead renderas="sect3">Conversion to String</bridgehead>
 324   <para>
 325     <informaltable frame="all">
 326       <tgroup cols="2">
 327         <thead>
 328           <row>
 329             <entry valign="top" morerows="1">Syntax</entry>
 330             <entry>Description</entry>
 331           </row>
 332           <row>
 333             <entry>Example</entry>
 334           </row>
 335         </thead>
 336         <tbody>
 337           <row>
 338             <entry valign="top" morerows="1"><screen>std::string to_simple_string(ptime)</screen></entry>
 339             <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>
 340           </row>
 341           <row>
 342             <entry><screen>2002-Jan-01 10:00:01.123456789</screen></entry>
 343           </row>
 344
 345           <row>
 346             <entry valign="top" morerows="1"><screen>std::string to_iso_string(ptime)</screen></entry>
 347             <entry>Convert to form <code>YYYYMMDDTHHMMSS,fffffffff</code> where <code>T</code> is the date-time separator</entry>
 348           </row>
 349           <row>
 350             <entry><screen>20020131T100001,123456789</screen></entry>
 351           </row>
 352
 353           <row>
 354             <entry valign="top" morerows="1"><screen>std::string to_iso_extended_string(ptime)</screen></entry>
 355             <entry>Convert to form <code>YYYY-MM-DDTHH:MM:SS,fffffffff</code> where <code>T</code> is the date-time separator</entry>
 356           </row>
 357           <row>
 358             <entry><screen>2002-01-31T10:00:01,123456789</screen></entry>
 359           </row>
 360         </tbody>
 361       </tgroup>
 362     </informaltable>
 363   </para>
 364
 365
 366   <anchor id="ptime_operators" />
 367   <bridgehead renderas="sect3">Operators</bridgehead>
 368   <para>
 369     <informaltable frame="all">
 370       <tgroup cols="2">
 371         <thead>
 372           <row>
 373             <entry valign="top" morerows="1">Syntax</entry>
 374             <entry>Description</entry>
 375           </row>
 376           <row>
 377             <entry>Example</entry>
 378           </row>
 379         </thead>
 380         <tbody>
 381           <row>
 382             <entry valign="top" morerows="1"><screen>operator&lt;&lt;, operator&gt;&gt;</screen></entry>
 383             <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>
 384           </row>
 385           <row>
 386             <entry><screen>ptime pt(not_a_date_time);
 387 stringstream ss("2002-Jan-01 14:23:11");
 388 ss &gt;&gt; pt;
 389 std::cout &lt;&lt; pt; // "2002-Jan-01 14:23:11"
 390   </screen>
 391             </entry>
 392           </row>
 393
 394           <row>
 395             <entry valign="top" morerows="1"><screen>operator==, operator!=,
 396 operator>, operator&lt;,
 397 operator>=, operator&lt;=</screen>
 398             </entry>
 399             <entry>A full complement of comparison operators</entry>
 400           </row>
 401           <row>
 402             <entry><screen>t1 == t2, etc</screen></entry>
 403           </row>
 404
 405           <row>
 406             <entry valign="top" morerows="1"><screen>ptime operator+(days)</screen></entry>
 407             <entry>Return a ptime adding a day offset</entry>
 408           </row>
 409           <row>
 410             <entry><screen>date d(2002,Jan,1);
 411 ptime t(d,minutes(5));
 412 days dd(1);
 413 ptime t2 = t + dd;</screen>
 414             </entry>
 415           </row>
 416
 417           <row>
 418             <entry valign="top" morerows="1"><screen>ptime operator-(days)</screen></entry>
 419             <entry>Return a ptime subtracting a day offset</entry>
 420           </row>
 421           <row>
 422             <entry><screen>date d(2002,Jan,1);
 423 ptime t(d,minutes(5));
 424 days dd(1);
 425 ptime t2 = t - dd;</screen>
 426             </entry>
 427           </row>
 428
 429           <row>
 430             <entry valign="top" morerows="1"><screen>ptime operator+(time_duration)</screen></entry>
 431             <entry>Return a ptime adding a time duration</entry>
 432           </row>
 433           <row>
 434             <entry><screen>date d(2002,Jan,1);
 435 ptime t(d,minutes(5));
 436 ptime t2 = t + hours(1) + minutes(2);</screen>
 437             </entry>
 438           </row>
 439
 440           <row>
 441             <entry valign="top" morerows="1"><screen>ptime operator-(time_duration)</screen></entry>
 442             <entry>Return a ptime subtracting a time duration</entry>
 443           </row>
 444           <row>
 445             <entry><screen>date d(2002,Jan,1);
 446 ptime t(d,minutes(5));
 447 ptime t2 = t - minutes(2);</screen>
 448             </entry>
 449           </row>
 450
 451           <row>
 452             <entry valign="top" morerows="1"><screen>time_duration operator-(ptime)</screen></entry>
 453             <entry>Take the difference between two times.</entry>
 454           </row>
 455           <row>
 456             <entry><screen>date d(2002,Jan,1);
 457 ptime t1(d,minutes(5));
 458 ptime t2(d,seconds(5));
 459 time_duration t3 = t2 - t1;//negative result</screen>
 460             </entry>
 461           </row>
 462         </tbody>
 463       </tgroup>
 464     </informaltable>
 465   </para>
 466
 467   <anchor id="ptime_struct_tm" />
 468   <bridgehead renderas="sect3">Struct tm, time_t, and FILETIME Functions</bridgehead>
 469   <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>
 470   <informaltable frame="all">
 471     <tgroup cols="2">
 472       <thead>
 473         <row>
 474           <entry valign="top" morerows="1">Syntax</entry>
 475           <entry>Description</entry>
 476         </row>
 477         <row>
 478           <entry>Example</entry>
 479         </row>
 480       </thead>
 481       <tbody>
 482         <row>
 483           <entry valign="top" morerows="1"><screen>tm to_tm(ptime)</screen></entry>
 484           <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>
 485         </row>
 486         <row>
 487           <entry><screen>ptime pt(date(2005,Jan,1), time_duration(1,2,3));
 488 tm pt_tm = to_tm(pt);
 489 /* tm_year => 105
 490    tm_mon  => 0
 491    tm_mday => 1
 492    tm_wday => 6 (Saturday)
 493    tm_yday => 0
 494    tm_hour => 1
 495    tm_min  => 2
 496    tm_sec  => 3
 497    tm_isddst => -1 */</screen>
 498           </entry>
 499         </row>
 500
 501         <row>
 502           <entry valign="top" morerows="1"><screen>ptime ptime_from_tm(tm timetm)</screen></entry>
 503           <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>
 504         </row>
 505         <row>
 506           <entry><screen>tm pt_tm;
 507 pt_tm.tm_year = 105;
 508 pt_tm.tm_mon  = 0;
 509 pt_tm.tm_mday = 1;
 510 pt_tm.tm_hour = 1;
 511 pt_tm.tm_min  = 2;
 512 pt_tm.tm_sec  = 3;
 513 ptime pt = ptime_from_tm(pt_tm);
 514 // pt => 2005-Jan-01 01:02:03</screen>
 515           </entry>
 516         </row>
 517
 518         <row>
 519           <entry valign="top" morerows="1"><screen>tm to_tm(time_duration)</screen></entry>
 520           <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>
 521         </row>
 522         <row>
 523           <entry><screen>time_duration td(1,2,3);
 524 tm td_tm = to_tm(td);
 525 /* tm_year => 0
 526    tm_mon  => 0
 527    tm_mday => 0
 528    tm_wday => 0
 529    tm_yday => 0
 530    tm_hour => 1
 531    tm_min  => 2
 532    tm_sec  => 3
 533    tm_isddst => -1 */</screen>
 534           </entry>
 535         </row>
 536
 537         <row>
 538           <entry valign="top" morerows="1"><screen>ptime from_time_t(std::time_t)</screen></entry>
 539           <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>
 540         </row>
 541         <row>
 542           <entry><screen>ptime pt(not_a_date_time);
 543 std::time_t t;
 544 t = 1118158776;
 545 pt = from_time_t(t);
 546 // pt => 2005-Jun-07 15:39:36</screen></entry>
 547         </row>
 548
 549         <row>
 550           <entry valign="top" morerows="1"><screen>ptime from_ftime&lt;ptime>(FILETIME)</screen></entry>
 551           <entry>A template function that constructs a <code>ptime</code> from a FILETIME struct.</entry>
 552         </row>
 553         <row>
 554           <entry><screen>FILETIME ft;
 555 ft.dwHighDateTime = 29715317;
 556 ft.dwLowDateTime = 3865122988UL;
 557 ptime pt = from_ftime&lt;ptime>(ft);
 558 // pt => 2005-Jun-07 15:30:57.039582000</screen></entry>
 559         </row>
 560
 561       </tbody>
 562     </tgroup>
 563   </informaltable>
 564
 565 </section>