| blob | 3f1e911607a7e2c034dcc2a880f9390ef2c81519 |
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
3 "../../../tools/boostbook/dtd/boostbook.dtd">
5 <!-- Copyright (c) 2001-2007 CrystalClear Software, Inc.
6 Subject to the Boost Software License, Version 1.0.
7 (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
8 -->
10 <section id="date_time.gregorian.date_class">
11 <title>Date</title>
13 <link linkend="date_intro">Introduction</link> --
14 <link linkend="date_header">Header</link> --
15 <link linkend="date_construction">Construction</link> --
16 <link linkend="date_construct_from_string">Construct from String</link> --
17 <link linkend="date_construct_from_clock">Construct from Clock</link> --
18 <link linkend="date_accessors">Accessors</link> --
19 <link linkend="date_convert_to_string">Convert to String</link> --
20 <link linkend="date_operators">Operators</link> --
21 <link linkend="date_tm_funcs">Struct tm Functions</link>
23 <anchor id="date_intro" />
24 <bridgehead renderas="sect3">Introduction</bridgehead>
25 <para>
26 The class boost::gregorian::date is the primary interface for date programming. In general,
27 the date class is immutable once constructed although it does allow assignment from another
28 date.
29 Techniques for creating dates include reading the
30 <link linkend="date_construct_from_clock">current date from the clock</link>,
31 using <link linkend="date_time.gregorian.date_iterators">date iterators</link>, and
32 <link linkend="date_time.gregorian.date_algorithms">date algorithms or generators</link>.
33 </para>
35 <para>
36 Internally boost::gregorian::date is stored as a 32 bit integer type. The class is specifically
37 designed to NOT contain virtual functions. This design allows for efficient
38 calculation and memory usage with large collections of dates.
39 </para>
41 <para>
42 The construction of a date validates all input so that it is not possible to
43 construct an 'invalid' date. That is 2001-Feb-29 cannot be constructed as a date.
44 Various exceptions derived from std::out_of_range are thrown to indicate which aspect
45 of the date input is invalid. Note that the
46 special value not-a-date-time can be used as 'invalid' or 'null' date if so desired.
47 </para>
49 <anchor id="date_header" />
50 <bridgehead renderas="sect3">Header</bridgehead>
51 <para>
52 <programlisting>#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o
53 or
54 #include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types</programlisting>
55 </para>
57 <anchor id="date_construction" />
58 <bridgehead renderas="sect3">Construction</bridgehead>
59 <informaltable frame="all">
60 <tgroup cols="2">
61 <thead>
62 <row>
63 <entry valign="top" morerows="1">Syntax</entry>
64 <entry>Description</entry>
65 </row>
66 <row>
67 <entry>Example</entry>
68 </row>
69 </thead>
70 <tbody>
71 <row>
72 <entry valign="top" morerows="1"><screen>date(greg_year, greg_month, greg_day)</screen></entry>
73 <entry>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.</entry>
74 </row>
75 <row>
76 <entry><screen>date d(2002,Jan,10);</screen></entry>
77 </row>
79 <row>
80 <entry valign="top" morerows="1"><screen>date(date d)</screen></entry>
81 <entry>Copy constructor</entry>
82 </row>
83 <row>
84 <entry><screen>date d1(d);</screen></entry>
85 </row>
87 <row>
88 <entry valign="top" morerows="1"><screen>date(special_values sv)</screen></entry>
89 <entry>Constructor for infinities, not-a-date-time, max_date_time, and min_date_time</entry>
90 </row>
91 <row>
92 <entry><screen>date d1(neg_infin);
93 date d2(pos_infin);
94 date d3(not_a_date_time);
95 date d4(max_date_time);
96 date d5(min_date_time);</screen></entry>
97 </row>
99 <row>
100 <entry valign="top" morerows="1"><screen>date()</screen></entry>
101 <entry>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)</entry>
102 </row>
103 <row>
104 <entry><screen>date d; // d => not_a_date_time</screen></entry>
105 </row>
106 </tbody>
107 </tgroup>
108 </informaltable>
110 <anchor id="date_construct_from_string" />
111 <bridgehead renderas="sect3">Construct from String</bridgehead>
112 <informaltable frame="all">
113 <tgroup cols="2">
114 <thead>
115 <row>
116 <entry valign="top" morerows="1">Syntax</entry>
117 <entry>Description</entry>
118 </row>
119 <row>
120 <entry>Example</entry>
121 </row>
122 </thead>
123 <tbody>
124 <row>
125 <entry valign="top" morerows="1"><screen>date from_string(std::string)</screen></entry>
126 <entry>From delimited date string where with order year-month-day eg: 2002-1-25</entry>
127 </row>
128 <row>
129 <entry><screen>std::string ds("2002/1/25");
130 date d(from_string(ds));</screen></entry>
131 </row>
133 <row>
134 <entry valign="top" morerows="1"><screen>date from_undelimited_string(std::string)</screen></entry>
135 <entry>From iso type date string where with order year-month-day eg: 20020125</entry>
136 </row>
137 <row>
138 <entry><screen>std::string ds("20020125");
139 date d(from_undelimited_string(ds));</screen></entry>
140 </row>
141 </tbody>
142 </tgroup>
143 </informaltable>
145 <anchor id="date_construct_from_clock" />
146 <bridgehead renderas="sect3">Construct from Clock</bridgehead>
147 <informaltable frame="all">
148 <tgroup cols="2">
149 <thead>
150 <row>
151 <entry valign="top" morerows="1">Syntax</entry>
152 <entry>Description</entry>
153 </row>
154 <row>
155 <entry>Example</entry>
156 </row>
157 </thead>
158 <tbody>
159 <row>
160 <entry valign="top" morerows="1"><screen>day_clock::local_day()</screen></entry>
161 <entry>Get the local day based on the time zone settings of the computer.</entry>
162 </row>
163 <row>
164 <entry><screen>date d(day_clock::local_day());</screen></entry>
165 </row>
167 <row>
168 <entry valign="top" morerows="1"><screen>day_clock::universal_day()</screen></entry>
169 <entry>Get the UTC day.</entry>
170 </row>
171 <row>
172 <entry><screen>date d(day_clock::universal_day());</screen></entry>
173 </row>
174 </tbody>
175 </tgroup>
176 </informaltable>
178 <anchor id="date_accessors" />
179 <bridgehead renderas="sect3">Accessors</bridgehead>
180 <informaltable frame="all">
181 <tgroup cols="2">
182 <thead>
183 <row>
184 <entry valign="top" morerows="1">Syntax</entry>
185 <entry>Description</entry>
186 </row>
187 <row>
188 <entry>Example</entry>
189 </row>
190 </thead>
191 <tbody>
192 <row>
193 <entry valign="top" morerows="1"><screen>greg_year year() const</screen></entry>
194 <entry>Get the year part of the date.</entry>
195 </row>
196 <row>
197 <entry><screen>date d(2002,Jan,10);
198 d.year(); // --> 2002</screen></entry>
199 </row>
201 <row>
202 <entry valign="top" morerows="1"><screen>greg_month month() const</screen></entry>
203 <entry>Get the month part of the date.</entry>
204 </row>
205 <row>
206 <entry><screen>date d(2002,Jan,10);
207 d.month(); // --> 1</screen></entry>
208 </row>
210 <row>
211 <entry valign="top" morerows="1"><screen>greg_day day() const</screen></entry>
212 <entry> Get the day part of the date.</entry>
213 </row>
214 <row>
215 <entry><screen>date d(2002,Jan,10);
216 d.day(); // --> 10</screen></entry>
217 </row>
219 <row>
220 <entry valign="top" morerows="1"><screen>greg_ymd year_month_day() const</screen></entry>
221 <entry>Return a year_month_day struct. More efficient when all 3 parts of the date are needed.</entry>
222 </row>
223 <row>
224 <entry><screen>date d(2002,Jan,10);
225 date::ymd_type ymd = d.year_month_day();
226 // ymd.year --> 2002,
227 // ymd.month --> 1,
228 // ymd.day --> 10</screen></entry>
229 </row>
231 <row>
232 <entry valign="top" morerows="1"><screen>greg_day_of_week day_of_week() const</screen></entry>
233 <entry>Get the day of the week (Sunday, Monday, etc.)</entry>
234 </row>
235 <row>
236 <entry><screen>date d(2002,Jan,10);
237 d.day(); // --> Thursday</screen></entry>
238 </row>
240 <row>
241 <entry valign="top" morerows="1"><screen>greg_day_of_year day_of_year() const</screen></entry>
242 <entry>Get the day of the year. Number from 1 to 366 </entry>
243 </row>
244 <row>
245 <entry><screen>date d(2000,Jan,10);
246 d.day_of_year(); // --> 10</screen></entry>
247 </row>
249 <row>
250 <entry valign="top" morerows="1"><screen>date end_of_month() const</screen></entry>
251 <entry>Returns a <code>date</code> object set to the last day of the calling objects current month.</entry>
252 </row>
253 <row>
254 <entry><screen>date d(2000,Jan,10);
255 d.end_of_month(); // --> 2000-Jan-31</screen></entry>
256 </row>
258 <row>
259 <entry valign="top" morerows="1"><screen>bool is_infinity() const</screen></entry>
260 <entry>Returns true if date is either positive or negative infinity</entry>
261 </row>
262 <row>
263 <entry><screen>date d(pos_infin);
264 d.is_infinity(); // --> true</screen></entry>
265 </row>
267 <row>
268 <entry valign="top" morerows="1"><screen>bool is_neg_infinity() const</screen></entry>
269 <entry>Returns true if date is negative infinity</entry>
270 </row>
271 <row>
272 <entry><screen>date d(neg_infin);
273 d.is_neg_infinity(); // --> true</screen></entry>
274 </row>
276 <row>
277 <entry valign="top" morerows="1"><screen>bool is_pos_infinity() const</screen></entry>
278 <entry>Returns true if date is positive infinity</entry>
279 </row>
280 <row>
281 <entry><screen>date d(neg_infin);
282 d.is_pos_infinity(); // --> true</screen></entry>
283 </row>
285 <row>
286 <entry valign="top" morerows="1"><screen>bool is_not_a_date() const</screen></entry>
287 <entry>Returns true if value is not a date</entry>
288 </row>
289 <row>
290 <entry><screen>date d(not_a_date_time);
291 d.is_not_a_date(); // --> true</screen></entry>
292 </row>
294 <row>
295 <entry valign="top" morerows="1"><screen>bool is_special() const</screen></entry>
296 <entry>Returns true if date is any <code>special_value</code></entry>
297 </row>
298 <row>
299 <entry><screen>date d(pos_infin);
300 date d2(not_a_date_time);
301 date d3(2005,Mar,1);
302 d.is_special(); // --> true
303 d2.is_special(); // --> true
304 d3.is_special(); // --> false</screen></entry>
305 </row>
307 <row>
308 <entry valign="top" morerows="1"><screen>special_value as_special() const</screen></entry>
309 <entry>Returns represented <code>special_value</code> or <code>not_special</code> if the represented date is a normal date.</entry>
310 </row>
311 <row>
312 <entry><screen></screen></entry>
313 </row>
315 <row>
316 <entry valign="top" morerows="1"><screen>long modjulian_day() const</screen></entry>
317 <entry>Returns the modified julian day for the date.</entry>
318 </row>
319 <row>
320 <entry><screen></screen></entry>
321 </row>
323 <row>
324 <entry valign="top" morerows="1"><screen>long julian_day() const</screen></entry>
325 <entry>Returns the julian day for the date.</entry>
326 </row>
327 <row>
328 <entry><screen></screen></entry>
329 </row>
331 <row>
332 <entry valign="top" morerows="1"><screen>int week_number() const</screen></entry>
333 <entry>Returns the ISO 8601 week number for the date.</entry>
334 </row>
335 <row>
336 <entry><screen></screen></entry>
337 </row>
338 <row>
339 <entry valign="top" morerows="1"><screen>date end_of_month_day() const</screen></entry>
340 <entry>Returns the last day of the month for the date.</entry>
341 </row>
342 <row>
343 <entry><screen>date d(2000,Feb,1);
344 //gets Feb 28 -- 2000 was leap year
345 date eom = d.end_of_month_day();</screen></entry>
346 </row>
347 </tbody>
348 </tgroup>
349 </informaltable>
351 <anchor id="date_convert_to_string" />
352 <bridgehead renderas="sect3">Convert to String</bridgehead>
353 <informaltable frame="all">
354 <tgroup cols="2">
355 <thead>
356 <row>
357 <entry valign="top" morerows="1">Syntax</entry>
358 <entry>Description</entry>
359 </row>
360 <row>
361 <entry>Example</entry>
362 </row>
363 </thead>
364 <tbody>
365 <row>
366 <entry valign="top" morerows="1"><screen>std::string to_simple_string(date d)</screen></entry>
367 <entry>To <code>YYYY-mmm-DD</code> string where <code>mmm</code> is a 3 char month name.</entry>
368 </row>
369 <row>
370 <entry><screen>"2002-Jan-01"</screen></entry>
371 </row>
373 <row>
374 <entry valign="top" morerows="1"><screen>std::string to_iso_string(date d)</screen></entry>
375 <entry>To <code>YYYYMMDD</code> where all components are integers.</entry>
376 </row>
377 <row>
378 <entry><screen>"20020131"</screen></entry>
379 </row>
381 <row>
382 <entry valign="top" morerows="1"><screen>std::string to_iso_extended_string(date d)</screen></entry>
383 <entry> To <code>YYYY-MM-DD</code> where all components are integers.</entry>
384 </row>
385 <row>
386 <entry><screen>"2002-01-31"</screen></entry>
387 </row>
388 </tbody>
389 </tgroup>
390 </informaltable>
392 <anchor id="date_operators" />
393 <bridgehead renderas="sect3">Operators</bridgehead>
394 <informaltable frame="all">
395 <tgroup cols="2">
396 <thead>
397 <row>
398 <entry valign="top" morerows="1">Syntax</entry>
399 <entry>Description</entry>
400 </row>
401 <row>
402 <entry>Example</entry>
403 </row>
404 </thead>
405 <tbody>
406 <row>
407 <entry valign="top" morerows="1"><screen>operator<<</screen></entry>
408 <entry>Stream output operator</entry>
409 </row>
410 <row>
411 <entry><screen>date d(2002,Jan,1);
412 std::cout << d << std::endl;</screen>
413 </entry>
414 </row>
416 <row>
417 <entry valign="top" morerows="1"><screen>operator>></screen></entry>
418 <entry>Stream input operator. <emphasis role="strong">Note:</emphasis> As of version 1.33, streaming operations have been greatly improved. See <link linkend="date_time.date_time_io">Date Time IO System</link> for details on exceptions and error conditions.</entry>
419 </row>
420 <row>
421 <entry><screen>date d(not_a_date_time);
422 stringstream ss("2002-Jan-01");
423 ss >> d;</screen>
424 </entry>
425 </row>
427 <row>
428 <entry valign="top" morerows="1"><screen>operator==, operator!=,
429 operator>, operator<,
430 operator>=, operator<=</screen></entry>
431 <entry>A full complement of comparison operators</entry>
432 </row>
433 <row>
434 <entry><screen>d1 == d2, etc</screen></entry>
435 </row>
437 <row>
438 <entry valign="top" morerows="1"><screen>date operator+(date_duration) const</screen></entry>
439 <entry>Return a date adding a day offset</entry>
440 </row>
441 <row>
442 <entry><screen>date d(2002,Jan,1);
443 date_duration dd(1);
444 date d2 = d + dd;</screen>
445 </entry>
446 </row>
448 <row>
449 <entry valign="top" morerows="1"><screen>date operator-(date_duration) const</screen></entry>
450 <entry>Return a date by substracting a day offset</entry>
451 </row>
452 <row>
453 <entry><screen>date d(2002,Jan,1);
454 date_duration dd(1);
455 date d2 = d - dd;</screen>
456 </entry>
457 </row>
459 <row>
460 <entry valign="top" morerows="1"><screen>date_duration operator-(date) const</screen></entry>
461 <entry>Return a date_duration by subtracting two dates</entry>
462 </row>
463 <row>
464 <entry><screen>date d1(2002,Jan,1);
465 date d2(2002,Jan,2);
466 date_duration dd = d2-d1;</screen>
467 </entry>
468 </row>
469 </tbody>
470 </tgroup>
471 </informaltable>
473 <anchor id="date_tm_funcs" />
474 <bridgehead renderas="sect3">Struct tm Functions</bridgehead>
475 <para>Functions for converting a <code>date</code> object to, and from, a <code>tm</code> struct are provided.</para>
476 <informaltable frame="all">
477 <tgroup cols="2">
478 <thead>
479 <row>
480 <entry valign="top" morerows="1">Syntax</entry>
481 <entry>Description</entry>
482 </row>
483 <row>
484 <entry>Example</entry>
485 </row>
486 </thead>
487 <tbody>
488 <row>
489 <entry valign="top" morerows="1"><screen>tm to_tm(date)</screen></entry>
490 <entry>A function for converting a <code>date</code> object to a <code>tm</code> struct. The fields: <code>tm_hour</code>, <code>tm_min</code>, and <code>tm_sec</code> are set to zero. The <code>tm_isdst</code> field is set to -1.</entry>
491 </row>
492 <row>
493 <entry><screen>date d(2005,Jan,1);
494 tm d_tm = to_tm(d);
495 /* tm_year => 105
496 tm_mon => 0
497 tm_mday => 1
498 tm_wday => 6 (Saturday)
499 tm_yday => 0
500 tm_hour => 0
501 tm_min => 0
502 tm_sec => 0
503 tm_isddst => -1 */</screen>
504 </entry>
505 </row>
507 <row>
508 <entry valign="top" morerows="1"><screen>date date_from_tm(tm datetm)</screen></entry>
509 <entry>A function for converting a <code>tm</code> struct to a <code>date</code> object. The fields: <code>tm_wday </code>, <code>tm_yday </code>, <code>tm_hour</code>, <code>tm_min</code>, <code>tm_sec</code>, and <code>tm_isdst</code> are ignored.</entry>
510 </row>
511 <row>
512 <entry><screen>tm d_tm;
513 d_tm.tm_year = 105;
514 d_tm.tm_mon = 0;
515 d_tm.tm_mday = 1;
516 date d = date_from_tm(d_tm);
517 // d => 2005-Jan-01</screen>
518 </entry>
519 </row>
520 </tbody>
521 </tgroup>
522 </informaltable>
524 </section>