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 53date 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) 63date 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); 68date 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) 76date 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); 81date 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) 90date 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; 95nth_dow ndm(nth_dow::third, Monday,Jan); 96date 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) 103date 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); 108date 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) 115date 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); 120date 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) 127date 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); 132date 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 161greg_weekday gw(Friday); 162days_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 172greg_weekday gw(Friday); 173days_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. Can return the given date.</entry> 180 </row> 181 <row> 182 <entry><screen>date d(2004,Jun,1); // Tuesday 183greg_weekday gw1(Friday); 184greg_weekday gw2(Tuesday); 185next_weekday(d, gw1); // 2004-Jun-4 186next_weekday(d, gw2); // 2004-Jun-1 187 </screen> 188 </entry> 189 </row> 190 191 <row> 192 <entry valign="top" morerows="1"><screen>date previous_weekday(date, greg_weekday)</screen></entry> 193 <entry> Generates a date object representing the date of the previous weekday from the given date. Can return the given date. </entry> 194 </row> 195 <row> 196 <entry><screen>date d(2004,Jun,1); // Tuesday 197greg_weekday gw1(Friday); 198greg_weekday gw2(Tuesday); 199previous_weekday(d, gw1); // 2004-May-28 200previous_weekday(d, gw2); // 2004-Jun-1 201 </screen> 202 </entry> 203 </row> 204 </tbody> 205 </tgroup> 206 </informaltable> 207 208</section> 209