ceph/src/boost/libs/date_time/xmldoc/local_date_time.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.local_time.local_date_time">
  11   <title>Local Date Time</title>
  12
  13   <link linkend="local_date_time_intro">Introduction</link> --
  14   <link linkend="local_date_time_header">Header</link> --
  15   <link linkend="local_date_time_clock_constr">Construct From Clock</link> --
  16   <link linkend="local_date_time_constr">Construction</link> --
  17   <link linkend="local_date_time_accessors">Accessors</link> --
  18   <link linkend="local_date_time_operators">Operators</link> --
  19   <link linkend="local_date_time_tm_func">Struct tm Functions</link>
  20
  21   <anchor id="local_date_time_intro" />
  22   <bridgehead renderas="sect3">Introduction</bridgehead>
  23   <para>
  24     A local_date_time object is a point in time and an associated time zone. The time is represented internally as UTC.
  25   </para>
  26
  27   <anchor id="local_date_time_header" />
  28   <bridgehead renderas="sect3">Header</bridgehead>
  29   <para>
  30     The inclusion of a single header will bring in all boost::local_time types,
  31 functions, and IO operators.
  32     <programlisting>
  33       #include "boost/date_time/local_time/local_time.hpp"
  34     </programlisting>
  35   </para>
  36
  37   <anchor id="local_date_time_clock_constr" />
  38   <bridgehead renderas="sect3">Construct From Clock</bridgehead>
  39   <para>
  40     Creation of a local_date_time object from clock is possible with either second, or sub second resolution.
  41   </para>
  42   <para>
  43     <informaltable frame="all">
  44       <tgroup cols="2">
  45         <thead>
  46           <row>
  47             <entry>Syntax</entry>
  48             <entry>Example</entry>
  49           </row>
  50         </thead>
  51         <tbody>
  52           <row>
  53             <entry valign="top"><screen>local_microsec_clock(...)
  54   Return Type:
  55     local_date_time
  56   Parameter:
  57     time_zone_ptr</screen></entry>
  58             <entry><screen>time_zone_ptr zone(
  59   new posix_time_zone("MST-07")
  60 );
  61 local_date_time ldt =
  62   local_microsec_clock::local_time(
  63     zone);</screen>
  64             </entry>
  65           </row>
  66           <row>
  67             <entry valign="top"><screen>local_sec_clock(...)
  68   Return Type:
  69     local_date_time
  70   Parameter:
  71     time_zone_ptr</screen></entry>
  72             <entry><screen>time_zone_ptr zone(
  73   new posix_time_zone("MST-07")
  74 );
  75 local_date_time ldt =
  76   local_sec_clock::local_time(zone);</screen>
  77             </entry>
  78           </row>
  79         </tbody>
  80       </tgroup>
  81     </informaltable>
  82   </para>
  83
  84   <anchor id="local_date_time_constr" />
  85   <bridgehead renderas="sect3">Construction</bridgehead>
  86   <para>
  87     Construction of a local_date_time object can be done with a ptime and a time_zone_ptr where the ptime represents UTC time. Construction with a wall-clock representation takes the form of a date, a time_duration, a time_zone_ptr, and a fourth parameter that addresses the following complication.
  88   </para>
  89   <para>
  90     Construction from a wall-clock rep may result in differing shifts for a particular time zone, depending on daylight savings rules for that zone. This means it is also possible to create a local_date_time with a non-existent, or duplicated, UTC representation. These cases occur during the forward shift in time that is the transition into daylight savings and during the backward shift that is the transition out of daylight savings. The user has two options for handling these cases: a bool flag that states if the time is daylight savings, or an enum that states what to do when either of these cases are encountered.
  91   </para>
  92   <para>
  93     The bool flag is ignored when the given time_zone has no daylight savings specification. When the daylight savings status of a given time label is calculated and it does not match the flag, a <code>local_time::dst_not_valid</code> exception is thrown. If a time label is invalid (does not exist), a <code>local_time::time_label_invalid</code> exception is thrown.
  94   </para>
  95   <para>
  96     There are two elements in the <code>local_date_time::DST_CALC_OPTIONS</code> enum: <code>EXCEPTION_ON_ERROR</code> and <code>NOT_DATE_TIME_ON_ERROR</code>. The possible exceptions thrown are a <code>local_time::ambiguous_result</code> or a <code>local_time::time_label_invalid</code>. The <code>NOT_DATE_TIME_ON_ERROR</code> sets the time value to the special value <code>local_time::not_a_date_time</code> in the event of either a invalid or an ambiguous time label.
  97   </para>
  98   <para>
  99     <informaltable frame="all">
 100       <tgroup cols="2">
 101         <thead>
 102           <row>
 103             <entry morerows="1">Syntax</entry>
 104             <entry>Description</entry>
 105           </row>
 106           <row>
 107             <entry>Example</entry>
 108           </row>
 109         </thead>
 110         <tbody>
 111           <row>
 112             <entry valign="top" morerows="1"><screen>local_date_time(...)
 113   Parameters:
 114     posix_time::ptime
 115     time_zone_ptr</screen></entry>
 116             <entry>The given time is expected to be UTC. Therefore, the given time will be adjusted according to the offset described in the time zone.</entry>
 117           </row>
 118           <row>
 119             <entry><screen>
 120 // 3am, 2004-Nov-05 local time
 121 ptime pt(date(2004,Nov,5),
 122          hours(10));
 123 time_zone_ptr zone(
 124   new posix_time_zone("MST-07"));
 125 local_date_time az(pt, zone);</screen>
 126             </entry>
 127           </row>
 128
 129           <row>
 130             <entry valign="top" morerows="1"><screen>local_date_time(...)
 131   Parameters:
 132     date
 133     time_duration
 134     time_zone_ptr
 135     bool</screen></entry>
 136 <entry>The passed time information understood to be in the passed tz. The DST flag must be passed to indicate whether the time is in daylight savings or not. May throw a <code>dst_not_valid</code> or <code>time_label_invalid</code> exception.</entry>
 137           </row>
 138           <row>
 139             <entry><screen>date d(2004,Nov,5);
 140 time_duration td(5,0,0,0);
 141 string z("PST-8PDT,M4.1.0,M10.1.0")
 142 time_zone_ptr zone(
 143   new posix_time_zone(z));
 144 local_date_time nyc(d, td,
 145                     zone, false);</screen>
 146             </entry>
 147           </row>
 148
 149           <row>
 150             <entry valign="top" morerows="1"><screen>local_date_time(...)
 151   Parameters:
 152     date
 153     time_duration
 154     time_zone_ptr
 155     DST_CALC_OPTIONS</screen></entry>
 156             <entry>The passed time information understood to be in the passed tz. The DST flag is calculated according to the specified rule. May throw a <code>ambiguous_result</code> or <code>time_label_invalid</code> exception.</entry>
 157           </row>
 158           <row>
 159             <entry><screen>date d(2004,Nov,5);
 160 time_duration td(5,0,0,0);
 161 string z("PST-8PDT,M4.1.0,M10.1.0")
 162 time_zone_ptr zone(
 163   new posix_time_zone(z));
 164 local_date_time nyc(d, td, zone,
 165   NOT_DATE_TIME_ON_ERROR);</screen>
 166             </entry>
 167           </row>
 168
 169           <row>
 170             <entry valign="top" morerows="1"><screen>local_date_time(local_date_time);</screen></entry>
 171             <entry>Copy Constructor.</entry>
 172           </row>
 173           <row>
 174             <entry><screen>local_date_time az_2(az);</screen></entry>
 175           </row>
 176
 177           <row>
 178             <entry valign="top" morerows="1"><screen>local_date_time(...)
 179   Parameters:
 180     special_values
 181     time_zone_ptr</screen></entry>
 182             <entry>Special Values constructor.</entry>
 183           </row>
 184           <row>
 185             <entry><screen>time_zone_ptr zone(
 186   new posix_time_zone("MST-07")
 187 );
 188 local_date_time nadt(not_a_date_time,
 189                      zone);
 190 // default NULL time_zone_ptr
 191 local_date_time nadt(pos_infin);</screen>
 192             </entry>
 193           </row>
 194
 195         </tbody>
 196       </tgroup>
 197     </informaltable>
 198   </para>
 199
 200   <anchor id="local_date_time_accessors" />
 201   <bridgehead renderas="sect3">Accessors</bridgehead>
 202   <para>
 203     <informaltable frame="all">
 204       <tgroup cols="2">
 205         <thead>
 206           <row>
 207             <entry valign="top" morerows="1">Syntax</entry>
 208             <entry>Description</entry>
 209           </row>
 210           <row>
 211               <entry>Example</entry>
 212           </row>
 213         </thead>
 214         <tbody>
 215           <row>
 216             <entry valign="top" morerows="1"><screen>time_zone_ptr zone()</screen></entry>
 217             <entry>Returns associated time_zone object via a time_zone_ptr</entry>
 218           </row>
 219           <row>
 220             <entry><screen></screen></entry>
 221           </row>
 222
 223           <row>
 224             <entry valign="top" morerows="1"><screen>bool is_dst()</screen></entry>
 225             <entry>Determines if time value is in DST for associated zone.</entry>
 226           </row>
 227           <row>
 228             <entry></entry>
 229           </row>
 230
 231           <row>
 232             <entry valign="top" morerows="1"><screen>ptime utc_time()</screen></entry>
 233             <entry>Converts the local time value to a UTC value.</entry>
 234           </row>
 235           <row>
 236             <entry><screen>ptime pt(date(2004,Nov,5),
 237          hours(10));
 238 time_zone_ptr zone(
 239   new posix_time_zone("MST-07"));
 240 local_date_time az(pt, zone);
 241 az.utc_time(); // 10am 2004-Nov-5</screen>
 242             </entry>
 243           </row>
 244
 245           <row>
 246             <entry valign="top" morerows="1"><screen>ptime local_time()</screen></entry>
 247             <entry>Returns the local time for this object (Wall-clock).</entry>
 248           </row>
 249           <row>
 250             <entry><screen>ptime pt(date(2004,Nov,5),
 251          hours(10));
 252 time_zone_ptr zone(
 253   new posix_time_zone("MST-07"));
 254 local_date_time az(pt, zone);
 255 az.utc_time(); // 10am 2004-Nov-5
 256 az.local_time(); // 3am 2004-Nov-5</screen></entry>
 257           </row>
 258
 259           <row>
 260             <entry valign="top" morerows="1"><screen>local_time_in(...)
 261   Return Type:
 262     local_date_time
 263   Parameters:
 264     time_zone_ptr
 265     time_duration</screen></entry>
 266             <entry>Returns a local_date_time representing the same UTC time as calling object, plus optional time_duration, with given time zone.</entry>
 267           </row>
 268           <row>
 269             <entry><screen>local_date_time nyc = az.local_time_in(nyc_zone);
 270 // nyc == 7am 2004-Nov-5</screen>
 271             </entry>
 272           </row>
 273           <!--
 274           <row>
 275             <entry valign="top" morerows="1"><screen>std::string zone_name()</screen></entry>
 276             <entry>Returns full zone name from associated time zone or "Coordinated Universal Time" if time_zone_ptr is NULL.</entry>
 277           </row>
 278           <row>
 279             <entry>
 280             </entry>
 281           </row>
 282
 283           <row>
 284             <entry valign="top" morerows="1"><screen>std::string zone_abbrev()</screen></entry>
 285             <entry>Returns zone abbreviation from associated time zone or "UTC" if time_zone_ptr is NULL.</entry>
 286           </row>
 287           <row>
 288             <entry>
 289             </entry>
 290           </row>
 291           -->
 292           <row>
 293             <entry valign="top" morerows="1"><screen>bool is_infinity() const</screen></entry>
 294             <entry>Returns true if local_date_time is either positive or negative infinity</entry>
 295           </row>
 296           <row>
 297             <entry><screen>local_date_time ldt(pos_infin);
 298 ldt.is_infinity(); // --> true</screen></entry>
 299           </row>
 300
 301           <row>
 302             <entry valign="top" morerows="1"><screen>bool is_neg_infinity() const</screen></entry>
 303             <entry>Returns true if local_date_time is negative infinity</entry>
 304           </row>
 305           <row>
 306             <entry><screen>local_date_time ldt(neg_infin);
 307 ldt.is_neg_infinity(); // --> true</screen></entry>
 308           </row>
 309
 310           <row>
 311             <entry valign="top" morerows="1"><screen>bool is_pos_infinity() const</screen></entry>
 312             <entry>Returns true if local_date_time is positive infinity</entry>
 313           </row>
 314           <row>
 315             <entry><screen>local_date_time ldt(neg_infin);
 316 ldt.is_pos_infinity(); // --> true</screen></entry>
 317           </row>
 318
 319           <row>
 320             <entry valign="top" morerows="1"><screen>bool is_not_a_date_time() const</screen></entry>
 321             <entry>Returns true if value is not a date</entry>
 322           </row>
 323           <row>
 324             <entry><screen>local_date_time ldt(not_a_date_time);
 325 ldt.is_not_a_date_time(); // --> true</screen></entry>
 326           </row>
 327
 328           <row>
 329             <entry valign="top" morerows="1"><screen>bool is_special() const</screen></entry>
 330             <entry>Returns true if local_date_time is any <code>special_value</code></entry>
 331           </row>
 332           <row>
 333             <entry><screen>local_date_time ldt(pos_infin);
 334 local_date_time ldt2(not_a_date_time);
 335 time_zone_ptr
 336   mst(new posix_time_zone("MST-07"));
 337 local_date_time
 338   ldt3(local_sec_clock::local_time(mst));
 339 ldt.is_special(); // --> true
 340 ldt2.is_special(); // --> true
 341 ldt3.is_special(); // --> false</screen></entry>
 342           </row>
 343
 344         </tbody>
 345       </tgroup>
 346     </informaltable>
 347   </para>
 348
 349   <anchor id="local_date_time_operators" />
 350   <bridgehead renderas="sect3">Operators</bridgehead>
 351   <informaltable frame="all">
 352     <tgroup cols="2">
 353       <thead>
 354         <row>
 355           <entry valign="top" morerows="1">Syntax</entry>
 356           <entry>Description</entry>
 357         </row>
 358         <row>
 359           <entry>Example</entry>
 360         </row>
 361       </thead>
 362       <tbody>
 363         <row>
 364           <entry valign="top" morerows="1"><screen>operator&lt;&lt;</screen></entry>
 365           <entry>Output streaming operator. This operator is part of the v1.33 IO addition to date_time. For complete details on this feature see <link linkend="date_time.date_time_io">Date Time IO</link>. The default output is shown in this example.</entry>
 366         </row>
 367         <row>
 368           <entry><screen>
 369 time_zone_ptr zone(new posix_time_zone("MST-07");
 370 local_date_time ldt(date(2005,Jul,4),
 371                     hours(20),
 372                     false);
 373 std::cout &lt;&lt; ldt &lt;&lt; std::endl;
 374 // "2005-Jul-04 20:00:00 MST"
 375           </screen></entry>
 376         </row>
 377
 378         <row>
 379           <entry valign="top" morerows="1"><screen>operator>></screen></entry>
 380           <entry>Input streaming operator. This operator is part of the v1.33 IO addition to date_time. For complete details on this feature see <link linkend="date_time.date_time_io">Date Time IO</link>. At this time, <code>local_date_time</code> objects can only be streamed in with a Posix Time Zone string. A complete description of a Posix Time Zone string can be found in the documentation for the <link linkend="posix_time_zone_intro">posix_time_zone</link> class.</entry>
 381         </row>
 382         <row>
 383           <entry><screen>stringstream ss;
 384 ss.str("2005-Jul-04 20:00:00 MST-07");
 385 ss >> ldt;
 386           </screen></entry>
 387         </row>
 388
 389         <row>
 390           <entry valign="top" morerows="1"><screen>operator==, operator!=,
 391 operator>, operator&lt;,
 392 operator>=, operator&lt;=</screen></entry>
 393           <entry>A full complement of comparison operators</entry>
 394         </row>
 395         <row>
 396           <entry><screen>ldt1 == ldt2, etc</screen></entry>
 397         </row>
 398
 399         <row>
 400           <entry valign="top" morerows="1"><screen>operator+, operator+=,
 401 operator-, operator-=</screen></entry>
 402           <entry>Addition, subtraction, and shortcut operators for <code>local_date_time</code> and date duration types. These include: <code>days</code>, <code>months</code>, and <code>years</code>.</entry>
 403         </row>
 404         <row>
 405           <entry><screen>ldt + days(5), etc</screen></entry>
 406         </row>
 407
 408         <row>
 409           <entry valign="top" morerows="1"><screen>operator+, operator+=,
 410 operator-, operator-=</screen></entry>
 411           <entry>Addition, subtraction, and shortcut operators for <code>local_date_time</code> and <code>time_duration</code>.</entry>
 412         </row>
 413         <row>
 414           <entry><screen>ldt + hours(5), etc</screen></entry>
 415         </row>
 416       </tbody>
 417     </tgroup>
 418   </informaltable>
 419
 420   <anchor id="local_date_time_tm_func" />
 421   <bridgehead renderas="sect3">Struct tm Functions</bridgehead>
 422   <para>Function for converting a <code>local_date_time</code> object to a <code>tm</code> struct is provided.</para>
 423   <informaltable frame="all">
 424     <tgroup cols="2">
 425       <thead>
 426         <row>
 427           <entry valign="top" morerows="1">Syntax</entry>
 428           <entry>Description</entry>
 429         </row>
 430         <row>
 431           <entry>Example</entry>
 432         </row>
 433       </thead>
 434       <tbody>
 435         <row>
 436           <entry valign="top" morerows="1"><screen>tm to_tm(local_date_time)</screen></entry>
 437           <entry>A function for converting a <code>local_date_time</code> object to a <code>tm</code> struct.</entry>
 438         </row>
 439         <row>
 440           <entry><screen>
 441 // 6am, 2005-Jul-05 local time
 442 std::string z("EST-05EDT,M4.1.0,M10.1.0");
 443 ptime pt(date(2005,Jul,5),
 444          hours(10));
 445 time_zone_ptr zone( new posix_time_zone(z));
 446 local_date_time ldt(pt, zone);
 447 tm ldt_tm = to_tm(ldt);
 448 /* tm_year => 105
 449    tm_mon  => 6
 450    tm_mday => 5
 451    tm_wday => 2 (Tuesday)
 452    tm_yday => 185
 453    tm_hour => 6
 454    tm_min  => 0
 455    tm_sec  => 0
 456    tm_isdst => 1 */</screen>
 457           </entry>
 458         </row>
 459
 460       </tbody>
 461     </tgroup>
 462   </informaltable>
 463 </section>