boost/date_time/date_generators.hpp

0001 #ifndef DATE_TIME_DATE_GENERATORS_HPP__
0002 #define DATE_TIME_DATE_GENERATORS_HPP__
0003
0004 /* Copyright (c) 2002,2003,2005 CrystalClear Software, Inc.
0005  * Use, modification and distribution is subject to the
0006  * Boost Software License, Version 1.0. (See accompanying
0007  * file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
0008  * Author: Jeff Garland, Bart Garst
0009  * $Date$
0010  */
0011
0012 /*! @file date_generators.hpp
0013   Definition and implementation of date algorithm templates
0014 */
0015
0016 #include <sstream>
0017 #include <stdexcept>
0018 #include <boost/throw_exception.hpp>
0019 #include <boost/date_time/date.hpp>
0020 #include <boost/date_time/compiler_config.hpp>
0021
0022 namespace boost {
0023 namespace date_time {
0024
0025   //! Base class for all generators that take a year and produce a date.
0026   /*! This class is a base class for polymorphic function objects that take
0027     a year and produce a concrete date.
0028     @tparam date_type The type representing a date.  This type must
0029     export a calender_type which defines a year_type.
0030   */
0031   template<class date_type>
0032   class year_based_generator
0033   {
0034   public:
0035     typedef typename date_type::calendar_type calendar_type;
0036     typedef typename calendar_type::year_type        year_type;
0037     year_based_generator() {}
0038     virtual ~year_based_generator() {}
0039     virtual date_type get_date(year_type y) const = 0;
0040     //! Returns a string for use in a POSIX time_zone string
0041     virtual std::string to_string() const = 0;
0042   };
0043
0044   //! Generates a date by applying the year to the given month and day.
0045   /*!
0046     Example usage:
0047     @code
0048     partial_date pd(1, Jan);
0049     partial_date pd2(70);
0050     date d = pd.get_date(2002); //2002-Jan-01
0051     date d2 = pd2.get_date(2002); //2002-Mar-10
0052     @endcode
0053     \ingroup date_alg
0054   */
0055   template<class date_type>
0056  class partial_date : public year_based_generator<date_type>
0057  {
0058  public:
0059    typedef typename date_type::calendar_type calendar_type;
0060    typedef typename calendar_type::day_type         day_type;
0061    typedef typename calendar_type::month_type       month_type;
0062    typedef typename calendar_type::year_type        year_type;
0063    typedef typename date_type::duration_type        duration_type;
0064    typedef typename duration_type::duration_rep     duration_rep;
0065    partial_date(day_type d, month_type m) :
0066      day_(d),
0067      month_(m)
0068    {}
0069    //! Partial date created from number of days into year. Range 1-366
0070    /*! Allowable values range from 1 to 366. 1=Jan1, 366=Dec31. If argument
0071     * exceeds range, partial_date will be created with closest in-range value.
0072     * 60 will always be Feb29, if get_date() is called with a non-leap year
0073     * an exception will be thrown */
0074    partial_date(duration_rep days) :
0075      day_(1), // default values
0076      month_(1)
0077    {
0078      date_type d1(2000,1,1);
0079      if(days > 1) {
0080        if(days > 366) // prevents wrapping
0081        {
0082          days = 366;
0083        }
0084        days = days - 1;
0085        duration_type dd(days);
0086        d1 = d1 + dd;
0087      }
0088      day_ = d1.day();
0089      month_ = d1.month();
0090    }
0091    //! Return a concrete date when provided with a year specific year.
0092    /*! Will throw an 'invalid_argument' exception if a partial_date object,
0093     * instantiated with Feb-29, has get_date called with a non-leap year.
0094     * Example:
0095     * @code
0096     * partial_date pd(29, Feb);
0097     * pd.get_date(2003); // throws invalid_argument exception
0098     * pg.get_date(2000); // returns 2000-2-29
0099     * @endcode
0100          */
0101    date_type get_date(year_type y) const BOOST_OVERRIDE
0102    {
0103      if((day_ == 29) && (month_ == 2) && !(calendar_type::is_leap_year(y))) {
0104        std::ostringstream ss;
0105        ss << "No Feb 29th in given year of " << y << ".";
0106        boost::throw_exception(std::invalid_argument(ss.str()));
0107      }
0108      return date_type(y, month_, day_);
0109    }
0110    date_type operator()(year_type y) const
0111    {
0112      return get_date(y);
0113      //return date_type(y, month_, day_);
0114    }
0115    bool operator==(const partial_date& rhs) const
0116    {
0117      return (month_ == rhs.month_) && (day_ == rhs.day_);
0118    }
0119    bool operator<(const partial_date& rhs) const
0120    {
0121      if (month_ < rhs.month_) return true;
0122      if (month_ > rhs.month_) return false;
0123      //months are equal
0124      return (day_ < rhs.day_);
0125    }
0126
0127    // added for streaming purposes
0128    month_type month() const
0129    {
0130      return month_;
0131    }
0132    day_type day() const
0133    {
0134      return day_;
0135    }
0136
0137    //! Returns string suitable for use in POSIX time zone string
0138    /*! Returns string formatted with up to 3 digits:
0139     * Jan-01 == "0"
0140     * Feb-29 == "58"
0141     * Dec-31 == "365" */
0142    std::string to_string() const BOOST_OVERRIDE
0143    {
0144      std::ostringstream ss;
0145      date_type d(2004, month_, day_);
0146      unsigned short c = d.day_of_year();
0147      c--; // numbered 0-365 while day_of_year is 1 based...
0148      ss << c;
0149      return ss.str();
0150    }
0151  private:
0152    day_type day_;
0153    month_type month_;
0154  };
0155
0156   //! Returns nth arg as string. 1 -> "first", 2 -> "second", max is 5.
0157   inline const char* nth_as_str(int ele)
0158   {
0159     static const char* const _nth_as_str[] = {"out of range", "first", "second",
0160                                               "third", "fourth", "fifth"};
0161     if(ele >= 1 && ele <= 5) {
0162       return _nth_as_str[ele];
0163     }
0164     else {
0165       return _nth_as_str[0];
0166     }
0167   }
0168
0169   //! Useful generator functor for finding holidays
0170   /*! Based on the idea in Cal. Calc. for finding holidays that are
0171    *  the 'first Monday of September'. When instantiated with
0172    *  'fifth' kday of month, the result will be the last kday of month
0173    *  which can be the fourth or fifth depending on the structure of
0174    *  the month.
0175    *
0176    *  The algorithm here basically guesses for the first
0177    *  day of the month.  Then finds the first day of the correct
0178    *  type.  That is, if the first of the month is a Tuesday
0179    *  and it needs Wednesday then we simply increment by a day
0180    *  and then we can add the length of a week until we get
0181    *  to the 'nth kday'.  There are probably more efficient
0182    *  algorithms based on using a mod 7, but this one works
0183    *  reasonably well for basic applications.
0184    *  \ingroup date_alg
0185    */
0186   template<class date_type>
0187   class nth_kday_of_month : public year_based_generator<date_type>
0188   {
0189   public:
0190     typedef typename date_type::calendar_type calendar_type;
0191     typedef typename calendar_type::day_of_week_type  day_of_week_type;
0192     typedef typename calendar_type::month_type        month_type;
0193     typedef typename calendar_type::year_type         year_type;
0194     typedef typename date_type::duration_type        duration_type;
0195     enum week_num {first=1, second, third, fourth, fifth};
0196     nth_kday_of_month(week_num week_no,
0197                       day_of_week_type dow,
0198                       month_type m) :
0199       month_(m),
0200       wn_(week_no),
0201       dow_(dow)
0202     {}
0203     //! Return a concrete date when provided with a year specific year.
0204     date_type get_date(year_type y) const BOOST_OVERRIDE
0205     {
0206       date_type d(y, month_, 1); //first day of month
0207       duration_type one_day(1);
0208       duration_type one_week(7);
0209       while (dow_ != d.day_of_week()) {
0210         d = d + one_day;
0211       }
0212       int week = 1;
0213       while (week < wn_) {
0214         d = d + one_week;
0215         week++;
0216       }
0217       // remove wrapping to next month behavior
0218       if(d.month() != month_) {
0219         d = d - one_week;
0220       }
0221       return d;
0222     }
0223     // added for streaming
0224     month_type month() const
0225     {
0226       return month_;
0227     }
0228     week_num nth_week() const
0229     {
0230       return wn_;
0231     }
0232     day_of_week_type day_of_week() const
0233     {
0234       return dow_;
0235     }
0236     const char* nth_week_as_str() const
0237     {
0238       return nth_as_str(wn_);
0239     }
0240     //! Returns string suitable for use in POSIX time zone string
0241     /*! Returns a string formatted as "M4.3.0" ==> 3rd Sunday in April. */
0242     std::string to_string() const BOOST_OVERRIDE
0243     {
0244      std::ostringstream ss;
0245      ss << 'M'
0246        << static_cast<int>(month_) << '.'
0247        << static_cast<int>(wn_) << '.'
0248        << static_cast<int>(dow_);
0249      return ss.str();
0250     }
0251   private:
0252     month_type month_;
0253     week_num wn_;
0254     day_of_week_type dow_;
0255   };
0256
0257   //! Useful generator functor for finding holidays and daylight savings
0258   /*! Similar to nth_kday_of_month, but requires less paramters
0259    *  \ingroup date_alg
0260    */
0261   template<class date_type>
0262   class first_kday_of_month : public year_based_generator<date_type>
0263   {
0264   public:
0265     typedef typename date_type::calendar_type calendar_type;
0266     typedef typename calendar_type::day_of_week_type  day_of_week_type;
0267     typedef typename calendar_type::month_type        month_type;
0268     typedef typename calendar_type::year_type         year_type;
0269     typedef typename date_type::duration_type        duration_type;
0270     //!Specify the first 'Sunday' in 'April' spec
0271     /*!@param dow The day of week, eg: Sunday, Monday, etc
0272      * @param m The month of the year, eg: Jan, Feb, Mar, etc
0273      */
0274     first_kday_of_month(day_of_week_type dow, month_type m) :
0275       month_(m),
0276       dow_(dow)
0277     {}
0278     //! Return a concrete date when provided with a year specific year.
0279     date_type get_date(year_type year) const BOOST_OVERRIDE
0280     {
0281       date_type d(year, month_,1);
0282       duration_type one_day(1);
0283       while (dow_ != d.day_of_week()) {
0284         d = d + one_day;
0285       }
0286       return d;
0287     }
0288     // added for streaming
0289     month_type month() const
0290     {
0291       return month_;
0292     }
0293     day_of_week_type day_of_week() const
0294     {
0295       return dow_;
0296     }
0297     //! Returns string suitable for use in POSIX time zone string
0298     /*! Returns a string formatted as "M4.1.0" ==> 1st Sunday in April. */
0299     std::string to_string() const BOOST_OVERRIDE
0300     {
0301      std::ostringstream ss;
0302      ss << 'M'
0303        << static_cast<int>(month_) << '.'
0304        << 1 << '.'
0305        << static_cast<int>(dow_);
0306      return ss.str();
0307     }
0308   private:
0309     month_type month_;
0310     day_of_week_type dow_;
0311   };
0312
0313
0314
0315   //! Calculate something like Last Sunday of January
0316   /*! Useful generator functor for finding holidays and daylight savings
0317    *  Get the last day of the month and then calculate the difference
0318    *  to the last previous day.
0319    *  @tparam date_type A date class that exports day_of_week, month_type, etc.
0320    *  \ingroup date_alg
0321    */
0322   template<class date_type>
0323   class last_kday_of_month : public year_based_generator<date_type>
0324   {
0325   public:
0326     typedef typename date_type::calendar_type calendar_type;
0327     typedef typename calendar_type::day_of_week_type  day_of_week_type;
0328     typedef typename calendar_type::month_type        month_type;
0329     typedef typename calendar_type::year_type         year_type;
0330     typedef typename date_type::duration_type        duration_type;
0331     //!Specify the date spec like last 'Sunday' in 'April' spec
0332     /*!@param dow The day of week, eg: Sunday, Monday, etc
0333      * @param m The month of the year, eg: Jan, Feb, Mar, etc
0334      */
0335     last_kday_of_month(day_of_week_type dow, month_type m) :
0336       month_(m),
0337       dow_(dow)
0338     {}
0339     //! Return a concrete date when provided with a year specific year.
0340     date_type get_date(year_type year) const BOOST_OVERRIDE
0341     {
0342       date_type d(year, month_, calendar_type::end_of_month_day(year,month_));
0343       duration_type one_day(1);
0344       while (dow_ != d.day_of_week()) {
0345         d = d - one_day;
0346       }
0347       return d;
0348     }
0349     // added for streaming
0350     month_type month() const
0351     {
0352       return month_;
0353     }
0354     day_of_week_type day_of_week() const
0355     {
0356       return dow_;
0357     }
0358     //! Returns string suitable for use in POSIX time zone string
0359     /*! Returns a string formatted as "M4.5.0" ==> last Sunday in April. */
0360     std::string to_string() const BOOST_OVERRIDE
0361     {
0362       std::ostringstream ss;
0363       ss << 'M'
0364          << static_cast<int>(month_) << '.'
0365          << 5 << '.'
0366          << static_cast<int>(dow_);
0367       return ss.str();
0368     }
0369   private:
0370     month_type month_;
0371     day_of_week_type dow_;
0372    };
0373
0374
0375   //! Calculate something like "First Sunday after Jan 1,2002
0376   /*! Date generator that takes a date and finds kday after
0377    *@code
0378      typedef boost::date_time::first_kday_after<date> firstkdayafter;
0379      firstkdayafter fkaf(Monday);
0380      fkaf.get_date(date(2002,Feb,1));
0381    @endcode
0382    *  \ingroup date_alg
0383    */
0384   template<class date_type>
0385   class first_kday_after
0386   {
0387   public:
0388     typedef typename date_type::calendar_type calendar_type;
0389     typedef typename calendar_type::day_of_week_type day_of_week_type;
0390     typedef typename date_type::duration_type        duration_type;
0391     first_kday_after(day_of_week_type dow) :
0392       dow_(dow)
0393     {}
0394     //! Return next kday given.
0395     date_type get_date(date_type start_day) const
0396     {
0397       duration_type one_day(1);
0398       date_type d = start_day + one_day;
0399       while (dow_ != d.day_of_week()) {
0400         d = d + one_day;
0401       }
0402       return d;
0403     }
0404     // added for streaming
0405     day_of_week_type day_of_week() const
0406     {
0407       return dow_;
0408     }
0409   private:
0410     day_of_week_type dow_;
0411   };
0412
0413   //! Calculate something like "First Sunday before Jan 1,2002
0414   /*! Date generator that takes a date and finds kday after
0415    *@code
0416      typedef boost::date_time::first_kday_before<date> firstkdaybefore;
0417      firstkdaybefore fkbf(Monday);
0418      fkbf.get_date(date(2002,Feb,1));
0419    @endcode
0420    *  \ingroup date_alg
0421    */
0422   template<class date_type>
0423   class first_kday_before
0424   {
0425   public:
0426     typedef typename date_type::calendar_type calendar_type;
0427     typedef typename calendar_type::day_of_week_type day_of_week_type;
0428     typedef typename date_type::duration_type        duration_type;
0429     first_kday_before(day_of_week_type dow) :
0430       dow_(dow)
0431     {}
0432     //! Return next kday given.
0433     date_type get_date(date_type start_day) const
0434     {
0435       duration_type one_day(1);
0436       date_type d = start_day - one_day;
0437       while (dow_ != d.day_of_week()) {
0438         d = d - one_day;
0439       }
0440       return d;
0441     }
0442     // added for streaming
0443     day_of_week_type day_of_week() const
0444     {
0445       return dow_;
0446     }
0447   private:
0448     day_of_week_type dow_;
0449   };
0450
0451   //! Calculates the number of days until the next weekday
0452   /*! Calculates the number of days until the next weekday.
0453    * If the date given falls on a Sunday and the given weekday
0454    * is Tuesday the result will be 2 days */
0455   template<typename date_type, class weekday_type>
0456   inline
0457   typename date_type::duration_type days_until_weekday(const date_type& d, const weekday_type& wd)
0458   {
0459     typedef typename date_type::duration_type duration_type;
0460     duration_type wks(0);
0461     duration_type dd(wd.as_number() - d.day_of_week().as_number());
0462     if(dd.is_negative()){
0463       wks = duration_type(7);
0464     }
0465     return dd + wks;
0466   }
0467
0468   //! Calculates the number of days since the previous weekday
0469   /*! Calculates the number of days since the previous weekday
0470    * If the date given falls on a Sunday and the given weekday
0471    * is Tuesday the result will be 5 days. The answer will be a positive
0472    * number because Tuesday is 5 days before Sunday, not -5 days before. */
0473   template<typename date_type, class weekday_type>
0474   inline
0475   typename date_type::duration_type days_before_weekday(const date_type& d, const weekday_type& wd)
0476   {
0477     typedef typename date_type::duration_type duration_type;
0478     duration_type wks(0);
0479     duration_type dd(wd.as_number() - d.day_of_week().as_number());
0480     if(dd.days() > 0){
0481       wks = duration_type(7);
0482     }
0483     // we want a number of days, not an offset. The value returned must
0484     // be zero or larger.
0485     return (-dd + wks);
0486   }
0487
0488   //! Generates a date object representing the date of the following weekday from the given date
0489   /*! Generates a date object representing the date of the following
0490    * weekday from the given date. If the date given is 2004-May-9
0491    * (a Sunday) and the given weekday is Tuesday then the resulting date
0492    * will be 2004-May-11. */
0493   template<class date_type, class weekday_type>
0494   inline
0495   date_type next_weekday(const date_type& d, const weekday_type& wd)
0496   {
0497     return d + days_until_weekday(d, wd);
0498   }
0499
0500   //! Generates a date object representing the date of the previous weekday from the given date
0501   /*! Generates a date object representing the date of the previous
0502    * weekday from the given date. If the date given is 2004-May-9
0503    * (a Sunday) and the given weekday is Tuesday then the resulting date
0504    * will be 2004-May-4. */
0505   template<class date_type, class weekday_type>
0506   inline
0507   date_type previous_weekday(const date_type& d, const weekday_type& wd)
0508   {
0509     return d - days_before_weekday(d, wd);
0510   }
0511
0512 } } //namespace date_time
0513
0514 #endif