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 33or 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); 65days dd2(pos_infin); 66days dd3(not_a_date_time); 67days dd4(max_date_time); 68days 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); 119days dd2(not_a_date_time); 120days dd3(25); 121dd.is_special(); // --> true 122dd2.is_special(); // --> true 123dd3.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<<, operator>></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); 150stringstream ss("2002-Jan-01"); 151ss >> d; 152std::cout << d; // "2002-Jan-01" 153</screen> 154 </entry> 155 </row> 156 157 <row> 158 <entry valign="top" morerows="1"><screen>operator==, operator!=, 159operator>, operator<, 160operator>=, operator<=</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); 174date_duration dd2(5); 175date_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); 185date_duration dd2(5); 186date_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); 214date leap_year(2004,Jan,31); 215date norm_year(2005,Jan,31); 216leap_year + single; // => 2004-Feb-29 217norm_year + single; // => 2005-Feb-28 218date(2005,Jan,1) + single; // => 2005-Feb-01 219date(2005,Feb,1) + single; // => 2005-Mar-01 220date(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); 229date(2003,Feb,28) + single; 230// results in => 2004-Feb-29 231date(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); 241date(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> 251