1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Gregorian</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../date_time.html" title="Chapter 13. Boost.Date_Time"> 10<link rel="prev" href="examples/general_usage_examples.html" title="General Usage Examples"> 11<link rel="next" href="posix_time.html" title="Posix Time"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="examples/general_usage_examples.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../date_time.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="posix_time.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="date_time.gregorian"></a>Gregorian</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="gregorian.html#date_time.gregorian.date_class">Date</a></span></dt> 31<dt><span class="section"><a href="gregorian.html#date_time.gregorian.date_duration">Date Duration (aka Days)</a></span></dt> 32<dt><span class="section"><a href="gregorian.html#date_time.gregorian.date_period">Date Period</a></span></dt> 33<dt><span class="section"><a href="gregorian.html#date_time.gregorian.date_iterators">Date Iterators</a></span></dt> 34<dt><span class="section"><a href="gregorian.html#date_time.gregorian.date_algorithms">Date Generators/Algorithms</a></span></dt> 35<dt><span class="section"><a href="gregorian.html#date_time.gregorian.gregorian_calendar">Gregorian Calendar</a></span></dt> 36</dl></div> 37<h3> 38<a name="id-1.3.14.8.2"></a>Gregorian Date System</h3> 39<p> 40 <a class="link" href="gregorian.html#greg_intro">Introduction</a> -- 41 <a class="link" href="gregorian.html#greg_ex">Usage Examples</a> 42 </p> 43<a name="greg_intro"></a><h4> 44<a name="id-1.3.14.8.5"></a>Introduction</h4> 45<p>The gregorian date system provides a date programming system based the Gregorian Calendar. The first introduction of the Gregorian calendar was in 1582 to fix an error in the Julian Calendar. However, many local jurisdictions did not adopt this change until much later. Thus there is potential confusion with historical dates. 46 </p> 47<p>The implemented calendar is a "proleptic Gregorian calendar" which extends dates back prior to the Gregorian Calendar's first adoption in 1582. The current implementation supports dates in the range 1400-Jan-01 to 9999-Dec-31. Many references will represent dates prior to 1582 using the Julian Calendar, so caution is in order if accurate calculations are required on historic dates. See <a href="http://emr.cs.iit.edu/home/reingold/calendar-book/second-edition" target="_top">Calendrical Calculations</a> by Reingold & Dershowitz for more details. Date information from Calendrical Calculations has been used to cross-test the correctness of the Gregorian calendar implementation. 48 </p> 49<p>All types for the gregorian system are found in namespace boost::gregorian. The library supports a convenience header boost/date_time/gregorian/gregorian_types.hpp that will include all the classes of the library with no input/output dependency. Another header boost/date_time/gregorian/gregorian.hpp will include the types and the input/output code. 50 </p> 51<p>The class <a class="link" href="gregorian.html#date_time.gregorian.date_class" title="Date">boost::gregorian::date</a> is the primary temporal type for users. If you are interested in learning about writing programs that do specialized date calculations such as finding the "first sunday in april" see the date <a class="link" href="gregorian.html#date_time.gregorian.date_algorithms" title="Date Generators/Algorithms">generators and algorithms page</a>. 52 </p> 53<a name="greg_ex"></a><h4> 54<a name="id-1.3.14.8.11"></a>Usage Examples</h4> 55<p> 56 </p> 57<div class="informaltable"><table class="table"> 58<colgroup> 59<col> 60<col> 61</colgroup> 62<thead><tr> 63<th>Example</th> 64<th>Description</th> 65</tr></thead> 66<tbody> 67<tr> 68<td valign="top"><div class="literallayout"><p><br> 69<a class="link" href="examples.html#date_time.examples.days_alive" title="Days Alive">Days Alive</a> <br> 70<a class="link" href="examples.html#date_time.examples.days_between_new_year" title="Days Between New Years">Days Between New Years</a></p></div></td> 71<td>Simple date arithmetic. Retrieve current day from clock.</td> 72</tr> 73<tr> 74<td valign="top"><div class="literallayout"><p><a class="link" href="examples.html#date_time.examples.dates_as_strings" title="Dates as Strings">Dates as strings</a></p></div></td> 75<td>Simple parsing and formatting of dates from/to strings</td> 76</tr> 77<tr> 78<td valign="top"><div class="literallayout"><p><a class="link" href="examples.html#date_time.examples.date_period_calc" title="Date Period Calculations">Date Period Calculations</a></p></div></td> 79<td>See if a date is in a set of date periods (eg: is it a holiday/weekend)</td> 80</tr> 81<tr> 82<td valign="top"><div class="literallayout"><p><a class="link" href="examples.html#date_time.examples.print_month" title="Print Month">Print a month</a></p></div></td> 83<td>Small utility program which prints out all the days in a month from command line. Need to know if 1999-Jan-1 was a Friday or a Saturday? This program shows how to do it.</td> 84</tr> 85<tr> 86<td valign="top"><div class="literallayout"><p><a class="link" href="examples.html#date_time.examples.print_holidays" title="Print Holidays">Print Holidays</a></p></div></td> 87<td>Uses date generators to convert abstract specification into concrete set of dates.</td> 88</tr> 89</tbody> 90</table></div> 91<p> 92 </p> 93<div class="section"> 94<div class="titlepage"><div><div><h3 class="title"> 95<a name="date_time.gregorian.date_class"></a>Date</h3></div></div></div> 96<a class="link" href="gregorian.html#date_intro">Introduction</a> -- 97 <a class="link" href="gregorian.html#date_header">Header</a> -- 98 <a class="link" href="gregorian.html#date_construction">Construction</a> -- 99 <a class="link" href="gregorian.html#date_construct_from_string">Construct from String</a> -- 100 <a class="link" href="gregorian.html#date_construct_from_clock">Construct from Clock</a> -- 101 <a class="link" href="gregorian.html#date_accessors">Accessors</a> -- 102 <a class="link" href="gregorian.html#date_convert_to_string">Convert to String</a> -- 103 <a class="link" href="gregorian.html#date_operators">Operators</a> -- 104 <a class="link" href="gregorian.html#date_tm_funcs">Struct tm Functions</a><a name="date_intro"></a><h4> 105<a name="id-1.3.14.8.13.12"></a>Introduction</h4> 106<p> 107 The class boost::gregorian::date is the primary interface for date programming. In general, 108 the date class is immutable once constructed although it does allow assignment from another 109 date. 110 Techniques for creating dates include reading the 111 <a class="link" href="gregorian.html#date_construct_from_clock">current date from the clock</a>, 112 using <a class="link" href="gregorian.html#date_time.gregorian.date_iterators" title="Date Iterators">date iterators</a>, and 113 <a class="link" href="gregorian.html#date_time.gregorian.date_algorithms" title="Date Generators/Algorithms">date algorithms or generators</a>. 114 </p> 115<p> 116 Internally boost::gregorian::date is stored as a 32 bit integer type. The class is specifically 117 designed to NOT contain virtual functions. This design allows for efficient 118 calculation and memory usage with large collections of dates. 119 </p> 120<p> 121 The construction of a date validates all input so that it is not possible to 122 construct an 'invalid' date. That is 2001-Feb-29 cannot be constructed as a date. 123 Various exceptions derived from std::out_of_range are thrown to indicate which aspect 124 of the date input is invalid. Note that the 125 special value not-a-date-time can be used as 'invalid' or 'null' date if so desired. 126 </p> 127<a name="date_header"></a><h4> 128<a name="id-1.3.14.8.13.17"></a>Header</h4> 129<p> 130 </p> 131<pre class="programlisting">#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o 132or 133#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types</pre> 134<p> 135 </p> 136<a name="date_construction"></a><h4> 137<a name="id-1.3.14.8.13.20"></a>Construction</h4> 138<div class="informaltable"><table class="table"> 139<colgroup> 140<col> 141<col> 142</colgroup> 143<thead> 144<tr> 145<th rowspan="2" valign="top">Syntax</th> 146<th>Description</th> 147</tr> 148<tr><th>Example</th></tr> 149</thead> 150<tbody> 151<tr> 152<td rowspan="2" valign="top"><pre class="screen">date(greg_year, greg_month, greg_day)</pre></td> 153<td>Construct from parts of date. Throws bad_year, bad_day_of_month, or bad_day_month (derivatives of std::out_of_range) if the year, month or day are out of range.</td> 154</tr> 155<tr><td><pre class="screen">date d(2002,Jan,10);</pre></td></tr> 156<tr> 157<td rowspan="2" valign="top"><pre class="screen">date(date d)</pre></td> 158<td>Copy constructor</td> 159</tr> 160<tr><td><pre class="screen">date d1(d);</pre></td></tr> 161<tr> 162<td rowspan="2" valign="top"><pre class="screen">date(special_values sv)</pre></td> 163<td>Constructor for infinities, not-a-date-time, max_date_time, and min_date_time</td> 164</tr> 165<tr><td><pre class="screen">date d1(neg_infin); 166date d2(pos_infin); 167date d3(not_a_date_time); 168date d4(max_date_time); 169date d5(min_date_time);</pre></td></tr> 170<tr> 171<td rowspan="2" valign="top"><pre class="screen">date()</pre></td> 172<td>Default constructor. Creates a date object initialized to not_a_date_time. NOTE: this constructor can be disabled by defining DATE_TIME_NO_DEFAULT_CONSTRUCTOR (see compiler_config.hpp)</td> 173</tr> 174<tr><td><pre class="screen">date d; // d => not_a_date_time</pre></td></tr> 175</tbody> 176</table></div> 177<a name="date_construct_from_string"></a><h4> 178<a name="id-1.3.14.8.13.23"></a>Construct from String</h4> 179<div class="informaltable"><table class="table"> 180<colgroup> 181<col> 182<col> 183</colgroup> 184<thead> 185<tr> 186<th rowspan="2" valign="top">Syntax</th> 187<th>Description</th> 188</tr> 189<tr><th>Example</th></tr> 190</thead> 191<tbody> 192<tr> 193<td rowspan="2" valign="top"><pre class="screen">date from_string(std::string)</pre></td> 194<td>From delimited date string where with order year-month-day eg: 2002-1-25</td> 195</tr> 196<tr><td><pre class="screen">std::string ds("2002/1/25"); 197date d(from_string(ds));</pre></td></tr> 198<tr> 199<td rowspan="2" valign="top"><pre class="screen">date from_undelimited_string(std::string)</pre></td> 200<td>From iso type date string where with order year-month-day eg: 20020125</td> 201</tr> 202<tr><td><pre class="screen">std::string ds("20020125"); 203date d(from_undelimited_string(ds));</pre></td></tr> 204</tbody> 205</table></div> 206<a name="date_construct_from_clock"></a><h4> 207<a name="id-1.3.14.8.13.26"></a>Construct from Clock</h4> 208<div class="informaltable"><table class="table"> 209<colgroup> 210<col> 211<col> 212</colgroup> 213<thead> 214<tr> 215<th rowspan="2" valign="top">Syntax</th> 216<th>Description</th> 217</tr> 218<tr><th>Example</th></tr> 219</thead> 220<tbody> 221<tr> 222<td rowspan="2" valign="top"><pre class="screen">day_clock::local_day()</pre></td> 223<td>Get the local day based on the time zone settings of the computer.</td> 224</tr> 225<tr><td><pre class="screen">date d(day_clock::local_day());</pre></td></tr> 226<tr> 227<td rowspan="2" valign="top"><pre class="screen">day_clock::universal_day()</pre></td> 228<td>Get the UTC day.</td> 229</tr> 230<tr><td><pre class="screen">date d(day_clock::universal_day());</pre></td></tr> 231</tbody> 232</table></div> 233<a name="date_accessors"></a><h4> 234<a name="id-1.3.14.8.13.29"></a>Accessors</h4> 235<div class="informaltable"><table class="table"> 236<colgroup> 237<col> 238<col> 239</colgroup> 240<thead> 241<tr> 242<th rowspan="2" valign="top">Syntax</th> 243<th>Description</th> 244</tr> 245<tr><th>Example</th></tr> 246</thead> 247<tbody> 248<tr> 249<td rowspan="2" valign="top"><pre class="screen">greg_year year() const</pre></td> 250<td>Get the year part of the date.</td> 251</tr> 252<tr><td><pre class="screen">date d(2002,Jan,10); 253d.year(); // --> 2002</pre></td></tr> 254<tr> 255<td rowspan="2" valign="top"><pre class="screen">greg_month month() const</pre></td> 256<td>Get the month part of the date.</td> 257</tr> 258<tr><td><pre class="screen">date d(2002,Jan,10); 259d.month(); // --> 1</pre></td></tr> 260<tr> 261<td rowspan="2" valign="top"><pre class="screen">greg_day day() const</pre></td> 262<td> Get the day part of the date.</td> 263</tr> 264<tr><td><pre class="screen">date d(2002,Jan,10); 265d.day(); // --> 10</pre></td></tr> 266<tr> 267<td rowspan="2" valign="top"><pre class="screen">greg_ymd year_month_day() const</pre></td> 268<td>Return a year_month_day struct. More efficient when all 3 parts of the date are needed.</td> 269</tr> 270<tr><td><pre class="screen">date d(2002,Jan,10); 271date::ymd_type ymd = d.year_month_day(); 272// ymd.year --> 2002, 273// ymd.month --> 1, 274// ymd.day --> 10</pre></td></tr> 275<tr> 276<td rowspan="2" valign="top"><pre class="screen">greg_day_of_week day_of_week() const</pre></td> 277<td>Get the day of the week (Sunday, Monday, etc.)</td> 278</tr> 279<tr><td><pre class="screen">date d(2002,Jan,10); 280d.day_of_week(); // --> Thursday</pre></td></tr> 281<tr> 282<td rowspan="2" valign="top"><pre class="screen">greg_day_of_year day_of_year() const</pre></td> 283<td>Get the day of the year. Number from 1 to 366 </td> 284</tr> 285<tr><td><pre class="screen">date d(2000,Jan,10); 286d.day_of_year(); // --> 10</pre></td></tr> 287<tr> 288<td rowspan="2" valign="top"><pre class="screen">date end_of_month() const</pre></td> 289<td>Returns a <code class="computeroutput">date</code> object set to the last day of the calling objects current month.</td> 290</tr> 291<tr><td><pre class="screen">date d(2000,Jan,10); 292d.end_of_month(); // --> 2000-Jan-31</pre></td></tr> 293<tr> 294<td rowspan="2" valign="top"><pre class="screen">bool is_infinity() const</pre></td> 295<td>Returns true if date is either positive or negative infinity</td> 296</tr> 297<tr><td><pre class="screen">date d(pos_infin); 298d.is_infinity(); // --> true</pre></td></tr> 299<tr> 300<td rowspan="2" valign="top"><pre class="screen">bool is_neg_infinity() const</pre></td> 301<td>Returns true if date is negative infinity</td> 302</tr> 303<tr><td><pre class="screen">date d(neg_infin); 304d.is_neg_infinity(); // --> true</pre></td></tr> 305<tr> 306<td rowspan="2" valign="top"><pre class="screen">bool is_pos_infinity() const</pre></td> 307<td>Returns true if date is positive infinity</td> 308</tr> 309<tr><td><pre class="screen">date d(pos_infin); 310d.is_pos_infinity(); // --> true</pre></td></tr> 311<tr> 312<td rowspan="2" valign="top"><pre class="screen">bool is_not_a_date() const</pre></td> 313<td>Returns true if value is not a date</td> 314</tr> 315<tr><td><pre class="screen">date d(not_a_date_time); 316d.is_not_a_date(); // --> true</pre></td></tr> 317<tr> 318<td rowspan="2" valign="top"><pre class="screen">bool is_special() const</pre></td> 319<td>Returns true if date is any <code class="computeroutput">special_value</code> 320</td> 321</tr> 322<tr><td><pre class="screen">date d(pos_infin); 323date d2(not_a_date_time); 324date d3(2005,Mar,1); 325d.is_special(); // --> true 326d2.is_special(); // --> true 327d3.is_special(); // --> false</pre></td></tr> 328<tr> 329<td rowspan="2" valign="top"><pre class="screen">special_value as_special() const</pre></td> 330<td>Returns represented <code class="computeroutput">special_value</code> or <code class="computeroutput">not_special</code> if the represented date is a normal date.</td> 331</tr> 332<tr><td><pre class="screen"></pre></td></tr> 333<tr> 334<td rowspan="2" valign="top"><pre class="screen">long modjulian_day() const</pre></td> 335<td>Returns the modified julian day for the date.</td> 336</tr> 337<tr><td><pre class="screen"></pre></td></tr> 338<tr> 339<td rowspan="2" valign="top"><pre class="screen">long julian_day() const</pre></td> 340<td>Returns the julian day for the date.</td> 341</tr> 342<tr><td><pre class="screen"></pre></td></tr> 343<tr> 344<td rowspan="2" valign="top"><pre class="screen">int week_number() const</pre></td> 345<td>Returns the ISO 8601 week number for the date.</td> 346</tr> 347<tr><td><pre class="screen"></pre></td></tr> 348<tr> 349<td rowspan="2" valign="top"><pre class="screen">date end_of_month() const</pre></td> 350<td>Returns the last day of the month for the date.</td> 351</tr> 352<tr><td><pre class="screen">date d(2000,Feb,1); 353//gets Feb 29 -- 2000 was leap year 354date eom = d.end_of_month();</pre></td></tr> 355</tbody> 356</table></div> 357<a name="date_convert_to_string"></a><h4> 358<a name="id-1.3.14.8.13.32"></a>Convert to String</h4> 359<div class="informaltable"><table class="table"> 360<colgroup> 361<col> 362<col> 363</colgroup> 364<thead> 365<tr> 366<th rowspan="2" valign="top">Syntax</th> 367<th>Description</th> 368</tr> 369<tr><th>Example</th></tr> 370</thead> 371<tbody> 372<tr> 373<td rowspan="2" valign="top"><pre class="screen">std::string to_simple_string(date d)</pre></td> 374<td>To <code class="computeroutput">YYYY-mmm-DD</code> string where <code class="computeroutput">mmm</code> is a 3 char month name.</td> 375</tr> 376<tr><td><pre class="screen">"2002-Jan-01"</pre></td></tr> 377<tr> 378<td rowspan="2" valign="top"><pre class="screen">std::string to_iso_string(date d)</pre></td> 379<td>To <code class="computeroutput">YYYYMMDD</code> where all components are integers.</td> 380</tr> 381<tr><td><pre class="screen">"20020131"</pre></td></tr> 382<tr> 383<td rowspan="2" valign="top"><pre class="screen">std::string to_iso_extended_string(date d)</pre></td> 384<td> To <code class="computeroutput">YYYY-MM-DD</code> where all components are integers.</td> 385</tr> 386<tr><td><pre class="screen">"2002-01-31"</pre></td></tr> 387</tbody> 388</table></div> 389<a name="date_operators"></a><h4> 390<a name="id-1.3.14.8.13.35"></a>Operators</h4> 391<div class="informaltable"><table class="table"> 392<colgroup> 393<col> 394<col> 395</colgroup> 396<thead> 397<tr> 398<th rowspan="2" valign="top">Syntax</th> 399<th>Description</th> 400</tr> 401<tr><th>Example</th></tr> 402</thead> 403<tbody> 404<tr> 405<td rowspan="2" valign="top"><pre class="screen">operator<<</pre></td> 406<td>Stream output operator</td> 407</tr> 408<tr><td> 409<pre class="screen">date d(2002,Jan,1); 410std::cout << d << std::endl;</pre> 411 </td></tr> 412<tr> 413<td rowspan="2" valign="top"><pre class="screen">operator>></pre></td> 414<td>Stream input operator. <span class="strong"><strong>Note:</strong></span> As of version 1.33, streaming operations have been greatly improved. See <a class="link" href="date_time_io.html" title="Date Time Input/Output">Date Time IO System</a> for details on exceptions and error conditions.</td> 415</tr> 416<tr><td> 417<pre class="screen">date d(not_a_date_time); 418stringstream ss("2002-Jan-01"); 419ss >> d;</pre> 420 </td></tr> 421<tr> 422<td rowspan="2" valign="top"><pre class="screen">operator==, operator!=, 423operator>, operator<, 424operator>=, operator<=</pre></td> 425<td>A full complement of comparison operators</td> 426</tr> 427<tr><td><pre class="screen">d1 == d2, etc</pre></td></tr> 428<tr> 429<td rowspan="2" valign="top"><pre class="screen">date operator+(date_duration) const</pre></td> 430<td>Return a date adding a day offset</td> 431</tr> 432<tr><td> 433<pre class="screen">date d(2002,Jan,1); 434date_duration dd(1); 435date d2 = d + dd;</pre> 436 </td></tr> 437<tr> 438<td rowspan="2" valign="top"><pre class="screen">date operator-(date_duration) const</pre></td> 439<td>Return a date by substracting a day offset</td> 440</tr> 441<tr><td> 442<pre class="screen">date d(2002,Jan,1); 443date_duration dd(1); 444date d2 = d - dd;</pre> 445 </td></tr> 446<tr> 447<td rowspan="2" valign="top"><pre class="screen">date_duration operator-(date) const</pre></td> 448<td>Return a date_duration by subtracting two dates</td> 449</tr> 450<tr><td> 451<pre class="screen">date d1(2002,Jan,1); 452date d2(2002,Jan,2); 453date_duration dd = d2-d1;</pre> 454 </td></tr> 455</tbody> 456</table></div> 457<a name="date_tm_funcs"></a><h4> 458<a name="id-1.3.14.8.13.38"></a>Struct tm Functions</h4> 459<p>Functions for converting a <code class="computeroutput">date</code> object to, and from, a <code class="computeroutput">tm</code> struct are provided.</p> 460<div class="informaltable"><table class="table"> 461<colgroup> 462<col> 463<col> 464</colgroup> 465<thead> 466<tr> 467<th rowspan="2" valign="top">Syntax</th> 468<th>Description</th> 469</tr> 470<tr><th>Example</th></tr> 471</thead> 472<tbody> 473<tr> 474<td rowspan="2" valign="top"><pre class="screen">tm to_tm(date)</pre></td> 475<td>A function for converting a <code class="computeroutput">date</code> object to a <code class="computeroutput">tm</code> struct. The fields: <code class="computeroutput">tm_hour</code>, <code class="computeroutput">tm_min</code>, and <code class="computeroutput">tm_sec</code> are set to zero. The <code class="computeroutput">tm_isdst</code> field is set to -1.</td> 476</tr> 477<tr><td> 478<pre class="screen">date d(2005,Jan,1); 479tm d_tm = to_tm(d); 480/* tm_year => 105 481 tm_mon => 0 482 tm_mday => 1 483 tm_wday => 6 (Saturday) 484 tm_yday => 0 485 tm_hour => 0 486 tm_min => 0 487 tm_sec => 0 488 tm_isdst => -1 */</pre> 489 </td></tr> 490<tr> 491<td rowspan="2" valign="top"><pre class="screen">date date_from_tm(tm datetm)</pre></td> 492<td>A function for converting a <code class="computeroutput">tm</code> struct to a <code class="computeroutput">date</code> object. The fields: <code class="computeroutput">tm_wday </code>, <code class="computeroutput">tm_yday </code>, <code class="computeroutput">tm_hour</code>, <code class="computeroutput">tm_min</code>, <code class="computeroutput">tm_sec</code>, and <code class="computeroutput">tm_isdst</code> are ignored.</td> 493</tr> 494<tr><td> 495<pre class="screen">tm d_tm; 496d_tm.tm_year = 105; 497d_tm.tm_mon = 0; 498d_tm.tm_mday = 1; 499date d = date_from_tm(d_tm); 500// d => 2005-Jan-01</pre> 501 </td></tr> 502</tbody> 503</table></div> 504</div> 505<div class="section"> 506<div class="titlepage"><div><div><h3 class="title"> 507<a name="date_time.gregorian.date_duration"></a>Date Duration (aka Days)</h3></div></div></div> 508<a class="link" href="gregorian.html#duration_intro">Introduction</a> -- 509 <a class="link" href="gregorian.html#duration_header">Header</a> -- 510 <a class="link" href="gregorian.html#duration_construction">Construction</a> -- 511 <a class="link" href="gregorian.html#duration_accessors">Accessors</a> -- 512 <a class="link" href="gregorian.html#duration_operators">Operators</a> -- 513 <a class="link" href="gregorian.html#additional_duration_types">Additional Duration Types</a><a name="duration_intro"></a><h4> 514<a name="id-1.3.14.8.14.9"></a>Introduction</h4> 515<p> 516 The class boost::gregorian::date_duration is a simple day count used for arithmetic with <a class="link" href="gregorian.html#date_time.gregorian.date_class" title="Date">gregorian::date</a>. A duration can be either positive or negative. 517 </p> 518<p> 519 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. 520 </p> 521<a name="duration_header"></a><h4> 522<a name="id-1.3.14.8.14.13"></a>Header</h4> 523<p> 524 </p> 525<pre class="programlisting">#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o 526or 527#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types</pre> 528<p> 529 </p> 530<a name="duration_construction"></a><h4> 531<a name="id-1.3.14.8.14.16"></a>Construction</h4> 532<div class="informaltable"><table class="table"> 533<colgroup> 534<col> 535<col> 536</colgroup> 537<thead> 538<tr> 539<th rowspan="2" valign="top">Syntax</th> 540<th>Description</th> 541</tr> 542<tr><th>Example</th></tr> 543</thead> 544<tbody> 545<tr> 546<td rowspan="2" valign="top"><pre class="screen">date_duration(long)</pre></td> 547<td>Create a duration count.</td> 548</tr> 549<tr><td><pre class="screen">date_duration dd(3); //3 days</pre></td></tr> 550<tr> 551<td rowspan="2" valign="top"><pre class="screen">days(special_values sv)</pre></td> 552<td>Constructor for infinities, not-a-date-time, max_date_time, and min_date_time</td> 553</tr> 554<tr><td><pre class="screen">days dd1(neg_infin); 555days dd2(pos_infin); 556days dd3(not_a_date_time); 557days dd4(max_date_time); 558days dd5(min_date_time);</pre></td></tr> 559</tbody> 560</table></div> 561<a name="duration_accessors"></a><h4> 562<a name="id-1.3.14.8.14.19"></a>Accessors</h4> 563<div class="informaltable"><table class="table"> 564<colgroup> 565<col> 566<col> 567</colgroup> 568<thead> 569<tr> 570<th rowspan="2" valign="top">Syntax</th> 571<th>Description</th> 572</tr> 573<tr><th>Example</th></tr> 574</thead> 575<tbody> 576<tr> 577<td rowspan="2" valign="top"><pre class="screen">long days() const</pre></td> 578<td>Get the day count.</td> 579</tr> 580<tr><td><pre class="screen">date_duration dd(3); dd.days() --> 3</pre></td></tr> 581<tr> 582<td rowspan="2" valign="top"><pre class="screen">bool is_negative() const</pre></td> 583<td>True if number of days is less than zero.</td> 584</tr> 585<tr><td><pre class="screen">date_duration dd(-1); dd.is_negative() --> true</pre></td></tr> 586<tr> 587<td rowspan="2" valign="top"><pre class="screen">static date_duration unit()</pre></td> 588<td>Return smallest possible unit of duration type.</td> 589</tr> 590<tr><td><pre class="screen">date_duration::unit() --> date_duration(1)</pre></td></tr> 591<tr> 592<td rowspan="2" valign="top"><pre class="screen">bool is_special() const</pre></td> 593<td>Returns true if days is any <code class="computeroutput">special_value</code> 594</td> 595</tr> 596<tr><td><pre class="screen">days dd(pos_infin); 597days dd2(not_a_date_time); 598days dd3(25); 599dd.is_special(); // --> true 600dd2.is_special(); // --> true 601dd3.is_special(); // --> false</pre></td></tr> 602</tbody> 603</table></div> 604<a name="duration_operators"></a><h4> 605<a name="id-1.3.14.8.14.22"></a>Operators</h4> 606<div class="informaltable"><table class="table"> 607<colgroup> 608<col> 609<col> 610</colgroup> 611<thead> 612<tr> 613<th rowspan="2" valign="top">Syntax</th> 614<th>Description</th> 615</tr> 616<tr><th>Example</th></tr> 617</thead> 618<tbody> 619<tr> 620<td rowspan="2" valign="top"><pre class="screen">operator<<, operator>></pre></td> 621<td>Streaming operators. <span class="strong"><strong>Note:</strong></span> As of version 1.33, streaming operations have been greatly improved. See <a class="link" href="date_time_io.html" title="Date Time Input/Output">Date Time IO System</a> for more details (including exceptions and error conditions).</td> 622</tr> 623<tr><td> 624<pre class="screen">date d(not_a_date_time); 625stringstream ss("2002-Jan-01"); 626ss >> d; 627std::cout << d; // "2002-Jan-01" 628</pre> 629 </td></tr> 630<tr> 631<td rowspan="2" valign="top"> 632<pre class="screen">operator==, operator!=, 633operator>, operator<, 634operator>=, operator<=</pre> 635 </td> 636<td>A full complement of comparison operators</td> 637</tr> 638<tr><td><pre class="screen">dd1 == dd2, etc</pre></td></tr> 639<tr> 640<td rowspan="2" valign="top"><pre class="screen">date_duration operator+(date_duration) const</pre></td> 641<td>Add date durations.</td> 642</tr> 643<tr><td> 644<pre class="screen">date_duration dd1(3); 645date_duration dd2(5); 646date_duration dd3 = dd1 + dd2;</pre> 647 </td></tr> 648<tr> 649<td rowspan="2" valign="top"><pre class="screen">date_duration operator-(date_duration) const</pre></td> 650<td>Subtract durations.</td> 651</tr> 652<tr><td> 653<pre class="screen">date_duration dd1(3); 654date_duration dd2(5); 655date_duration dd3 = dd1 - dd2;</pre> 656 </td></tr> 657</tbody> 658</table></div> 659<a name="additional_duration_types"></a><h4> 660<a name="id-1.3.14.8.14.25"></a>Additional Duration Types</h4> 661<p>These additional types are logical representations of spans of days.</p> 662<div class="informaltable"><table class="table"> 663<colgroup> 664<col> 665<col> 666</colgroup> 667<thead> 668<tr> 669<th rowspan="2" valign="top">Syntax</th> 670<th>Description</th> 671</tr> 672<tr><th>Example</th></tr> 673</thead> 674<tbody> 675<tr> 676<td rowspan="2" valign="top"><pre class="screen">months(int num_of_months)</pre></td> 677<td>A logical month representation. Depending on the usage, this <code class="computeroutput">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. <span class="strong"><strong>WARNING: this behavior may lead to unexpected results.</strong></span> See: <a class="link" href="gregorian.html#snap_to_details">Reversibility of Operations Pitfall</a> for complete details and alternatives.</td> 678</tr> 679<tr><td><pre class="screen">months single(1); 680date leap_year(2004,Jan,31); 681date norm_year(2005,Jan,31); 682leap_year + single; // => 2004-Feb-29 683norm_year + single; // => 2005-Feb-28 684date(2005,Jan,1) + single; // => 2005-Feb-01 685date(2005,Feb,1) + single; // => 2005-Mar-01 686date(2005,Feb,28) + single; // => 2005-Mar-31</pre></td></tr> 687<tr> 688<td rowspan="2" valign="top"><pre class="screen">years(int num_of_years)</pre></td> 689<td>A logical representation of a year. The <code class="computeroutput">years</code> object has the same behavior as the <code class="computeroutput">months</code> objects with regards to the end-of-the-month.</td> 690</tr> 691<tr><td><pre class="screen">years single(1); 692date(2003,Feb,28) + single; 693// results in => 2004-Feb-29 694date(2004,Feb,29) + single; 695// results in => 2005-Feb-28</pre></td></tr> 696<tr> 697<td rowspan="2" valign="top"><pre class="screen">weeks(int num_of_weeks)</pre></td> 698<td>A duration type representing a number of <code class="computeroutput">n * 7</code> days.</td> 699</tr> 700<tr><td><pre class="screen">weeks single(1); 701date(2005,Jan,1) + single; // => 2005-Jan-08</pre></td></tr> 702</tbody> 703</table></div> 704<p> 705<a name="snap_to_details"></a> 706</p> 707<h5> 708<a name="id-1.3.14.8.14.28.2"></a>Reversibility of Operations Pitfall</h5> 709<p> 710</p> 711<p>A natural expectation when adding a number of months to a date, and then subtracting the same number of months, is to end up exactly where you started. This is most often the result the <code class="computeroutput">date_time</code> library provides but there is one significant exception: The snap-to-end-of-month behavior implemented by the <a class="link" href="gregorian.html#additional_duration_types">months</a> duration type. The <a class="link" href="gregorian.html#additional_duration_types">months</a> duration type may provide unexpected results when the starting day is the 28th, 29th, or 30th in a 31 day month. The <a class="link" href="gregorian.html#iterators_intro">month_iterator</a> is not affected by this issue and is therefore included in the examples to illustrate a possible alternative. 712</p> 713<p> 714 715</p> 716<p>When the starting date is in the middle of a month, adding or subtracting any number of months will result in a date that is the same day of month (e.g. if you start on the 15th, you will end on the 15th). When a date is the last day of the month, adding or subtracting any number of months will give a result that is also the last day of the month (e.g if you start on Jan 31st, you will land on: Feb 28th, Mar 31st, etc). 717 </p> 718<pre class="programlisting"> 719 // using months duration type 720 date d(2005, Nov, 30); // last day of November 721 d + months(1); // result is last day of December "2005-Dec-31" 722 d - months(1); // result is last day of October "2005-Oct-31" 723 724 // using month_iterator 725 month_iterator itr(d); // last day of November 726 ++itr; // result is last day of December "2005-Dec-31" 727 --itr; // back to original starting point "2005-Nov-30" 728 --itr; // last day of October "2005-Oct-31" 729 </pre> 730<p> 731</p> 732<p> 733 734</p> 735<p>If the start date is the 28th, 29th, or 30th in a 31 day month, the result of adding or subtracting a month may result in the snap-to-end-of-month behavior kicking in unexpectedly. This would cause the final result to be different than the starting date. 736 </p> 737<pre class="programlisting"> 738 // using months duration type 739 date d(2005, Nov, 29); 740 d += months(1); // "2005-Dec-29" 741 d += months(1); // "2006-Jan-29" 742 d += months(1); // "2006-Feb-28" --> snap-to-end-of-month behavior kicks in 743 d += months(1); // "2006-Mar-31" --> unexpected result 744 d -= months(4); // "2005-Nov-30" --> unexpected result, not where we started 745 746 // using month_iterator 747 month_iterator itr(date(2005, Dec, 30)); 748 ++itr; // "2006-Jan-30" --> ok 749 ++itr; // "2006-Feb-28" --> snap-to DOES NOT kick in 750 ++itr; // "2006-Mar-30" --> ok 751 --itr; // "2006-Feb-28" --> ok 752 --itr; // "2006-Jan-30" --> ok 753 --itr; // "2005-Dec-30" --> ok, back where we started 754 </pre> 755<p> 756</p> 757<p> 758 759</p> 760<p>The additional duration types (<code class="computeroutput">months</code>, <code class="computeroutput">years</code>, and <code class="computeroutput">weeks</code>) are provided as a convenience and can be easily removed to insure this pitfall never occurs. To remove these types simply undefine BOOST_DATE_TIME_OPTIONAL_GREGORIAN_TYPES.</p> 761<p> 762</p> 763</div> 764<div class="section"> 765<div class="titlepage"><div><div><h3 class="title"> 766<a name="date_time.gregorian.date_period"></a>Date Period</h3></div></div></div> 767<a class="link" href="gregorian.html#period_intro">Introduction</a> -- 768 <a class="link" href="gregorian.html#period_header">Header</a> -- 769 <a class="link" href="gregorian.html#period_construction">Construction</a> -- 770 <a class="link" href="gregorian.html#date_period_mutators">Mutators</a> -- 771 <a class="link" href="gregorian.html#period_accessors">Accessors</a> -- 772 <a class="link" href="gregorian.html#period_convert_to_string">Convert to String</a> -- 773 <a class="link" href="gregorian.html#period_operators">Operators</a><a name="period_intro"></a><h4> 774<a name="id-1.3.14.8.15.10"></a>Introduction</h4> 775<p> 776 The class boost::gregorian::date_period provides direct representation for ranges between two dates. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program. For example, testing if a date is within an irregular schedule such as a weekend or holiday can be accomplished using collections of date periods. This is facilitated by several methods that allow evaluation if a date_period intersects with another date period, and to generate the period resulting from the intersection. The <a class="link" href="examples.html#date_time.examples.date_period_calc" title="Date Period Calculations">date period calculation example</a> provides an example of this. 777 </p> 778<p> 779 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 class="computeroutput">last</code> point will always be one unit less that the <code class="computeroutput">begin</code> point. 780 </p> 781<p> 782 Date periods used in combination with infinity values have the ability to represent complex concepts such as 'until further notice'. 783 </p> 784<a name="period_header"></a><h4> 785<a name="id-1.3.14.8.15.15"></a>Header</h4> 786<p> 787 </p> 788<pre class="programlisting">#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o 789or 790#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types</pre> 791<p> 792 </p> 793<a name="period_construction"></a><h4> 794<a name="id-1.3.14.8.15.18"></a>Construction</h4> 795<div class="informaltable"><table class="table"> 796<colgroup> 797<col> 798<col> 799</colgroup> 800<thead> 801<tr> 802<th rowspan="2" valign="top">Syntax</th> 803<th>Description</th> 804</tr> 805<tr><th>Example</th></tr> 806</thead> 807<tbody> 808<tr> 809<td rowspan="2" valign="top"><pre class="screen">date_period(date, date)</pre></td> 810<td>Create a period as [begin, end). If end is <= begin then the period will be invalid.</td> 811</tr> 812<tr><td><pre class="screen">date_period dp(date(2002,Jan,10), 813 date(2002,Jan,12));</pre></td></tr> 814<tr> 815<td rowspan="2" valign="top"><pre class="screen">date_period(date, days)</pre></td> 816<td>Create a period as [begin, begin+len) where end point would be begin+len. If len is <= zero then the period will be defined as invalid.</td> 817</tr> 818<tr><td><pre class="screen">date_period dp(date(2002,Jan,10), 819 days(2));</pre></td></tr> 820<tr> 821<td rowspan="2" valign="top"><pre class="screen">date_period(date_period)</pre></td> 822<td> Copy constructor</td> 823</tr> 824<tr><td><pre class="screen">date_period dp1(dp);</pre></td></tr> 825</tbody> 826</table></div> 827<a name="date_period_mutators"></a><h4> 828<a name="id-1.3.14.8.15.21"></a>Mutators</h4> 829<p> 830 </p> 831<div class="informaltable"><table class="table"> 832<colgroup> 833<col> 834<col> 835</colgroup> 836<thead> 837<tr> 838<th rowspan="2" valign="top">Syntax</th> 839<th>Description</th> 840</tr> 841<tr><th>Example</th></tr> 842</thead> 843<tbody> 844<tr> 845<td rowspan="2" valign="top"><pre class="screen">date_period shift(days)</pre></td> 846<td>Add duration to both begin and end.</td> 847</tr> 848<tr><td> 849 <pre class="screen"> 850date_period dp(date(2005,Jan,1), days(3)); 851dp.shift(days(3)); 852// dp == 2005-Jan-04 to 2005-Jan-07 853 </pre> 854 </td></tr> 855<tr> 856<td rowspan="2" valign="top"><pre class="screen">date_period expand(days)</pre></td> 857<td>Subtract duration from begin and add duration to end.</td> 858</tr> 859<tr><td> 860 <pre class="screen"> 861date_period dp(date(2005,Jan,2), days(2)); 862dp.expand(days(1)); 863// dp == 2005-Jan-01 to 2005-Jan-04 864 </pre> 865 </td></tr> 866</tbody> 867</table></div> 868<p> 869 </p> 870<a name="period_accessors"></a><h4> 871<a name="id-1.3.14.8.15.24"></a>Accessors</h4> 872<div class="informaltable"><table class="table"> 873<colgroup> 874<col> 875<col> 876</colgroup> 877<thead> 878<tr> 879<th rowspan="2" valign="top">Syntax</th> 880<th>Description</th> 881</tr> 882<tr><th>Example</th></tr> 883</thead> 884<tbody> 885<tr> 886<td rowspan="2" valign="top"><pre class="screen">date begin()</pre></td> 887<td> Return first day of period.</td> 888</tr> 889<tr><td> 890<pre class="screen">date_period dp(date(2002,Jan,1), 891 date(2002,Jan,10)); 892dp.begin() --> 2002-Jan-01</pre> 893 </td></tr> 894<tr> 895<td rowspan="2" valign="top"><pre class="screen">date last()</pre></td> 896<td>Return last date in the period</td> 897</tr> 898<tr><td> 899<pre class="screen">date_period dp(date(2002,Jan,1), 900 date(2002,Jan,10)); 901dp.last() --> 2002-Jan-09</pre> 902 </td></tr> 903<tr> 904<td rowspan="2" valign="top"><pre class="screen">date end()</pre></td> 905<td>Return one past the last in period</td> 906</tr> 907<tr><td> 908<pre class="screen">date_period dp(date(2002,Jan,1), 909 date(2002,Jan,10)); 910dp.end() --> 2002-Jan-10</pre> 911 </td></tr> 912<tr> 913<td rowspan="2" valign="top"><pre class="screen">days length()</pre></td> 914<td>Return the length of the date_period</td> 915</tr> 916<tr><td> 917<pre class="screen">date_period dp(date(2002,Jan,1), 918 days(2)); 919dp.length() --> 2</pre> 920 </td></tr> 921<tr> 922<td rowspan="2" valign="top"><pre class="screen">bool is_null()</pre></td> 923<td>True if period is not well formed. eg: end less than or equal to begin.</td> 924</tr> 925<tr><td> 926<pre class="screen">date_period dp(date(2002,Jan,10), 927 date(2002,Jan,1)); 928dp.is_null() --> true</pre> 929 </td></tr> 930<tr> 931<td rowspan="2" valign="top"><pre class="screen">bool contains(date)</pre></td> 932<td>True if date is within the period. Zero length periods cannot contain any points</td> 933</tr> 934<tr><td> 935<pre class="screen">date d(2002,Jan,1); 936date_period dp(d, date(2002,Jan,10)); 937dp.contains(date(2002,Jan,2));// true 938date_period dp2(d, d); 939dp.contains(date(2002,Jan,1));// false</pre> 940 </td></tr> 941<tr> 942<td rowspan="2" valign="top"><pre class="screen">bool contains(date_period)</pre></td> 943<td>True if date period is within the period</td> 944</tr> 945<tr><td> 946<pre class="screen">date_period dp1(date(2002,Jan,1), 947 date(2002,Jan,10)); 948date_period dp2(date(2002,Jan,2), 949 date(2002,Jan,3)); 950dp1.contains(dp2) --> true 951dp2.contains(dp1) --> false</pre> 952 </td></tr> 953<tr> 954<td rowspan="2" valign="top"><pre class="screen">bool intersects(date_period)</pre></td> 955<td>True if periods overlap</td> 956</tr> 957<tr><td> 958<pre class="screen">date_period dp1(date(2002,Jan,1), 959 date(2002,Jan,10)); 960date_period dp2(date(2002,Jan,2), 961 date(2002,Jan,3)); 962dp2.intersects(dp1) --> true</pre> 963 </td></tr> 964<tr> 965<td rowspan="2" valign="top"><pre class="screen">date_period intersection(date_period)</pre></td> 966<td>Calculate the intersection of 2 periods. Null if no intersection.</td> 967</tr> 968<tr><td> 969<pre class="screen">date_period dp1(date(2002,Jan,1), 970 date(2002,Jan,10)); 971date_period dp2(date(2002,Jan,2), 972 date(2002,Jan,3)); 973dp2.intersection(dp1) --> dp2</pre> 974 </td></tr> 975<tr> 976<td rowspan="2" valign="top"><pre class="screen">date_period is_adjacent(date_period)</pre></td> 977<td>Check if two periods are adjacent, but not overlapping.</td> 978</tr> 979<tr><td> 980<pre class="screen">date_period dp1(date(2002,Jan,1), 981 date(2002,Jan,3)); 982date_period dp2(date(2002,Jan,3), 983 date(2002,Jan,10)); 984dp2.is_adjacent(dp1) --> true</pre> 985 </td></tr> 986<tr> 987<td rowspan="2" valign="top"><pre class="screen">date_period is_after(date)</pre></td> 988<td>Determine the period is after a given date.</td> 989</tr> 990<tr><td> 991<pre class="screen">date_period dp1(date(2002,Jan,10), 992 date(2002,Jan,30)); 993date d(2002,Jan,3); 994dp1.is_after(d) --> true</pre> 995 </td></tr> 996<tr> 997<td rowspan="2" valign="top"><pre class="screen">date_period is_before(date)</pre></td> 998<td>Determine the period is before a given date.</td> 999</tr> 1000<tr><td> 1001<pre class="screen">date_period dp1(date(2002,Jan,1), 1002 date(2002,Jan,3)); 1003date d(2002,Jan,10); 1004dp1.is_before(d) --> true</pre> 1005 </td></tr> 1006<tr> 1007<td rowspan="2" valign="top"><pre class="screen">date_period merge(date_period)</pre></td> 1008<td>Returns union of two periods. Null if no intersection.</td> 1009</tr> 1010<tr><td> 1011<pre class="screen">date_period dp1(date(2002,Jan,1), 1012 date(2002,Jan,10)); 1013date_period dp2(date(2002,Jan,9), 1014 date(2002,Jan,31)); 1015dp2.merge(dp1) 1016// 2002-Jan-01/2002-Jan-31</pre> 1017 </td></tr> 1018<tr> 1019<td rowspan="2" valign="top"><pre class="screen">date_period span(date_period)</pre></td> 1020<td>Combines two periods and any gap between them such that begin = min(p1.begin, p2.begin) and end = max(p1.end , p2.end)</td> 1021</tr> 1022<tr><td> 1023<pre class="screen"> 1024date_period dp1(date(2002,Jan,1), 1025 date(2002,Jan,5)); 1026date_period dp2(date(2002,Jan,9), 1027 date(2002,Jan,31)); 1028dp2.span(dp1); // 2002-Jan-01/2002-Jan-31</pre> 1029 </td></tr> 1030<tr> 1031<td rowspan="2" valign="top"><pre class="screen">date_period shift(days)</pre></td> 1032<td>Add duration to both begin and end.</td> 1033</tr> 1034<tr><td> 1035<pre class="screen">date_period dp1(date(2002,Jan,1), 1036 date(2002,Jan,10)); 1037dp1.shift(days(1)); 1038// 2002-Jan-02/2002-Jan-11</pre> 1039 </td></tr> 1040<tr> 1041<td rowspan="2" valign="top"><pre class="screen">date_period expand(days)</pre></td> 1042<td>Subtract duration from begin and add duration to end.</td> 1043</tr> 1044<tr><td> 1045<pre class="screen">date_period dp1(date(2002,Jan,4), 1046 date(2002,Jan,10)); 1047dp1.expand(days(2)); 1048// 2002-Jan-02/2002-Jan-12</pre> 1049 </td></tr> 1050</tbody> 1051</table></div> 1052<a name="period_convert_to_string"></a><h4> 1053<a name="id-1.3.14.8.15.27"></a>Convert to String</h4> 1054<div class="informaltable"><table class="table"> 1055<colgroup> 1056<col> 1057<col> 1058</colgroup> 1059<thead> 1060<tr> 1061<th rowspan="2" valign="top">Syntax</th> 1062<th>Description</th> 1063</tr> 1064<tr><th>Example</th></tr> 1065</thead> 1066<tbody> 1067<tr> 1068<td rowspan="2" valign="top"><pre class="screen">std::string to_simple_string(date_period dp)</pre></td> 1069<td>To <code class="computeroutput">[YYYY-mmm-DD/YYYY-mmm-DD]</code> string where <code class="computeroutput">mmm</code> is 3 char month name.</td> 1070</tr> 1071<tr><td><pre class="screen">[2002-Jan-01/2002-Jan-31]</pre></td></tr> 1072</tbody> 1073</table></div> 1074<a name="period_operators"></a><h4> 1075<a name="id-1.3.14.8.15.30"></a>Operators</h4> 1076<div class="informaltable"><table class="table"> 1077<colgroup> 1078<col> 1079<col> 1080</colgroup> 1081<thead> 1082<tr> 1083<th rowspan="2" valign="top">Syntax</th> 1084<th>Description</th> 1085</tr> 1086<tr><th>Example</th></tr> 1087</thead> 1088<tbody> 1089<tr> 1090<td rowspan="2" valign="top"><pre class="screen">operator<<</pre></td> 1091<td>ostream operator for date_period. Uses facet to format time points. Typical output: [2002-Jan-01/2002-Jan-31].</td> 1092</tr> 1093<tr><td><pre class="screen">std::cout << dp << std::endl;</pre></td></tr> 1094<tr> 1095<td rowspan="2" valign="top"><pre class="screen">operator>></pre></td> 1096<td>istream operator for date_period. Uses facet to parse time points.</td> 1097</tr> 1098<tr><td><pre class="screen">"[2002-Jan-01/2002-Jan-31]"</pre></td></tr> 1099<tr> 1100<td rowspan="2" valign="top"> 1101<pre class="screen">operator==, operator!=, 1102operator>, operator<</pre> 1103 </td> 1104<td>A full complement of comparison operators</td> 1105</tr> 1106<tr><td><pre class="screen">dp1 == dp2, etc</pre></td></tr> 1107<tr> 1108<td rowspan="2" valign="top"><pre class="screen">operator<</pre></td> 1109<td>True if dp1.end() less than dp2.begin()</td> 1110</tr> 1111<tr><td><pre class="screen">dp1 < dp2, etc</pre></td></tr> 1112<tr> 1113<td rowspan="2" valign="top"><pre class="screen">operator></pre></td> 1114<td>True if dp1.begin() greater than dp2.end()</td> 1115</tr> 1116<tr><td><pre class="screen">dp1 > dp2, etc</pre></td></tr> 1117</tbody> 1118</table></div> 1119</div> 1120<div class="section"> 1121<div class="titlepage"><div><div><h3 class="title"> 1122<a name="date_time.gregorian.date_iterators"></a>Date Iterators</h3></div></div></div> 1123<a class="link" href="gregorian.html#iterators_intro">Introduction</a> -- 1124 <a class="link" href="gregorian.html#iterators_header">Header</a> -- 1125 <a class="link" href="gregorian.html#iterators_overview">Overview</a><a name="iterators_intro"></a><h4> 1126<a name="id-1.3.14.8.16.6"></a>Introduction</h4> 1127<p> 1128 Date iterators provide a standard mechanism for iteration through dates. Date iterators are a model of <a href="http://www.sgi.com/tech/stl/BidirectionalIterator.html" target="_top">Bidirectional Iterator</a> and can be used to populate collections with dates and other date generation tasks. For example, the <a class="link" href="examples.html#date_time.examples.print_month" title="Print Month">print month</a> example iterates through all the days in a month and prints them. 1129 </p> 1130<p> 1131 All of the iterators here derive from boost::gregorian::date_iterator. 1132 </p> 1133<a name="iterators_header"></a><h4> 1134<a name="id-1.3.14.8.16.10"></a>Header</h4> 1135<p> 1136 </p> 1137<pre class="programlisting">#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o 1138or 1139#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types</pre> 1140<p> 1141 </p> 1142<a name="iterators_overview"></a><h4> 1143<a name="id-1.3.14.8.16.13"></a>Overview</h4> 1144<div class="informaltable"><table class="table"> 1145<colgroup> 1146<col> 1147<col> 1148</colgroup> 1149<thead> 1150<tr> 1151<th rowspan="2" valign="top">Syntax</th> 1152<th>Description</th> 1153</tr> 1154<tr><th>Example</th></tr> 1155</thead> 1156<tbody> 1157<tr> 1158<td rowspan="2" valign="top"><pre class="screen">date_iterator</pre></td> 1159<td>Common (abstract) base class for all day level iterators.</td> 1160</tr> 1161<tr><td><pre class="screen"></pre></td></tr> 1162<tr> 1163<td rowspan="2" valign="top"><pre class="screen">day_iterator(date start_date, int day_count=1)</pre></td> 1164<td>Iterate <code class="computeroutput">day_count</code> days at a time. This iterator does not provide postfix increment/decrement operators. Only prefix operators are provided.</td> 1165</tr> 1166<tr><td><pre class="screen">day_iterator day_itr(date(2005,Jan,1)); 1167++d_itr; // 2005-Jan-02 1168day_iterator 2day_itr(date(2005,Feb,1),2); 1169++2d_itr; // 2005-Feb-03</pre></td></tr> 1170<tr> 1171<td rowspan="2" valign="top"><pre class="screen">week_iterator(...) 1172 Parameters: 1173 date start_date 1174 int week_offset (defaults to 1)</pre></td> 1175<td>Iterate <code class="computeroutput">week_offset</code> weeks at a time. This iterator does not provide postfix increment/decrement operators. Only prefix operators are provided.</td> 1176</tr> 1177<tr><td><pre class="screen">week_iterator wk_itr(date(2005,Jan,1)); 1178++wk_itr; // 2005-Jan-08 1179week_iterator 2wk_itr(date(2005,Jan,1),2); 1180++2wk_itr; // 2005-Feb-15</pre></td></tr> 1181<tr> 1182<td rowspan="2" valign="top"><pre class="screen">month_iterator(...) 1183 Parameters: 1184 date start_date 1185 int month_offset (defaults to 1)</pre></td> 1186<td>Iterate <code class="computeroutput">month_offset</code> months. There are special rules for handling the end of the month. These are: if start date is last day of the month, always adjust to last day of the month. If date is beyond the end of the month (e.g. Jan 31 + 1 month) adjust back to end of month (for more details and examples of this, see <a class="link" href="gregorian.html#snap_to_details">Reversibility of Operations Pitfall</a>. <span class="strong"><strong>NOTE:</strong></span> the <code class="computeroutput">month_iterator</code> is not effected by this pitfall.) This iterator does not provide postfix increment/decrement operators. Only prefix operators are provided.</td> 1187</tr> 1188<tr><td><pre class="screen">month_iterator m_itr(date(2005,Jan,1)); 1189++m_itr; // 2005-Feb-01 1190month_iterator 2m_itr(date(2005,Feb,1),2); 1191++2m_itr; // 2005-Apr-01</pre></td></tr> 1192<tr> 1193<td rowspan="2" valign="top"><pre class="screen">year_iterator(...) 1194 Parameters: 1195 date start_date 1196 int year_offset (defaults to 1)</pre></td> 1197<td>Iterate year_offset years. The year_iterator will always land on the day of the date parameter except when date is Feb 28 in a non-leap year. In this case the iterator will return Feb 29 for leap years (eg: 2003-Feb-28, 2004-Feb-29, 2005-Feb-28). This iterator does not provide postfix increment/decrement operators. Only prefix operators are provided.</td> 1198</tr> 1199<tr><td><pre class="screen">year_iterator y_itr(date(2005,Jan,1)); 1200++y_itr; // 2006-Jan-01 1201year_iterator 2y_itr(date(2005,Feb,1),2); 1202++2y_itr; // 2007-Feb-01</pre></td></tr> 1203</tbody> 1204</table></div> 1205</div> 1206<div class="section"> 1207<div class="titlepage"><div><div><h3 class="title"> 1208<a name="date_time.gregorian.date_algorithms"></a>Date Generators/Algorithms</h3></div></div></div> 1209<h3> 1210<a name="id-1.3.14.8.17.2"></a>Date Generators/Algorithms</h3> 1211<a class="link" href="gregorian.html#algo_intro">Introduction</a> -- 1212 <a class="link" href="gregorian.html#algo_header">Header</a> -- 1213 <a class="link" href="gregorian.html#algo_overview">Class Overview</a> -- 1214 <a class="link" href="gregorian.html#algo_func_overview">Function Overview</a><a name="algo_intro"></a><h4> 1215<a name="id-1.3.14.8.17.8"></a>Introduction</h4> 1216<p> 1217 Date algorithms or generators are tools for generating other dates or schedules of dates. A generator function starts with some part of a date such as a month and day and is supplied another part to then generate a concrete date. This allows the programmer to represent concepts such as "The first Sunday in February" and then create a concrete set of dates when provided with one or more years. 1218 <span class="emphasis"><em>Note</em></span>: As of boost version 1_31_0, date generator names have been changed. Old names are still available but are no longer documented and may someday be deprecated 1219 </p> 1220<p>Also provided are stand-alone functions for generating a date, or calculation a duration of days. These functions take a date object and a weekday object as parameters. 1221 </p> 1222<p>All date generator classes and functions are in the boost::gregorian namespace. 1223 </p> 1224<p> 1225 The <a class="link" href="examples.html#date_time.examples.print_holidays" title="Print Holidays">print holidays</a> example shows a detailed usage example. 1226 </p> 1227<a name="algo_header"></a><h4> 1228<a name="id-1.3.14.8.17.14"></a>Header</h4> 1229<pre class="programlisting">#include "boost/date_time/gregorian/gregorian.hpp"</pre> 1230<p> 1231 </p> 1232<a name="algo_overview"></a><h4> 1233<a name="id-1.3.14.8.17.17"></a>Overview</h4> 1234<div class="informaltable"><table class="table"> 1235<colgroup> 1236<col> 1237<col> 1238</colgroup> 1239<thead> 1240<tr> 1241<th rowspan="2" valign="top">Class and get_date Parameter</th> 1242<th>Description</th> 1243</tr> 1244<tr><th>Example</th></tr> 1245</thead> 1246<tbody> 1247<tr> 1248<td rowspan="2" valign="top"><pre class="screen">year_based_generator 1249date get_date(greg_year year)</pre></td> 1250<td>A unifying (abstract) date_generator base type for: <code class="computeroutput">partial_date</code>, <code class="computeroutput">nth_day_of_the_week_in_month</code>, <code class="computeroutput">first_day_of_the_week_in_month</code>, and <code class="computeroutput">last_day_of_the_week_in_month</code>.</td> 1251</tr> 1252<tr><td>The <a class="link" href="examples.html#date_time.examples.print_holidays" title="Print Holidays">print holidays</a> example shows a detailed usage example.</td></tr> 1253<tr> 1254<td rowspan="2" valign="top"><pre class="screen">last_day_of_the_week_in_month(greg_weekday, 1255 greg_month) 1256date get_date(greg_year year)</pre></td> 1257<td>Calculate something like last Monday of January</td> 1258</tr> 1259<tr><td> 1260<pre class="screen">last_day_of_the_week_in_month lwdm(Monday,Jan); 1261date d = lwdm.get_date(2002); 1262//2002-Jan-28</pre> 1263 </td></tr> 1264<tr> 1265<td rowspan="2" valign="top"><pre class="screen">first_day_of_the_week_in_month(greg_weekday, 1266 greg_month) 1267date get_date(greg_year year)</pre></td> 1268<td>Calculate something like first Monday of January</td> 1269</tr> 1270<tr><td> 1271<pre class="screen">first_day_of_the_week_in_month fdm(Monday,Jan); 1272date d = fdm.get_date(2002); 1273//2002-Jan-07</pre> 1274 </td></tr> 1275<tr> 1276<td rowspan="2" valign="top"><pre class="screen">nth_day_of_the_week_in_month(week_num, 1277 greg_weekday, 1278 greg_month) 1279date get_date(greg_year year)</pre></td> 1280<td> 1281<code class="computeroutput">week_num</code> is a public enum member of <code class="computeroutput">nth_day_of_the_week_in_month</code>. Calculate something like first Monday of January, second Tuesday of March, Third Sunday of December, etc. (first through fifth are provided, fifth is the equivalent of last)</td> 1282</tr> 1283<tr><td> 1284<pre class="screen">typedef nth_day_of_the_week_in_month nth_dow; 1285nth_dow ndm(nth_dow::third, Monday,Jan); 1286date d = ndm.get_date(2002); 1287//2002-Jan-21</pre> 1288 </td></tr> 1289<tr> 1290<td rowspan="2" valign="top"><pre class="screen">partial_date(greg_day, greg_month) 1291date get_date(greg_year year)</pre></td> 1292<td>Generates a date by applying the year to the given month and day.</td> 1293</tr> 1294<tr><td> 1295<pre class="screen">partial_date pd(1,Jan); 1296date d = pd.get_date(2002); 1297//2002-Jan-01</pre> 1298 </td></tr> 1299<tr> 1300<td rowspan="2" valign="top"><pre class="screen">first_day_of_the_week_after(greg_weekday) 1301date get_date(date d)</pre></td> 1302<td>Calculate something like First Sunday after Jan 1,2002</td> 1303</tr> 1304<tr><td> 1305<pre class="screen">first_day_of_the_week_after fdaf(Monday); 1306date d = fdaf.get_date(date(2002,Jan,1)); 1307//2002-Jan-07</pre> 1308 </td></tr> 1309<tr> 1310<td rowspan="2" valign="top"><pre class="screen">first_day_of_the_week_before(greg_weekday) 1311date get_date(date d)</pre></td> 1312<td>Calculate something like First Monday before Feb 1,2002</td> 1313</tr> 1314<tr><td> 1315<pre class="screen">first_day_of_the_week_before fdbf(Monday); 1316date d = fdbf.get_date(date(2002,Feb,1)); 1317//2002-Jan-28</pre> 1318 </td></tr> 1319</tbody> 1320</table></div> 1321<a name="algo_func_overview"></a><h4> 1322<a name="id-1.3.14.8.17.20"></a>Function Overview</h4> 1323<div class="informaltable"><table class="table"> 1324<colgroup> 1325<col> 1326<col> 1327</colgroup> 1328<thead> 1329<tr> 1330<th rowspan="2" valign="top">Function Prototype</th> 1331<th>Description</th> 1332</tr> 1333<tr><th>Example</th></tr> 1334</thead> 1335<tbody> 1336<tr> 1337<td rowspan="2" valign="top"><pre class="screen">days days_until_weekday date, greg_weekday)</pre></td> 1338<td> Calculates the number of days from given date until given weekday.</td> 1339</tr> 1340<tr><td> 1341<pre class="screen">date d(2004,Jun,1); // Tuesday 1342greg_weekday gw(Friday); 1343days_until_weekday(d, gw); // 3 days</pre> 1344 </td></tr> 1345<tr> 1346<td rowspan="2" valign="top"><pre class="screen">days days_before_weekday(date, greg_weekday)</pre></td> 1347<td> Calculates the number of day from given date to previous given weekday.</td> 1348</tr> 1349<tr><td> 1350<pre class="screen">date d(2004,Jun,1); // Tuesday 1351greg_weekday gw(Friday); 1352days_before_weekday(d, gw); // 4 days</pre> 1353 </td></tr> 1354<tr> 1355<td rowspan="2" valign="top"><pre class="screen">date next_weekday(date, greg_weekday)</pre></td> 1356<td> Generates a date object representing the date of the following weekday from the given date. Can return the given date.</td> 1357</tr> 1358<tr><td> 1359<pre class="screen">date d(2004,Jun,1); // Tuesday 1360greg_weekday gw1(Friday); 1361greg_weekday gw2(Tuesday); 1362next_weekday(d, gw1); // 2004-Jun-4 1363next_weekday(d, gw2); // 2004-Jun-1 1364 </pre> 1365 </td></tr> 1366<tr> 1367<td rowspan="2" valign="top"><pre class="screen">date previous_weekday(date, greg_weekday)</pre></td> 1368<td> Generates a date object representing the date of the previous weekday from the given date. Can return the given date. </td> 1369</tr> 1370<tr><td> 1371<pre class="screen">date d(2004,Jun,1); // Tuesday 1372greg_weekday gw1(Friday); 1373greg_weekday gw2(Tuesday); 1374previous_weekday(d, gw1); // 2004-May-28 1375previous_weekday(d, gw2); // 2004-Jun-1 1376 </pre> 1377 </td></tr> 1378</tbody> 1379</table></div> 1380</div> 1381<div class="section"> 1382<div class="titlepage"><div><div><h3 class="title"> 1383<a name="date_time.gregorian.gregorian_calendar"></a>Gregorian Calendar</h3></div></div></div> 1384<a class="link" href="gregorian.html#gregcal_intro">Introduction</a> -- 1385 <a class="link" href="gregorian.html#gregcal_header">Header</a> -- 1386 <a class="link" href="gregorian.html#gregcal_functions">Functions</a><a name="gregcal_intro"></a><h4> 1387<a name="id-1.3.14.8.18.6"></a>Introduction</h4> 1388<p> 1389 The class boost::gregorian::gregorian_calendar implements the functions necessary to create the gregorian date system. It converts to the year-month-day form of a date to a day number representation and back. 1390 </p> 1391<p> 1392 For most purposes this class is simply accessed by <a class="link" href="gregorian.html#date_time.gregorian.date_class" title="Date">gregorian::date</a> and is not used directly by the user. However, there are useful functions that might be of use such as the end_of_month_day function. 1393 </p> 1394<p> 1395 The <a class="link" href="examples.html#date_time.examples.print_month" title="Print Month">print month</a> example demonstrates this. 1396 </p> 1397<a name="gregcal_header"></a><h4> 1398<a name="id-1.3.14.8.18.11"></a>Header</h4> 1399<p> 1400 </p> 1401<pre class="programlisting">#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o 1402or 1403#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types</pre> 1404<p> 1405 </p> 1406<a name="gregcal_functions"></a><h4> 1407<a name="id-1.3.14.8.18.14"></a>Functions</h4> 1408<div class="informaltable"><table class="table"> 1409<colgroup> 1410<col> 1411<col> 1412</colgroup> 1413<thead> 1414<tr> 1415<th rowspan="2" valign="top">Syntax</th> 1416<th>Description</th> 1417</tr> 1418<tr><th>Example</th></tr> 1419</thead> 1420<tbody> 1421<tr> 1422<td rowspan="2" valign="top"><pre class="screen">static short day_of_week(ymd_type)</pre></td> 1423<td>Return the day of the week (0==Sunday, 1==Monday, etc)</td> 1424</tr> 1425<tr><td>See also <a class="link" href="gregorian.html#date_time.gregorian.date_class" title="Date">gregorian::date</a> day_of_week</td></tr> 1426<tr> 1427<td rowspan="2" valign="top"><pre class="screen">static date_int_type day_number(ymd_type)</pre></td> 1428<td> Convert a ymd_type into a day number. The day number mapping is implementation defined, however the library implements the 1400-01-01 epoch as follows <pre class="screen"> date(gregorian_calendar::epoch()).day_number() == 2232400</pre> 1429</td> 1430</tr> 1431<tr><td> </td></tr> 1432<tr> 1433<td rowspan="2" valign="top"><pre class="screen">static short end_of_month_day(year_type, 1434 month_type)</pre></td> 1435<td>Given a year and month determine the last day of the month.</td> 1436</tr> 1437<tr><td> </td></tr> 1438<tr> 1439<td rowspan="2" valign="top"><pre class="screen">static ymd_type from_day_number(date_int_type)</pre></td> 1440<td> Convert a day number to a ymd struct.</td> 1441</tr> 1442<tr><td> </td></tr> 1443<tr> 1444<td rowspan="2" valign="top"><pre class="screen">static bool is_leap_year(year_type)</pre></td> 1445<td>Returns true if specified year is a leap year.</td> 1446</tr> 1447<tr><td><pre class="screen">gregorian_calendar::is_leap_year(2000) 1448//--> true</pre></td></tr> 1449</tbody> 1450</table></div> 1451</div> 1452</div> 1453<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 1454<td align="left"></td> 1455<td align="right"><div class="copyright-footer">Copyright © 2001-2005 CrystalClear Software, Inc<p>Subject to the Boost Software License, Version 1.0. (See accompanying file 1456 <code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p> 1457</div></td> 1458</tr></table> 1459<hr> 1460<div class="spirit-nav"> 1461<a accesskey="p" href="examples/general_usage_examples.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../date_time.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="posix_time.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 1462</div> 1463</body> 1464</html> 1465
