1<?xml version="1.0" encoding="utf-8"?> 2<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 3"../../../tools/boostbook/dtd/boostbook.dtd"> 4 5<!-- Copyright (c) 2001-2006 CrystalClear Software, Inc. 6 Subject to the Boost Software License, Version 1.0. 7 (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt) 8--> 9 10<section id="date_time.gregorian.date_period"> 11 <title>Date Period</title> 12 13 <link linkend="period_intro">Introduction</link> -- 14 <link linkend="period_header">Header</link> -- 15 <link linkend="period_construction">Construction</link> -- 16 <link linkend="date_period_mutators">Mutators</link> -- 17 <link linkend="period_accessors">Accessors</link> -- 18 <link linkend="period_convert_to_string">Convert to String</link> -- 19 <link linkend="period_operators">Operators</link> 20 21 <anchor id="period_intro" /> 22 <bridgehead renderas="sect3">Introduction</bridgehead> 23 <para> 24 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 <link linkend="date_time.examples.date_period_calc">date period calculation example</link> provides an example of this. 25 </para> 26 <para> 27 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>last</code> point will always be one unit less that the <code>begin</code> point. 28 </para> 29 <para> 30 Date periods used in combination with infinity values have the ability to represent complex concepts such as 'until further notice'. 31 </para> 32 33 <anchor id="period_header" /> 34 <bridgehead renderas="sect3">Header</bridgehead> 35 <para> 36 <programlisting>#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o 37or 38#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types</programlisting> 39 </para> 40 41 <anchor id="period_construction" /> 42 <bridgehead renderas="sect3">Construction</bridgehead> 43 <informaltable frame="all"> 44 <tgroup cols="2"> 45 <thead> 46 <row> 47 <entry valign="top" morerows="1">Syntax</entry> 48 <entry>Description</entry> 49 </row> 50 <row> 51 <entry>Example</entry> 52 </row> 53 </thead> 54 <tbody> 55 <row> 56 <entry valign="top" morerows="1"><screen>date_period(date, date)</screen></entry> 57 <entry>Create a period as [begin, end). If end is <= begin then the period will be invalid.</entry> 58 </row> 59 <row> 60 <entry><screen>date_period dp(date(2002,Jan,10), 61 date(2002,Jan,12));</screen></entry> 62 </row> 63 64 <row> 65 <entry valign="top" morerows="1"><screen>date_period(date, days)</screen></entry> 66 <entry>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.</entry> 67 </row> 68 <row> 69 <entry><screen>date_period dp(date(2002,Jan,10), 70 days(2));</screen></entry> 71 </row> 72 73 <row> 74 <entry valign="top" morerows="1"><screen>date_period(date_period)</screen></entry> 75 <entry> Copy constructor</entry> 76 </row> 77 <row> 78 <entry><screen>date_period dp1(dp);</screen></entry> 79 </row> 80 </tbody> 81 </tgroup> 82 </informaltable> 83 84 85 <anchor id="date_period_mutators" /> 86 <bridgehead renderas="sect3">Mutators</bridgehead> 87 <para> 88 <informaltable frame="all"> 89 <tgroup cols="2"> 90 <thead> 91 <row> 92 <entry valign="top" morerows="1">Syntax</entry> 93 <entry>Description</entry> 94 </row> 95 <row> 96 <entry>Example</entry> 97 </row> 98 </thead> 99 <tbody> 100 <row> 101 <entry valign="top" morerows="1"><screen>date_period shift(days)</screen></entry> 102 <entry>Add duration to both begin and end.</entry> 103 </row> 104 <row> 105 <entry> 106 <screen> 107date_period dp(date(2005,Jan,1), days(3)); 108dp.shift(days(3)); 109// dp == 2005-Jan-04 to 2005-Jan-07 110 </screen> 111 </entry> 112 </row> 113 114 <row> 115 <entry valign="top" morerows="1"><screen>date_period expand(days)</screen></entry> 116 <entry>Subtract duration from begin and add duration to end.</entry> 117 </row> 118 <row> 119 <entry> 120 <screen> 121date_period dp(date(2005,Jan,2), days(2)); 122dp.expand(days(1)); 123// dp == 2005-Jan-01 to 2005-Jan-04 124 </screen> 125 </entry> 126 </row> 127 128 </tbody> 129 </tgroup> 130 </informaltable> 131 </para> 132 133 134 <anchor id="period_accessors" /> 135 <bridgehead renderas="sect3">Accessors</bridgehead> 136 <informaltable frame="all"> 137 <tgroup cols="2"> 138 <thead> 139 <row> 140 <entry valign="top" morerows="1">Syntax</entry> 141 <entry>Description</entry> 142 </row> 143 <row> 144 <entry>Example</entry> 145 </row> 146 </thead> 147 <tbody> 148 <row> 149 <entry valign="top" morerows="1"><screen>date begin()</screen></entry> 150 <entry> Return first day of period.</entry> 151 </row> 152 <row> 153 <entry><screen>date_period dp(date(2002,Jan,1), 154 date(2002,Jan,10)); 155dp.begin() --> 2002-Jan-01</screen> 156 </entry> 157 </row> 158 159 <row> 160 <entry valign="top" morerows="1"><screen>date last()</screen></entry> 161 <entry>Return last date in the period</entry> 162 </row> 163 <row> 164 <entry><screen>date_period dp(date(2002,Jan,1), 165 date(2002,Jan,10)); 166dp.last() --> 2002-Jan-09</screen> 167 </entry> 168 </row> 169 170 <row> 171 <entry valign="top" morerows="1"><screen>date end()</screen></entry> 172 <entry>Return one past the last in period</entry> 173 </row> 174 <row> 175 <entry><screen>date_period dp(date(2002,Jan,1), 176 date(2002,Jan,10)); 177dp.end() --> 2002-Jan-10</screen> 178 </entry> 179 </row> 180 181 <row> 182 <entry valign="top" morerows="1"><screen>days length()</screen></entry> 183 <entry>Return the length of the date_period</entry> 184 </row> 185 <row> 186 <entry><screen>date_period dp(date(2002,Jan,1), 187 days(2)); 188dp.length() --> 2</screen> 189 </entry> 190 </row> 191 192 <row> 193 <entry valign="top" morerows="1"><screen>bool is_null()</screen></entry> 194 <entry>True if period is not well formed. eg: end less than or equal to begin.</entry> 195 </row> 196 <row> 197 <entry><screen>date_period dp(date(2002,Jan,10), 198 date(2002,Jan,1)); 199dp.is_null() --> true</screen> 200 </entry> 201 </row> 202 203 <row> 204 <entry valign="top" morerows="1"><screen>bool contains(date)</screen></entry> 205 <entry>True if date is within the period. Zero length periods cannot contain any points</entry> 206 </row> 207 <row> 208 <entry><screen>date d(2002,Jan,1); 209date_period dp(d, date(2002,Jan,10)); 210dp.contains(date(2002,Jan,2));// true 211date_period dp2(d, d); 212dp.contains(date(2002,Jan,1));// false</screen> 213 </entry> 214 </row> 215 216 <row> 217 <entry valign="top" morerows="1"><screen>bool contains(date_period)</screen></entry> 218 <entry>True if date period is within the period</entry> 219 </row> 220 <row> 221 <entry><screen>date_period dp1(date(2002,Jan,1), 222 date(2002,Jan,10)); 223date_period dp2(date(2002,Jan,2), 224 date(2002,Jan,3)); 225dp1.contains(dp2) --> true 226dp2.contains(dp1) --> false</screen> 227 </entry> 228 </row> 229 230 <row> 231 <entry valign="top" morerows="1"><screen>bool intersects(date_period)</screen></entry> 232 <entry>True if periods overlap</entry> 233 </row> 234 <row> 235 <entry><screen>date_period dp1(date(2002,Jan,1), 236 date(2002,Jan,10)); 237date_period dp2(date(2002,Jan,2), 238 date(2002,Jan,3)); 239dp2.intersects(dp1) --> true</screen> 240 </entry> 241 </row> 242 243 <row> 244 <entry valign="top" morerows="1"><screen>date_period intersection(date_period)</screen></entry> 245 <entry>Calculate the intersection of 2 periods. Null if no intersection.</entry> 246 </row> 247 <row> 248 <entry><screen>date_period dp1(date(2002,Jan,1), 249 date(2002,Jan,10)); 250date_period dp2(date(2002,Jan,2), 251 date(2002,Jan,3)); 252dp2.intersection(dp1) --> dp2</screen> 253 </entry> 254 </row> 255 256 <row> 257 <entry valign="top" morerows="1"><screen>date_period is_adjacent(date_period)</screen></entry> 258 <entry>Check if two periods are adjacent, but not overlapping.</entry> 259 </row> 260 <row> 261 <entry><screen>date_period dp1(date(2002,Jan,1), 262 date(2002,Jan,3)); 263date_period dp2(date(2002,Jan,3), 264 date(2002,Jan,10)); 265dp2.is_adjacent(dp1) --> true</screen> 266 </entry> 267 </row> 268 269 <row> 270 <entry valign="top" morerows="1"><screen>date_period is_after(date)</screen></entry> 271 <entry>Determine the period is after a given date.</entry> 272 </row> 273 <row> 274 <entry><screen>date_period dp1(date(2002,Jan,10), 275 date(2002,Jan,30)); 276date d(2002,Jan,3); 277dp1.is_after(d) --> true</screen> 278 </entry> 279 </row> 280 281 <row> 282 <entry valign="top" morerows="1"><screen>date_period is_before(date)</screen></entry> 283 <entry>Determine the period is before a given date.</entry> 284 </row> 285 <row> 286 <entry><screen>date_period dp1(date(2002,Jan,1), 287 date(2002,Jan,3)); 288date d(2002,Jan,10); 289dp1.is_before(d) --> true</screen> 290 </entry> 291 </row> 292 293 <row> 294 <entry valign="top" morerows="1"><screen>date_period merge(date_period)</screen></entry> 295 <entry>Returns union of two periods. Null if no intersection.</entry> 296 </row> 297 <row> 298 <entry><screen>date_period dp1(date(2002,Jan,1), 299 date(2002,Jan,10)); 300date_period dp2(date(2002,Jan,9), 301 date(2002,Jan,31)); 302dp2.merge(dp1) 303// 2002-Jan-01/2002-Jan-31</screen> 304 </entry> 305 </row> 306 307 <row> 308 <entry valign="top" morerows="1"><screen>date_period span(date_period)</screen></entry> 309 <entry>Combines two periods and any gap between them such that begin = min(p1.begin, p2.begin) and end = max(p1.end , p2.end)</entry> 310 </row> 311 <row> 312 <entry><screen> 313date_period dp1(date(2002,Jan,1), 314 date(2002,Jan,5)); 315date_period dp2(date(2002,Jan,9), 316 date(2002,Jan,31)); 317dp2.span(dp1); // 2002-Jan-01/2002-Jan-31</screen> 318 </entry> 319 </row> 320 321 <row> 322 <entry valign="top" morerows="1"><screen>date_period shift(days)</screen></entry> 323 <entry>Add duration to both begin and end.</entry> 324 </row> 325 <row> 326 <entry><screen>date_period dp1(date(2002,Jan,1), 327 date(2002,Jan,10)); 328dp1.shift(days(1)); 329// 2002-Jan-02/2002-Jan-11</screen> 330 </entry> 331 </row> 332 333 <row> 334 <entry valign="top" morerows="1"><screen>date_period expand(days)</screen></entry> 335 <entry>Subtract duration from begin and add duration to end.</entry> 336 </row> 337 <row> 338 <entry><screen>date_period dp1(date(2002,Jan,4), 339 date(2002,Jan,10)); 340dp1.expand(days(2)); 341// 2002-Jan-02/2002-Jan-12</screen> 342 </entry> 343 </row> 344 </tbody> 345 </tgroup> 346 </informaltable> 347 348 349 <anchor id="period_convert_to_string" /> 350 <bridgehead renderas="sect3">Convert to String</bridgehead> 351 <informaltable frame="all"> 352 <tgroup cols="2"> 353 <thead> 354 <row> 355 <entry valign="top" morerows="1">Syntax</entry> 356 <entry>Description</entry> 357 </row> 358 <row> 359 <entry>Example</entry> 360 </row> 361 </thead> 362 <tbody> 363 <row> 364 <entry valign="top" morerows="1"><screen>std::string to_simple_string(date_period dp)</screen></entry> 365 <entry>To <code>[YYYY-mmm-DD/YYYY-mmm-DD]</code> string where <code>mmm</code> is 3 char month name.</entry> 366 </row> 367 <row> 368 <entry><screen>[2002-Jan-01/2002-Jan-31]</screen></entry> 369 </row> 370 </tbody> 371 </tgroup> 372 </informaltable> 373 374 375 <anchor id="period_operators" /> 376 <bridgehead renderas="sect3">Operators</bridgehead> 377 <informaltable frame="all"> 378 <tgroup cols="2"> 379 <thead> 380 <row> 381 <entry valign="top" morerows="1">Syntax</entry> 382 <entry>Description</entry> 383 </row> 384 <row> 385 <entry>Example</entry> 386 </row> 387 </thead> 388 <tbody> 389 <row> 390 <entry valign="top" morerows="1"><screen>operator<<</screen></entry> 391 <entry>ostream operator for date_period. Uses facet to format time points. Typical output: [2002-Jan-01/2002-Jan-31].</entry> 392 </row> 393 <row> 394 <entry><screen>std::cout << dp << std::endl;</screen></entry> 395 </row> 396 397 <row> 398 <entry valign="top" morerows="1"><screen>operator>></screen></entry> 399 <entry>istream operator for date_period. Uses facet to parse time points.</entry> 400 </row> 401 <row> 402 <entry><screen>"[2002-Jan-01/2002-Jan-31]"</screen></entry> 403 </row> 404 405 <row> 406 <entry valign="top" morerows="1"><screen>operator==, operator!=, 407operator>, operator<</screen> 408 </entry> 409 <entry>A full complement of comparison operators</entry> 410 </row> 411 <row> 412 <entry><screen>dp1 == dp2, etc</screen></entry> 413 </row> 414 415 <row> 416 <entry valign="top" morerows="1"><screen>operator<</screen></entry> 417 <entry>True if dp1.end() less than dp2.begin()</entry> 418 </row> 419 <row> 420 <entry><screen>dp1 < dp2, etc</screen></entry> 421 </row> 422 423 <row> 424 <entry valign="top" morerows="1"><screen>operator></screen></entry> 425 <entry>True if dp1.begin() greater than dp2.end()</entry> 426 </row> 427 <row> 428 <entry><screen>dp1 > dp2, etc</screen></entry> 429 </row> 430 </tbody> 431 </tgroup> 432 </informaltable> 433 434</section> 435