ceph/src/boost/libs/date_time/xmldoc/local_time_period.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_time_period">
  11   <title>Local Time Period</title>
  12
  13   <link linkend="local_time_period_intro">Introduction</link> --
  14   <link linkend="local_time_period_header">Header</link> --
  15   <link linkend="local_time_period_constr">Construction</link> --
  16   <link linkend="local_time_period_accessors">Accessors</link> --
  17   <link linkend="local_time_period_operators">Operators</link>
  18
  19   <anchor id="local_time_period_intro" />
  20   <bridgehead renderas="sect3">Introduction</bridgehead>
  21   <para>
  22     The class <code>boost::local_time::local_time_period</code> provides direct representation for ranges between two local times. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program.
  23   </para>
  24   <para>
  25     A period that is created with beginning and end points being equal, or with a duration of zero, is known as a zero length period. Zero length periods are considered invalid (it is perfectly legal to construct an invalid period). For these periods, the <code>last</code> point will always be one unit less that the <code>begin</code> point.
  26   </para>
  27
  28   <anchor id="local_time_period_header" />
  29   <bridgehead renderas="sect3">Header</bridgehead>
  30   <para>
  31     <programlisting>#include "boost/date_time/local_time/local_time.hpp" //include all types plus i/o
  32 or
  33 #include "boost/date_time/local_time/local_time_types.hpp" //no i/o just types</programlisting>
  34   </para>
  35
  36   <anchor id="local_time_period_constr" />
  37   <bridgehead renderas="sect3">Construction</bridgehead>
  38   <para>
  39     <informaltable frame="all">
  40       <tgroup cols="2">
  41         <thead>
  42           <row>
  43             <entry valign="top" morerows="1">Syntax</entry>
  44             <entry>Description</entry>
  45           </row>
  46           <row>
  47             <entry>Example</entry>
  48           </row>
  49         </thead>
  50         <tbody>
  51           <row>
  52             <entry valign="top" morerows="1"><screen>local_time_period(...)
  53   Parameters:
  54     local_date_time beginning
  55     local_date_time end</screen></entry>
  56             <entry> Create a period as [begin, end). If end is &lt;= begin then the period will be defined as invalid.</entry>
  57           </row>
  58           <row>
  59             <entry><screen>time_zone_ptr
  60   zone(new posix_time_zone("MST-07"));
  61 local_date_time
  62   beg(ptime(date(2005,Jan,1),hours(0)), zone);
  63 local_date_time
  64   end(ptime(date(2005,Feb,1),hours(0)), zone);
  65 // period for the entire month of Jan 2005
  66 local_time_period ltp(beg, end);</screen>
  67             </entry>
  68           </row>
  69
  70           <row>
  71             <entry valign="top" morerows="1"><screen>local_time_period(...)
  72   Parameters:
  73     local_date_time beginning
  74     time_duration length</screen></entry>
  75             <entry>Create a period as [begin, begin+len) where end would be begin+len. If len is &lt;= zero then the period will be defined as invalid.</entry>
  76           </row>
  77           <row>
  78             <entry><screen>time_zone_ptr
  79   zone(new posix_time_zone("MST-07"));
  80 local_date_time
  81   beg(ptime(date(2005,Jan,1),hours(0)), zone);
  82 // period for the whole day of 2005-Jan-01
  83 local_time_period ltp(beg, hours(24));</screen>
  84             </entry>
  85           </row>
  86
  87           <row>
  88             <entry valign="top" morerows="1"><screen>local_time_period(local_time_period rhs)</screen></entry>
  89             <entry>Copy constructor</entry>
  90           </row>
  91           <row>
  92             <entry><screen>local_time_period ltp1(ltp);</screen></entry>
  93           </row>
  94         </tbody>
  95       </tgroup>
  96     </informaltable>
  97   </para>
  98
  99
 100   <anchor id="local_time_period_accessors" />
 101   <bridgehead renderas="sect3">Accessors</bridgehead>
 102   <para>
 103     <informaltable frame="all">
 104       <tgroup cols="2">
 105         <thead>
 106           <row>
 107             <entry valign="top" morerows="1">Syntax</entry>
 108             <entry>Description</entry>
 109           </row>
 110           <row>
 111             <entry>Example</entry>
 112           </row>
 113         </thead>
 114         <tbody>
 115           <row>
 116             <entry valign="top" morerows="1"><screen>local_date_time begin()</screen></entry>
 117             <entry>Return first local_date_time of the period.</entry>
 118           </row>
 119           <row>
 120             <entry><screen>time_zone_ptr
 121   zone(new posix_time_zone("MST-07"));
 122 local_date_time
 123   ldt((ptime(date(2005,Jan,1)),hours(0)), zone);
 124 local_time_period ltp(ldt, hours(2));
 125 ltp.begin(); // => 2005-Jan-01 00:00:00</screen>
 126             </entry>
 127           </row>
 128
 129           <row>
 130             <entry valign="top" morerows="1"><screen>local_date_time last()</screen></entry>
 131             <entry>Return last local_date_time in the period</entry>
 132           </row>
 133           <row>
 134             <entry><screen>time_zone_ptr
 135   zone(new posix_time_zone("MST-07"));
 136 local_date_time
 137   ldt((ptime(date(2005,Jan,1),hours(0))), zone);
 138 local_time_period ltp(ldt, hours(2));
 139 ltp.last(); // => 2005-Jan-01 01:59:59.999999999</screen>
 140             </entry>
 141           </row>
 142
 143           <row>
 144             <entry valign="top" morerows="1"><screen>local_date_time end()</screen></entry>
 145             <entry>Return one past the last in period</entry>
 146           </row>
 147           <row>
 148             <entry><screen>time_zone_ptr
 149   zone(new posix_time_zone("MST-07"));
 150 local_date_time
 151   ldt((ptime(date(2005,Jan,1),hours(0))), zone);
 152 local_time_period ltp(ldt, hours(2));
 153 ltp.end(); // => 2005-Jan-01 02:00:00</screen>
 154             </entry>
 155           </row>
 156
 157           <row>
 158             <entry valign="top" morerows="1"><screen>time_duration length()</screen></entry>
 159             <entry>Return the length of the local_time period.</entry>
 160           </row>
 161           <row>
 162             <entry><screen>time_zone_ptr
 163   zone(new posix_time_zone("MST-07"));
 164 local_date_time
 165   ldt((ptime(date(2005,Jan,1),hours(0))), zone);
 166 local_time_period ltp(ldt, hours(2));
 167 ltp.length(); // => 02:00:00</screen>
 168             </entry>
 169           </row>
 170
 171           <row>
 172             <entry valign="top" morerows="1"><screen>bool is_null()</screen></entry>
 173             <entry>True if period is not well formed. eg: end less than or equal to begin.</entry>
 174           </row>
 175           <row>
 176             <entry><screen>time_zone_ptr
 177   zone(new posix_time_zone("MST-07"));
 178 local_date_time
 179   beg((ptime(date(2005,Feb,1),hours(0))), zone);
 180 local_date_time
 181   end((ptime(date(2005,Jan,1),hours(0))), zone);
 182 local_time_period ltp(beg, end);
 183 ltp.is_null(); // => true</screen>
 184             </entry>
 185           </row>
 186
 187           <row>
 188             <entry valign="top" morerows="1"><screen>bool contains(local_date_time)</screen></entry>
 189             <entry>True if local_date_time is within the period. Zero length periods cannot contain any points</entry>
 190           </row>
 191           <row>
 192             <entry><screen>time_zone_ptr
 193   zone(new posix_time_zone("MST-07"));
 194 local_date_time
 195   beg((ptime(date(2005,Jan,1),hours(0))), zone);
 196 local_date_time
 197   end((ptime(date(2005,Feb,1),hours(0))), zone);
 198 local_time_period jan_mst(beg, end);
 199
 200 local_date_time
 201 ldt((ptime(date(2005,Jan,15),hours(12))), zone);
 202 jan_mst.contains(ldt); // => true
 203
 204 local_time_period zero(beg, beg);
 205 zero.contains(beg); // false</screen></entry>
 206           </row>
 207
 208           <row>
 209             <entry valign="top" morerows="1"><screen>bool contains(local_time_period)</screen></entry>
 210             <entry>True if period is within the period</entry>
 211           </row>
 212           <row>
 213             <entry><screen>// using jan_mst period from previous example
 214
 215 local_date_time
 216   beg((ptime(date(2005,Jan,7),hours(0))), zone);
 217 local_time_period ltp(beg, hours(24));
 218
 219 jan_mst.contains(ltp); // => true</screen></entry>
 220           </row>
 221
 222           <row>
 223             <entry valign="top" morerows="1"><screen>bool intersects(local_time_period)</screen></entry>
 224             <entry> True if periods overlap</entry>
 225           </row>
 226           <row>
 227             <entry><screen>// using jan_mst period from previous example
 228
 229 local_date_time
 230   beg((ptime(date(2005,Jan,7),hours(0))), zone);
 231 local_date_time
 232   end((ptime(date(2005,Feb,7),hours(0))), zone);
 233 local_time_period ltp(beg, end);
 234
 235 jan_mst.intersects(ltp); // => true</screen></entry>
 236           </row>
 237
 238           <row>
 239             <entry valign="top" morerows="1"><screen>local_time_period intersection(local_time_period)</screen></entry>
 240             <entry>Calculate the intersection of 2 periods. Null if no intersection.</entry>
 241           </row>
 242           <row>
 243             <entry><screen>// using jan_mst period from previous example
 244
 245 local_date_time
 246   beg((ptime(date(2005,Jan,7),hours(0))), zone);
 247 local_date_time
 248   end((ptime(date(2005,Feb,7),hours(0))), zone);
 249 local_time_period ltp(beg, end);
 250
 251 local_time_period res(jan_mst.intersection(ltp));
 252 // res => 2005-Jan-07 00:00:00 through
 253 // 2005-Jan-31 23:59:59.999999999 (inclusive)</screen></entry>
 254           </row>
 255
 256           <row>
 257             <entry valign="top" morerows="1"><screen>local_time_period merge(local_time_period)</screen></entry>
 258             <entry>Returns union of two periods. Null if no intersection.</entry>
 259           </row>
 260           <row>
 261             <entry><screen>// using jan_mst period from previous example
 262
 263 local_date_time
 264   beg((ptime(date(2005,Jan,7),hours(0))), zone);
 265 local_date_time
 266   end((ptime(date(2005,Feb,7),hours(0))), zone);
 267 local_time_period ltp(beg, end);
 268
 269 local_time_period res(jan_mst.merge(ltp));
 270 // res => 2005-Jan-07 00:00:00 through
 271 // 2005-Feb-06 23:59:59.999999999 (inclusive)</screen></entry>
 272           </row>
 273
 274           <row>
 275             <entry valign="top" morerows="1"><screen>local_time_period span(local_time_period)</screen></entry>
 276             <entry>Combines two periods and any gap between them such that begin = min(p1.begin, p2.begin) and end = max(p1.end , p2.end).</entry>
 277           </row>
 278           <row>
 279             <entry><screen>// using jan_mst period from previous example
 280
 281 local_date_time
 282   beg((ptime(date(2005,Mar,1),hours(0))), zone);
 283 local_date_time
 284   end((ptime(date(2005,Apr,1),hours(0))), zone);
 285 local_time_period mar_mst(beg, end);
 286
 287 local_time_period res(jan_mst.span(mar_mst));
 288 // res => 2005-Jan-01 00:00:00 through
 289 // 2005-Mar-31 23:59:59.999999999 (inclusive)</screen></entry>
 290           </row>
 291
 292           <row>
 293             <entry valign="top" morerows="1"><screen>void shift(time_duration)</screen></entry>
 294             <entry>Add duration to both begin and end.</entry>
 295           </row>
 296           <row>
 297             <entry><screen>local_date_time
 298   beg((ptime(date(2005,Mar,1),hours(0))), zone);
 299 local_date_time
 300   end((ptime(date(2005,Apr,1),hours(0))), zone);
 301 local_time_period mar_mst(beg, end);
 302
 303 mar_mst.shift(hours(48));
 304 // mar_mst => 2005-Mar-03 00:00:00 through
 305 // 2005-Apr-02 23:59:59.999999999 (inclusive)</screen></entry>
 306           </row>
 307         </tbody>
 308       </tgroup>
 309     </informaltable>
 310   </para>
 311
 312
 313   <anchor id="local_time_period_operators" />
 314   <bridgehead renderas="sect3">Operators</bridgehead>
 315   <para>
 316     <informaltable frame="all">
 317       <tgroup cols="2">
 318         <thead>
 319           <row>
 320             <entry valign="top" morerows="1">Syntax</entry>
 321             <entry>Description</entry>
 322           </row>
 323           <row>
 324             <entry>Example</entry>
 325           </row>
 326         </thead>
 327         <tbody>
 328           <!-- TODO: the streaming operators have not bee changed from time_period to local_time_period
 329           <row>
 330             <entry valign="top" morerows="1"><screen>operator&lt;&lt;</screen></entry>
 331             <entry>Output streaming operator for time duration. Uses facet to output [date time_of_day/date time_of_day]. The default is format is <code>[YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff]</code> string where <code>mmm</code> is 3 char month name and the fractional seconds are left out when zero.</entry>
 332           </row>
 333           <row>
 334             <entry><screen>[2002-Jan-01 01:25:10.000000001/ \
 335     2002-Jan-31 01:25:10.123456789]</screen></entry>
 336           </row>
 337
 338           <row>
 339             <entry valign="top" morerows="1"><screen>operator&gt;&gt;</screen></entry>
 340             <entry>Input streaming operator for time duration. Uses facet to read [date time_of_day/date time_of_day]. The default is format is <code>[YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff]</code> string where <code>mmm</code> is 3 char month name and the fractional seconds are left out when zero.</entry>
 341           </row>
 342           <row>
 343             <entry><screen>[2002-Jan-01 01:25:10.000000001/ \
 344     2002-Jan-31 01:25:10.123456789]</screen></entry>
 345           </row>
 346           -->
 347           <row>
 348             <entry valign="top" morerows="1"><screen>operator==, operator!=</screen></entry>
 349             <entry>Equality operators. Periods are equal if ltp1.begin == ltp2.begin &amp;&amp; ltp1.last == ltp2.last</entry>
 350           </row>
 351           <row>
 352             <entry><screen>if (ltp1 == ltp2) {...</screen></entry>
 353           </row>
 354
 355           <row>
 356             <entry valign="top" morerows="1"><screen>operator&lt;</screen></entry>
 357             <entry>Ordering with no overlap. True if ltp1.end() less than ltp2.begin()</entry>
 358           </row>
 359           <row>
 360             <entry><screen>if (ltp1 &lt; ltp2) {...</screen></entry>
 361           </row>
 362
 363           <row>
 364             <entry valign="top" morerows="1"><screen>operator&gt;</screen></entry>
 365             <entry>Ordering with no overlap. True if ltp1.begin() greater than ltp2.end()</entry>
 366           </row>
 367           <row>
 368             <entry><screen>if (ltp1 > ltp2) {... etc</screen></entry>
 369           </row>
 370
 371           <row>
 372             <entry valign="top" morerows="1"><screen>operator&lt;=, operator&gt;=</screen></entry>
 373             <entry>Defined in terms of the other operators.</entry>
 374           </row>
 375           <row>
 376             <entry></entry>
 377           </row>
 378         </tbody>
 379       </tgroup>
 380     </informaltable>
 381   </para>
 382
 383 </section>