libs/date_time/xmldoc/date_algorithms.xml

   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-2005 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_algorithms">
  11   <title>Date Generators/Algorithms</title>
  12   <bridgehead renderas="sect2">Date Generators/Algorithms</bridgehead>
  13   <link linkend="algo_intro">Introduction</link> --
  14   <link linkend="algo_header">Header</link> --
  15   <link linkend="algo_overview">Class Overview</link> --
  16   <link linkend="algo_func_overview">Function Overview</link>
  17
  18   <anchor id="algo_intro" />
  19   <bridgehead renderas="sect3">Introduction</bridgehead>
  20   <para>
  21     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.
  22     <emphasis>Note</emphasis>: 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
  23   </para>
  24   <para>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.
  25   </para>
  26   <para>All date generator classes and functions are in the boost::gregorian namespace.
  27   </para>
  28   <para>
  29     The <link linkend="date_time.examples.print_holidays">print holidays</link> example shows a detailed usage example.
  30   </para>
  31
  32   <anchor id="algo_header" />
  33   <bridgehead renderas="sect3">Header</bridgehead>
  34   <para><programlisting>#include "boost/date_time/gregorian/gregorian.hpp"</programlisting>
  35   </para>
  36
  37   <anchor id="algo_overview" />
  38   <bridgehead renderas="sect3">Overview</bridgehead>
  39   <informaltable frame="all">
  40     <tgroup cols="2">
  41       <thead>
  42         <row>
  43           <entry valign="top" morerows="1">Class and get_date Parameter</entry>
  44           <entry>Description</entry>
  45         </row>
  46         <row>
  47           <entry>Example</entry>
  48         </row>
  49       </thead>
  50       <tbody>
  51         <row>
  52           <entry valign="top" morerows="1"><screen>year_based_generator
  53 date get_date(greg_year year)</screen></entry>
  54           <entry>A unifying (abstract) date_generator base type for: <code>partial_date</code>, <code>nth_day_of_the_week_in_month</code>, <code>first_day_of_the_week_in_month</code>, and <code>last_day_of_the_week_in_month</code>.</entry>
  55         </row>
  56         <row>
  57           <entry>The <link linkend="date_time.examples.print_holidays">print holidays</link> example shows a detailed usage example.</entry>
  58         </row>
  59
  60         <row>
  61           <entry valign="top" morerows="1"><screen>last_day_of_the_week_in_month(greg_weekday,
  62                               greg_month)
  63 date get_date(greg_year year)</screen></entry>
  64           <entry>Calculate something like last Monday of January</entry>
  65         </row>
  66         <row>
  67           <entry><screen>last_day_of_the_week_in_month lwdm(Monday,Jan);
  68 date d = lwdm.get_date(2002);
  69 //2002-Jan-28</screen>
  70           </entry>
  71         </row>
  72
  73         <row>
  74           <entry valign="top" morerows="1"><screen>first_day_of_the_week_in_month(greg_weekday,
  75                                greg_month)
  76 date get_date(greg_year year)</screen></entry>
  77           <entry>Calculate something like first Monday of January</entry>
  78         </row>
  79         <row>
  80           <entry><screen>first_day_of_the_week_in_month fdm(Monday,Jan);
  81 date d = fdm.get_date(2002);
  82 //2002-Jan-07</screen>
  83           </entry>
  84         </row>
  85
  86         <row>
  87           <entry valign="top" morerows="1"><screen>nth_day_of_the_week_in_month(week_num,
  88                              greg_weekday,
  89                              greg_month)
  90 date get_date(greg_year year)</screen></entry>
  91           <entry><code>week_num</code> is a public enum member of <code>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)</entry>
  92         </row>
  93         <row>
  94           <entry><screen>typedef nth_day_of_the_week_in_month nth_dow;
  95 nth_dow ndm(nth_dow::third, Monday,Jan);
  96 date d = ndm.get_date(2002);
  97 //2002-Jan-21</screen>
  98           </entry>
  99         </row>
 100
 101         <row>
 102           <entry valign="top" morerows="1"><screen>partial_date(greg_day, greg_month)
 103 date get_date(greg_year year)</screen></entry>
 104           <entry>Generates a date by applying the year to the given month and day.</entry>
 105         </row>
 106         <row>
 107           <entry><screen>partial_date pd(1,Jan);
 108 date d = pd.get_date(2002);
 109 //2002-Jan-01</screen>
 110           </entry>
 111         </row>
 112
 113         <row>
 114           <entry valign="top" morerows="1"><screen>first_day_of_the_week_after(greg_weekday)
 115 date get_date(date d)</screen></entry>
 116           <entry>Calculate something like First Sunday after Jan 1,2002</entry>
 117         </row>
 118         <row>
 119           <entry><screen>first_day_of_the_week_after fdaf(Monday);
 120 date d = fdaf.get_date(date(2002,Jan,1));
 121 //2002-Jan-07</screen>
 122           </entry>
 123         </row>
 124
 125         <row>
 126           <entry valign="top" morerows="1"><screen>first_day_of_the_week_before(greg_weekday)
 127 date get_date(date d)</screen></entry>
 128           <entry>Calculate something like First Monday before Feb 1,2002</entry>
 129         </row>
 130         <row>
 131           <entry><screen>first_day_of_the_week_before fdbf(Monday);
 132 date d = fdbf.get_date(date(2002,Feb,1));
 133 //2002-Jan-28</screen>
 134           </entry>
 135         </row>
 136       </tbody>
 137     </tgroup>
 138   </informaltable>
 139
 140
 141   <anchor id="algo_func_overview" />
 142   <bridgehead renderas="sect3">Function Overview</bridgehead>
 143   <informaltable frame="all">
 144     <tgroup cols="2">
 145       <thead>
 146         <row>
 147           <entry valign="top" morerows="1">Function Prototype</entry>
 148           <entry>Description</entry>
 149         </row>
 150         <row>
 151           <entry>Example</entry>
 152         </row>
 153       </thead>
 154       <tbody>
 155         <row>
 156           <entry valign="top" morerows="1"><screen>days days_until_weekday date, greg_weekday)</screen></entry>
 157           <entry> Calculates the number of days from given date until given weekday.</entry>
 158         </row>
 159         <row>
 160           <entry><screen>date d(2004,Jun,1); // Tuesday
 161 greg_weekday gw(Friday);
 162 days_until_weekday(d, gw); // 3 days</screen>
 163           </entry>
 164         </row>
 165
 166         <row>
 167           <entry valign="top" morerows="1"><screen>days days_before_weekday(date, greg_weekday)</screen></entry>
 168           <entry> Calculates the number of day from given date to previous given weekday.</entry>
 169         </row>
 170         <row>
 171           <entry><screen>date d(2004,Jun,1); // Tuesday
 172 greg_weekday gw(Friday);
 173 days_before_weekday(d, gw); // 4 days</screen>
 174           </entry>
 175         </row>
 176
 177         <row>
 178           <entry valign="top" morerows="1"><screen>date next_weekday(date, greg_weekday)</screen></entry>
 179           <entry> Generates a date object representing the date of the following weekday from the given date.</entry>
 180         </row>
 181         <row>
 182           <entry><screen>date d(2004,Jun,1); // Tuesday
 183 greg_weekday gw(Friday);
 184 next_weekday(d, gw); // 2004-Jun-4</screen>
 185           </entry>
 186         </row>
 187
 188         <row>
 189           <entry valign="top" morerows="1"><screen>date previous_weekday(date, greg_weekday)</screen></entry>
 190           <entry> Generates a date object representing the date of the previous weekday from the given date.</entry>
 191         </row>
 192         <row>
 193           <entry><screen>date d(2004,Jun,1); // Tuesday
 194 greg_weekday gw(Friday);
 195 previous_weekday(d, gw); // 2004-May-28</screen>
 196           </entry>
 197         </row>
 198       </tbody>
 199     </tgroup>
 200   </informaltable>
 201
 202 </section>