boost/date_time/local_time_adjustor.hpp

0001 #ifndef DATE_TIME_LOCAL_TIME_ADJUSTOR_HPP__
0002 #define DATE_TIME_LOCAL_TIME_ADJUSTOR_HPP__
0003
0004 /* Copyright (c) 2002,2003 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
0009  * $Date$
0010  */
0011
0012 /*! @file local_time_adjustor.hpp
0013   Time adjustment calculations for local times
0014 */
0015
0016 #include <stdexcept>
0017 #include <boost/throw_exception.hpp>
0018 #include <boost/date_time/compiler_config.hpp>
0019 #include <boost/date_time/date_generators.hpp>
0020 #include <boost/date_time/dst_rules.hpp>
0021 #include <boost/date_time/time_defs.hpp> // boost::date_time::dst_flags
0022 #include <boost/date_time/special_defs.hpp> // not_a_date_time
0023
0024 namespace boost {
0025   namespace date_time {
0026
0027
0028     //! Provides a base offset adjustment from utc
0029     template<class time_duration_type,
0030              short hours, unsigned short minutes = 0>
0031     class utc_adjustment
0032     {
0033     public:
0034       static time_duration_type local_to_utc_base_offset()
0035       {
0036         time_duration_type td(hours,minutes,0);
0037         return td.invert_sign();
0038       }
0039       static time_duration_type utc_to_local_base_offset()
0040       {
0041         return time_duration_type(hours,minutes,0);
0042       }
0043     };
0044
0045
0046
0047     //! Allow sliding utc adjustment with fixed dst rules
0048     template<class time_type, class dst_rules>
0049     class dynamic_local_time_adjustor : public dst_rules
0050     {
0051     public:
0052       typedef typename time_type::time_duration_type time_duration_type;
0053       typedef typename time_type::date_type date_type;
0054
0055       dynamic_local_time_adjustor(time_duration_type utc_offset) :
0056         utc_offset_(utc_offset)
0057       {}
0058
0059       //! Presumes local time
0060       time_duration_type utc_offset(bool is_dst)
0061       {
0062         if (is_dst) {
0063           return utc_offset_ + this->dst_offset();
0064         }
0065         else {
0066           return utc_offset_;
0067         }
0068
0069       }
0070     private:
0071       time_duration_type utc_offset_;
0072
0073     };
0074
0075
0076
0077     //! Embed the rules for local time adjustments at compile time
0078     template<class time_type, class dst_rules, class utc_offset_rules>
0079     class static_local_time_adjustor: public dst_rules, public utc_offset_rules
0080     {
0081     public:
0082       typedef typename time_type::time_duration_type time_duration_type;
0083       typedef typename time_type::date_type date_type;
0084
0085       //! Calculates the offset from a utc time to local based on dst and utc offset
0086       /*! @param t UTC time to calculate offset to local time
0087        *  This adjustment depends on the following observations about the
0088        *  workings of the DST boundary offset.  Since UTC time labels are
0089        *  monotonically increasing we can determine if a given local time
0090        *  is in DST or not and therefore adjust the offset appropriately.
0091        *
0092        *  The logic is as follows.  Starting with UTC time use the offset to
0093        *  create a label for an non-dst adjusted local time.  Then call
0094        *  dst_rules::local_is_dst with the non adjust local time.  The
0095        *  results of this function will either unabiguously decide that
0096        *  the initial local time is in dst or return an illegal or
0097        *  ambiguous result.  An illegal result only occurs at the end
0098        *  of dst (where labels are skipped) and indicates that dst has
0099        *  ended.  An ambiguous result means that we need to recheck by
0100        *  making a dst adjustment and then rechecking.  If the dst offset
0101        *  is added to the utc time and the recheck proves non-ambiguous
0102        *  then we are past the boundary.  If it is still ambiguous then
0103        *  we are ahead of the boundary and dst is still in effect.
0104        *
0105        *  TODO -- check if all dst offsets are positive.  If not then
0106        *  the algorithm needs to check for this and reverse the
0107        *  illegal/ambiguous logic.
0108        */
0109       static time_duration_type utc_to_local_offset(const time_type& t)
0110       {
0111         //get initial local time guess by applying utc offset
0112         time_type initial = t + utc_offset_rules::utc_to_local_base_offset();
0113         time_is_dst_result dst_flag =
0114           dst_rules::local_is_dst(initial.date(), initial.time_of_day());
0115         switch(dst_flag) {
0116         case is_in_dst:        return utc_offset_rules::utc_to_local_base_offset() + dst_rules::dst_offset();
0117         case is_not_in_dst:    return utc_offset_rules::utc_to_local_base_offset();
0118         case invalid_time_label:return utc_offset_rules::utc_to_local_base_offset() + dst_rules::dst_offset();
0119         case ambiguous: {
0120           time_type retry = initial + dst_rules::dst_offset();
0121           dst_flag = dst_rules::local_is_dst(retry.date(), retry.time_of_day());
0122           //if still ambibuous then the utc time still translates to a dst time
0123           if (dst_flag == ambiguous) {
0124             return utc_offset_rules::utc_to_local_base_offset() + dst_rules::dst_offset();
0125           }
0126           // we are past the dst boundary
0127           else {
0128             return utc_offset_rules::utc_to_local_base_offset();
0129           }
0130         }
0131         }//case
0132         //TODO  better exception type
0133         boost::throw_exception(std::out_of_range("Unreachable case"));
0134         BOOST_DATE_TIME_UNREACHABLE_EXPRESSION(return time_duration_type(not_a_date_time)); // should never reach
0135       }
0136
0137       //! Get the offset to UTC given a local time
0138       static time_duration_type local_to_utc_offset(const time_type& t,
0139                                                     date_time::dst_flags dst=date_time::calculate)
0140       {
0141         switch (dst) {
0142         case is_dst:
0143           return utc_offset_rules::local_to_utc_base_offset() - dst_rules::dst_offset();
0144         case not_dst:
0145           return utc_offset_rules::local_to_utc_base_offset();
0146         case calculate:
0147           time_is_dst_result res =
0148             dst_rules::local_is_dst(t.date(), t.time_of_day());
0149           switch(res) {
0150           case is_in_dst:      return utc_offset_rules::local_to_utc_base_offset() - dst_rules::dst_offset();
0151           case is_not_in_dst:      return utc_offset_rules::local_to_utc_base_offset();
0152           case ambiguous:          return utc_offset_rules::local_to_utc_base_offset();
0153           case invalid_time_label: break;
0154           }
0155         }
0156         boost::throw_exception(std::out_of_range("Time label invalid"));
0157         BOOST_DATE_TIME_UNREACHABLE_EXPRESSION(return time_duration_type(not_a_date_time)); // should never reach
0158       }
0159
0160
0161     private:
0162
0163     };
0164
0165     void dummy_to_prevent_msvc6_ice(); //why ask why?
0166
0167     //! Template that simplifies the creation of local time calculator
0168     /*! Use this template to create the timezone to utc convertors as required.
0169      *
0170      *  This class will also work for other regions that don't use dst and
0171      *  have a utc offset which is an integral number of hours.
0172      *
0173      *  <b>Template Parameters</b>
0174      *  -time_type  -- Time class to use
0175      *  -utc_offset -- Number hours local time is adjust from utc
0176      *  -use_dst -- true (default) if region uses dst, false otherwise
0177      *  For example:
0178      *  @code
0179      *  //eastern timezone is utc-5
0180      typedef date_time::local_adjustor<ptime, -5, us_dst> us_eastern;
0181      typedef date_time::local_adjustor<ptime, -6, us_dst> us_central;
0182      typedef date_time::local_adjustor<ptime, -7, us_dst> us_mountain;
0183      typedef date_time::local_adjustor<ptime, -8, us_dst> us_pacific;
0184      typedef date_time::local_adjustor<ptime, -7, no_dst> us_arizona;
0185      @endcode
0186
0187     */
0188     template<class time_type, short utc_offset, class dst_rule>
0189     class local_adjustor
0190     {
0191     public:
0192       typedef typename time_type::time_duration_type time_duration_type;
0193       typedef typename time_type::date_type date_type;
0194       typedef static_local_time_adjustor<time_type,
0195                                          dst_rule,
0196                                          utc_adjustment<time_duration_type,
0197                                                         utc_offset> > dst_adjustor;
0198       //! Convert a utc time to local time
0199       static time_type utc_to_local(const time_type& t)
0200       {
0201         time_duration_type td = dst_adjustor::utc_to_local_offset(t);
0202         return t + td;
0203       }
0204       //! Convert a local time to utc
0205       static time_type local_to_utc(const time_type& t,
0206                                     date_time::dst_flags dst=date_time::calculate)
0207       {
0208         time_duration_type td = dst_adjustor::local_to_utc_offset(t, dst);
0209         return t + td;
0210       }
0211     };
0212
0213
0214   } } //namespace date_time
0215
0216
0217
0218 #endif