Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/date_time/gregorian.html @ 46

Last change on this file since 46 was 29, checked in by landauf, 17 years ago

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