source: downloads/boost_1_34_1/libs/date_time/xmldoc/date_period.xml @ 33

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 
"../../../tools/boostbook/dtd/boostbook.dtd">

<!-- Copyright (c) 2001-2006 CrystalClear Software, Inc.
     Subject to the Boost Software License, Version 1.0. 
     (See accompanying file LICENSE-1.0 or  http://www.boost.org/LICENSE-1.0)
-->

<section id="date_time.gregorian.date_period">
  <title>Date Period</title>

  <link linkend="period_intro">Introduction</link> --
  <link linkend="period_header">Header</link> --
  <link linkend="period_construction">Construction</link> --
  <link linkend="date_period_mutators">Mutators</link> --
  <link linkend="period_accessors">Accessors</link> --
  <link linkend="period_convert_to_string">Convert to String</link> --
  <link linkend="period_operators">Operators</link>

  <anchor id="period_intro" />
  <bridgehead renderas="sect3">Introduction</bridgehead>
  <para>
    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.
  </para>
  <para>
    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.
  </para>
  <para>
    Date periods used in combination with infinity values have the ability to represent complex concepts such as 'until further notice'. 
  </para>

  <anchor id="period_header" />
  <bridgehead renderas="sect3">Header</bridgehead>
  <para>
    <programlisting>#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o
or
#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types</programlisting>
  </para>

  <anchor id="period_construction" />
  <bridgehead renderas="sect3">Construction</bridgehead>
  <informaltable frame="all">
    <tgroup cols="2">
      <thead>
        <row>
          <entry valign="top" morerows="1">Syntax</entry>
          <entry>Description</entry>
        </row>
        <row>
          <entry>Example</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry valign="top" morerows="1"><screen>date_period(date, date)</screen></entry>
          <entry>Create a period as [begin, end). If end is &lt;= begin then the period will be invalid.</entry>
        </row>
        <row>
          <entry><screen>date_period dp(date(2002,Jan,10),
               date(2002,Jan,12));</screen></entry>
        </row>

        <row>
          <entry valign="top" morerows="1"><screen>date_period(date, days)</screen></entry>
          <entry>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.</entry>
        </row>
        <row>
          <entry><screen>date_period dp(date(2002,Jan,10),
               days(2));</screen></entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>date_period(date_period)</screen></entry>
          <entry> Copy constructor</entry>
        </row>
        <row>
          <entry><screen>date_period dp1(dp);</screen></entry>
        </row>
      </tbody>
    </tgroup>
  </informaltable>


  <anchor id="date_period_mutators" />
  <bridgehead renderas="sect3">Mutators</bridgehead>
  <para>
    <informaltable frame="all">
      <tgroup cols="2">
        <thead>
          <row>
            <entry valign="top" morerows="1">Syntax</entry>
            <entry>Description</entry>
          </row>
          <row>
            <entry>Example</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry valign="top" morerows="1"><screen>date_period shift(days)</screen></entry>
            <entry>Add duration to both begin and end.</entry>
          </row>
          <row>
            <entry>
              <screen>
date_period dp(date(2005,Jan,1), days(3));
dp.shift(days(3)); 
// dp == 2005-Jan-04 to 2005-Jan-07
             </screen>
            </entry>
          </row>

          <row>
            <entry valign="top" morerows="1"><screen>date_period expand(days)</screen></entry>
            <entry>Add duration to both begin and end.</entry>
          </row>
          <row>
              <screen>
date_period dp(date(2005,Jan,2), days(2));
dp.expand(days(1)); 
// dp == 2005-Jan-01 to 2005-Jan-04
             </screen>
          </row>

        </tbody>
      </tgroup>
    </informaltable>
  </para>


  <anchor id="period_accessors" />
  <bridgehead renderas="sect3">Accessors</bridgehead>
  <informaltable frame="all">
    <tgroup cols="2">
      <thead>
        <row>
          <entry valign="top" morerows="1">Syntax</entry>
          <entry>Description</entry>
        </row>
        <row>
          <entry>Example</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry valign="top" morerows="1"><screen>date begin()</screen></entry>
          <entry> Return first day of period.</entry>
        </row>
        <row>
          <entry><screen>date_period dp(date(2002,Jan,1),
               date(2002,Jan,10));
dp.begin() --> 2002-Jan-01</screen>
          </entry>
        </row>

        <row>
          <entry valign="top" morerows="1"><screen>date last()</screen></entry>
          <entry>Return last date in the period</entry>
        </row>
        <row>
          <entry><screen>date_period dp(date(2002,Jan,1),
               date(2002,Jan,10));
dp.last() --> 2002-Jan-09</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>date end()</screen></entry>
          <entry>Return one past the last in period</entry>
        </row>
        <row>
          <entry><screen>date_period dp(date(2002,Jan,1),
               date(2002,Jan,10));
dp.end() --> 2002-Jan-10</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>days length()</screen></entry>
          <entry>Return the length of the date_period</entry>
        </row>
        <row>
          <entry><screen>date_period dp(date(2002,Jan,1),
               days(2));
dp.length() --> 2</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>bool is_null()</screen></entry>
          <entry>True if period is not well formed. eg: end less than or equal to begin.</entry>
        </row>
        <row>
          <entry><screen>date_period dp(date(2002,Jan,10),
               date(2002,Jan,1));
dp.begin() --> true</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>bool contains(date)</screen></entry>
          <entry>True if date is within the period. Zero length periods cannot contain any points</entry>
        </row>
        <row>
          <entry><screen>date d(2002,Jan,1);
date_period dp(d, date(2002,Jan,10));
dp.contains(date(2002,Jan,2));// true
date_period dp2(d, d);
dp.contains(date(2002,Jan,1));// false</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>bool contains(date_period)</screen></entry>
          <entry>True if date period is within the period</entry>
        </row>
        <row>
          <entry><screen>date_period dp1(date(2002,Jan,1),
                date(2002,Jan,10));
date_period dp2(date(2002,Jan,2),
                date(2002,Jan,3));
dp1.contains(dp2) --> true
dp2.contains(dp1) --> false</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>bool intersects(date_period)</screen></entry>
          <entry>True if periods overlap</entry>
        </row>
        <row>
          <entry><screen>date_period dp1(date(2002,Jan,1),
               date(2002,Jan,10));
date_period dp2(date(2002,Jan,2),
               date(2002,Jan,3));
dp2.intersects(dp1) --> true</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>date_period intersection(date_period)</screen></entry>
          <entry>Calculate the intersection of 2 periods. Null if no intersection.</entry>
        </row>
        <row>
          <entry><screen>date_period dp1(date(2002,Jan,1),
                date(2002,Jan,10));
date_period dp2(date(2002,Jan,2),
                date(2002,Jan,3));
dp2.intersection(dp1) --> dp2</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>date_period is_adjacent(date_period)</screen></entry>
          <entry>Check if two periods are adjacent, but not overlapping.</entry>
        </row>
        <row>
          <entry><screen>date_period dp1(date(2002,Jan,1),
                date(2002,Jan,3));
date_period dp2(date(2002,Jan,3),
                date(2002,Jan,10));
dp2.is_adjacent(dp1) --> true</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>date_period is_after(date)</screen></entry>
          <entry>Determine the period is after a given date.</entry>
        </row>
        <row>
          <entry><screen>date_period dp1(date(2002,Jan,10),
                date(2002,Jan,30));
date d(2002,Jan,3);
dp1.is_after(d) --> true</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>date_period is_before(date)</screen></entry>
          <entry>Determine the period is before a given date.</entry>
        </row>
        <row>
          <entry><screen>date_period dp1(date(2002,Jan,1),
                date(2002,Jan,3));
date d(2002,Jan,10);
dp1.is_before(d) --> true</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>date_period merge(date_period)</screen></entry>
          <entry>Returns union of two periods. Null if no intersection.</entry>
        </row>
        <row>
          <entry><screen>date_period dp1(date(2002,Jan,1),
                date(2002,Jan,10));
date_period dp2(date(2002,Jan,9),
                date(2002,Jan,31));
dp2.merge(dp1)
// 2002-Jan-01/2002-Jan-31</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>date_period span(date_period)</screen></entry>
          <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>
        </row>
        <row>
          <entry><screen>
date_period dp1(date(2002,Jan,1),
                date(2002,Jan,5));
date_period dp2(date(2002,Jan,9),
                date(2002,Jan,31));
dp2.span(dp1); // 2002-Jan-01/2002-Jan-31</screen>
          </entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>date_period shift(days)</screen></entry>
          <entry>Add duration to both begin and end.</entry>
        </row>
        <row>
          <entry><screen>date_period dp1(date(2002,Jan,1),
                date(2002,Jan,10));
dp1.shift(days(1));
// 2002-Jan-02/2002-Jan-11</screen>
          </entry>
        </row>

        <row>
          <entry valign="top" morerows="1"><screen>date_period expand(days)</screen></entry>
          <entry>Subtract duration from begin and add duration to end.</entry>
        </row>
        <row>
          <entry><screen>date_period dp1(date(2002,Jan,4),
                date(2002,Jan,10));
dp1.expand(days(2));
// 2002-Jan-02/2002-Jan-12</screen>
          </entry>
        </row>
      </tbody>
    </tgroup>
  </informaltable>


  <anchor id="period_convert_to_string" />
  <bridgehead renderas="sect3">Convert to String</bridgehead>
  <informaltable frame="all">
    <tgroup cols="2">
      <thead>
        <row>
          <entry valign="top" morerows="1">Syntax</entry>
          <entry>Description</entry>
        </row>
        <row>
          <entry>Example</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry valign="top" morerows="1"><screen>std::string to_simple_string(date_period dp)</screen></entry>
          <entry>To <code>[YYYY-mmm-DD/YYYY-mmm-DD]</code> string where <code>mmm</code> is 3 char month name.</entry>
        </row>
        <row>
          <entry><screen>[2002-Jan-01/2002-Jan-31]</screen></entry>
        </row>
      </tbody>
    </tgroup>
  </informaltable>


  <anchor id="period_operators" />
  <bridgehead renderas="sect3">Operators</bridgehead>
  <informaltable frame="all">
    <tgroup cols="2">
      <thead>
        <row>
          <entry valign="top" morerows="1">Syntax</entry>
          <entry>Description</entry>
        </row>
        <row>
          <entry>Example</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry valign="top" morerows="1"><screen>operator&lt;&lt;</screen></entry>
          <entry>ostream operator for date_period. Uses facet to format time points. Typical output: [2002-Jan-01/2002-Jan-31].</entry>
        </row>
        <row>
          <entry><screen>std::cout &lt;&lt; dp &lt;&lt; std::endl;</screen></entry>
        </row>

        <row>
          <entry valign="top" morerows="1"><screen>operator&gt;&gt;</screen></entry>
          <entry>istream operator for date_period. Uses facet to parse time points.</entry>
        </row>
        <row>
          <entry><screen>"[2002-Jan-01/2002-Jan-31]"</screen></entry>
        </row>

        <row>
          <entry valign="top" morerows="1"><screen>operator==, operator!=,
operator&gt;, operator&lt;</screen>
          </entry>
          <entry>A full complement of comparison operators</entry>
        </row>
        <row>
          <entry><screen>dp1 == dp2, etc</screen></entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>operator&lt;</screen></entry>
          <entry>True if dp1.end() less than dp2.begin()</entry>
        </row>
        <row>
          <entry><screen>dp1 &lt; dp2, etc</screen></entry>
        </row>
        
        <row>
          <entry valign="top" morerows="1"><screen>operator&gt;</screen></entry>
          <entry>True if dp1.begin() greater than dp2.end()</entry>
        </row>
        <row>
          <entry><screen>dp1 &gt; dp2, etc</screen></entry>
        </row>
      </tbody>
    </tgroup>
  </informaltable>

</section>