ceph/src/boost/libs/date_time/xmldoc/date_duration.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 xmlns:xi="http://www.w3.org/2001/XInclude" id="date_time.gregorian.date_duration">
  11   <title>Date Duration (aka Days)</title>
  12
  13   <link linkend="duration_intro">Introduction</link> --
  14   <link linkend="duration_header">Header</link> --
  15   <link linkend="duration_construction">Construction</link> --
  16   <link linkend="duration_accessors">Accessors</link> --
  17   <link linkend="duration_operators">Operators</link> --
  18   <link linkend="additional_duration_types">Additional Duration Types</link>
  19
  20   <anchor id="duration_intro" />
  21   <bridgehead renderas="sect3">Introduction</bridgehead>
  22   <para>
  23     The class boost::gregorian::date_duration is a simple day count used for arithmetic with <link linkend="date_time.gregorian.date_class">gregorian::date</link>. A duration can be either positive or negative.
  24   </para>
  25   <para>
  26     As of version 1_32 the date_duration class has been typedef'd as days in the boost::gregorian namespace. Throughout the examples you will find days used instead of date_duration.
  27   </para>
  28
  29   <anchor id="duration_header" />
  30   <bridgehead renderas="sect3">Header</bridgehead>
  31   <para>
  32     <programlisting>#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o
  33 or
  34 #include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types</programlisting>
  35   </para>
  36
  37   <anchor id="duration_construction" />
  38   <bridgehead renderas="sect3">Construction</bridgehead>
  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>date_duration(long)</screen></entry>
  53           <entry>Create a duration count.</entry>
  54         </row>
  55         <row>
  56           <entry><screen>date_duration dd(3); //3 days</screen></entry>
  57         </row>
  58
  59         <row>
  60           <entry valign="top" morerows="1"><screen>days(special_values sv)</screen></entry>
  61           <entry>Constructor for infinities, not-a-date-time, max_date_time, and min_date_time</entry>
  62         </row>
  63         <row>
  64           <entry><screen>days dd1(neg_infin);
  65 days dd2(pos_infin);
  66 days dd3(not_a_date_time);
  67 days dd4(max_date_time);
  68 days dd5(min_date_time);</screen></entry>
  69         </row>
  70
  71       </tbody>
  72     </tgroup>
  73   </informaltable>
  74
  75   <anchor id="duration_accessors" />
  76   <bridgehead renderas="sect3">Accessors</bridgehead>
  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>long days() const</screen></entry>
  91           <entry>Get the day count.</entry>
  92         </row>
  93         <row>
  94           <entry><screen>date_duration dd(3); dd.days() --> 3</screen></entry>
  95         </row>
  96
  97         <row>
  98           <entry valign="top" morerows="1"><screen>bool is_negative() const</screen></entry>
  99           <entry>True if number of days is less than zero.</entry>
 100         </row>
 101         <row>
 102           <entry><screen>date_duration dd(-1); dd.is_negative() --> true</screen></entry>
 103         </row>
 104
 105         <row>
 106           <entry valign="top" morerows="1"><screen>static date_duration unit()</screen></entry>
 107           <entry>Return smallest possible unit of duration type.</entry>
 108         </row>
 109         <row>
 110           <entry><screen>date_duration::unit() --> date_duration(1)</screen></entry>
 111         </row>
 112
 113         <row>
 114           <entry valign="top" morerows="1"><screen>bool is_special() const</screen></entry>
 115           <entry>Returns true if days is any <code>special_value</code></entry>
 116         </row>
 117         <row>
 118           <entry><screen>days dd(pos_infin);
 119 days dd2(not_a_date_time);
 120 days dd3(25);
 121 dd.is_special(); // --> true
 122 dd2.is_special(); // --> true
 123 dd3.is_special(); // --> false</screen></entry>
 124         </row>
 125
 126       </tbody>
 127     </tgroup>
 128   </informaltable>
 129
 130   <anchor id="duration_operators" />
 131   <bridgehead renderas="sect3">Operators</bridgehead>
 132   <informaltable frame="all">
 133     <tgroup cols="2">
 134       <thead>
 135         <row>
 136           <entry valign="top" morerows="1">Syntax</entry>
 137           <entry>Description</entry>
 138         </row>
 139         <row>
 140           <entry>Example</entry>
 141         </row>
 142       </thead>
 143       <tbody>
 144         <row>
 145           <entry valign="top" morerows="1"><screen>operator&lt;&lt;, operator&gt;&gt;</screen></entry>
 146           <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>
 147         </row>
 148         <row>
 149           <entry><screen>date d(not_a_date_time);
 150 stringstream ss("2002-Jan-01");
 151 ss &gt;&gt; d;
 152 std::cout &lt;&lt; d; // "2002-Jan-01"
 153 </screen>
 154           </entry>
 155         </row>
 156
 157         <row>
 158           <entry valign="top" morerows="1"><screen>operator==, operator!=,
 159 operator>, operator&lt;,
 160 operator>=, operator&lt;=</screen>
 161           </entry>
 162           <entry>A full complement of comparison operators</entry>
 163         </row>
 164         <row>
 165           <entry><screen>dd1 == dd2, etc</screen></entry>
 166         </row>
 167
 168         <row>
 169           <entry valign="top" morerows="1"><screen>date_duration operator+(date_duration) const</screen></entry>
 170           <entry>Add date durations.</entry>
 171         </row>
 172         <row>
 173           <entry><screen>date_duration dd1(3);
 174 date_duration dd2(5);
 175 date_duration dd3 = dd1 + dd2;</screen>
 176           </entry>
 177         </row>
 178
 179         <row>
 180           <entry valign="top" morerows="1"><screen>date_duration operator-(date_duration) const</screen></entry>
 181           <entry>Subtract durations.</entry>
 182         </row>
 183         <row>
 184           <entry><screen>date_duration dd1(3);
 185 date_duration dd2(5);
 186 date_duration dd3 = dd1 - dd2;</screen>
 187           </entry>
 188         </row>
 189       </tbody>
 190     </tgroup>
 191   </informaltable>
 192
 193   <anchor id="additional_duration_types" />
 194   <bridgehead renderas="sect3">Additional Duration Types</bridgehead>
 195   <para>These additional types are logical representations of spans of days.</para>
 196   <informaltable frame="all">
 197     <tgroup cols="2">
 198       <thead>
 199         <row>
 200           <entry valign="top" morerows="1">Syntax</entry>
 201           <entry>Description</entry>
 202         </row>
 203         <row>
 204           <entry>Example</entry>
 205         </row>
 206       </thead>
 207       <tbody>
 208         <row>
 209           <entry valign="top" morerows="1"><screen>months(int num_of_months)</screen></entry>
 210           <entry>A logical month representation. Depending on the usage, this <code>months</code> object may cover a span of 28 to 31 days. The objects also use a snap to end-of-month behavior when used in conjunction with a date that is the last day of a given month. <emphasis role="strong">WARNING: this behavior may lead to unexpected results.</emphasis> See: <link linkend="snap_to_details">Reversibility of Operations Pitfall</link> for complete details and alternatives.</entry>
 211         </row>
 212         <row>
 213           <entry><screen>months single(1);
 214 date leap_year(2004,Jan,31);
 215 date norm_year(2005,Jan,31);
 216 leap_year + single; // => 2004-Feb-29
 217 norm_year + single; // => 2005-Feb-28
 218 date(2005,Jan,1) + single; // => 2005-Feb-01
 219 date(2005,Feb,1) + single; // => 2005-Mar-01
 220 date(2005,Feb,28) + single; // => 2005-Mar-31</screen></entry>
 221         </row>
 222
 223         <row>
 224           <entry valign="top" morerows="1"><screen>years(int num_of_years)</screen></entry>
 225           <entry>A logical representation of a year. The <code>years</code> object has the same behavior as the <code>months</code> objects with regards to the end-of-the-month.</entry>
 226         </row>
 227         <row>
 228           <entry><screen>years single(1);
 229 date(2003,Feb,28) + single;
 230 // results in => 2004-Feb-29
 231 date(2004,Feb,29) + single;
 232 // results in => 2005-Feb-28</screen></entry>
 233         </row>
 234
 235         <row>
 236           <entry valign="top" morerows="1"><screen>weeks(int num_of_weeks)</screen></entry>
 237           <entry>A duration type representing a number of <code>n * 7</code> days.</entry>
 238         </row>
 239         <row>
 240           <entry><screen>weeks single(1);
 241 date(2005,Jan,1) + single; // => 2005-Jan-08</screen></entry>
 242         </row>
 243
 244       </tbody>
 245     </tgroup>
 246   </informaltable>
 247
 248   <xi:include href="snap_to_details.xml"/>
 249
 250 </section>