kstars/kstars/timezonerule.h

   1 /***************************************************************************
   2                           timezonerule.h  -  description
   3                              -------------------
   4     begin                : Tue Apr 2 2002
   5     copyright            : (C) 2002 by Jason Harris
   6     email                : kstars@30doradus.org
   7  ***************************************************************************/
   8
   9 /***************************************************************************
  10  *                                                                         *
  11  *   This program is free software; you can redistribute it and/or modify  *
  12  *   it under the terms of the GNU General Public License as published by  *
  13  *   the Free Software Foundation; either version 2 of the License, or     *
  14  *   (at your option) any later version.                                   *
  15  *                                                                         *
  16  ***************************************************************************/
  17
  18 #ifndef TIMEZONERULE_H
  19 #define TIMEZONERULE_H
  20
  21 /**@class TimeZoneRule
  22         *This class provides the information needed to determine whether Daylight
  23         *Savings Time (DST; a.k.a. "Summer Time") is currently active at a given
  24         *location.  There are (at least) 25 different "rules" which govern DST
  25         *around the world; a string identifying the appropriate rule is attachded
  26         *to each city in Cities.dat.
  27         *
  28         *The rules themselves are stored in the TZrulebook.dat file, which is read
  29         *on startup; each line in the file creates a TimeZoneRule object.
  30         *
  31         *TimeZoneRule consists of QStrings identifying the months and days on which
  32         *DST starts and ends, QTime objects identifying the time at which the
  33         *changes occur, and a double indicating the size of the offset in hours
  34         *(probably always 1.00).
  35         *
  36         *Month names should be the English three-letter abbreviation, uncapitalized.
  37         *Day names are either an integer indicating the calendar date (i.e., "15" is
  38         *the fifteenth of the month), or a number paired with a three-letter
  39         *abbreviation for a weekday.  This indicates the Nth weekday of the month
  40         *(i.e., "2sun" is the second Sunday of the Month).  Finally, the weekday
  41         *string on its own indicates the last weekday of the month (i.e.,
  42         *"mon" is the last Monday of the month).
  43         *
  44         *The isDSTActive(KStarsDateTime) function returns true if DST is active for the
  45         *DateTime given as an argument.
  46         *
  47         *The nextDSTChange(KStarsDateTime) function returns the KStarsDateTime of the moment
  48         *at which the next DST change will occur for the current location.
  49         *@author Jason Harris
  50         *@version 1.0
  51         */
  52
  53 #include <qstring.h>
  54 #include "kstarsdatetime.h"
  55
  56 class TimeZoneRule {
  57 public:
  58         /**Default Constructor. Makes the "empty" time zone rule (i.e., no DST correction)*/
  59         TimeZoneRule();
  60
  61         /**Constructor. Create a TZ rule according to the arguments.
  62                 *@p smonth the three-letter code for the month in which DST starts
  63                 *@p sday a string encoding the day on which DST starts (see the class description)
  64                 *@p stime the time at which DST starts
  65                 *@p rmonth the three-letter code for the month in which DST reverts
  66                 *@p rday a string encoding the day on which DST reverts (see the class description)
  67                 *@p rtime the time at which DST reverts
  68                 *@p offset the offset between normal time and DS time (always 1.00?)
  69                 */
  70         TimeZoneRule( const QString &smonth, const QString &sday, const QTime &stime,
  71                 const QString &rmonth, const QString &rday, const QTime &rtime, const double &offset=1.00 );
  72
  73         /**Destructor. (empty)*/
  74         ~TimeZoneRule();
  75
  76         /**Determine whether DST is in effect for the given DateTime, according to this rule
  77                 *@p date the date/time to test for DST
  78                 */
  79         bool isDSTActive( const KStarsDateTime &date );
  80
  81         /**@return TRUE if the rule is the "empty" TZ rule. */
  82         bool isEmptyRule() { return ( HourOffset == 0.0 ); }
  83
  84         /**@Toggle DST on/off.  The "activate" argument should probably be isDSTActive()
  85                 *@p activate if TRUE, then set DST active; otherwise, deactivate DST
  86                 */
  87         void setDST( bool activate=true );
  88
  89         /**@return the current Timezone offset, compared to the timezone's Standard Time.
  90                 *This is typically 0.0 if DST is inactive, and 1.0 if DST is active. */
  91         double deltaTZ() const { return dTZ; }
  92
  93 /**@Recalculate next dst change and if DST is active by a given local time with
  94         *timezone offset and time direction.
  95         *@param ltime the time to be tested
  96         *@param bool time_runs_forward time direction
  97         *@param automaticDSTchange is automatic DST change?
  98         */
  99         void reset_with_ltime( KStarsDateTime &ltime, const double TZoffset, const bool time_runs_forward,
 100                                                                                                 const bool automaticDSTchange = false );
 101
 102         /**@return computed value for next DST change in universal time.
 103                 */
 104         KStarsDateTime nextDSTChange() { return next_change_utc; }
 105
 106         /**@return computed value for next DST change in local time.
 107                 */
 108         KStarsDateTime nextDSTChange_LTime() { return next_change_ltime; }
 109
 110         /**@return TRUE if this rule is the same as the argument.
 111                 *@p r the rule to check for equivalence
 112                 */
 113         bool equals( TimeZoneRule *r );
 114
 115         int StartMonth, RevertMonth;
 116
 117 private:
 118
 119         /**@return the KStarsDateTime of the moment when the next DST change will occur in local time
 120                 *This is useful because DST change times are saved in local times*/
 121         void nextDSTChange_LTime( const KStarsDateTime &date );
 122
 123         /**@return the KStarsDateTime of the moment when the last DST change occurred in local time
 124                 *This is useful because DST change times are saved in local times
 125                 *We need this in case time is running backwards. */
 126         void previousDSTChange_LTime( const KStarsDateTime &date );
 127
 128         /**calculate the next DST change in universal time for current location */
 129         void nextDSTChange( const KStarsDateTime &local_date, const double TZoffset );
 130
 131         /**calculate the previous DST change in universal time for current location */
 132         void previousDSTChange( const KStarsDateTime &local_date, const double TZoffset );
 133
 134         /**Interpret the string as a month of the year;
 135                 *@return the month integer (1=jan ... 12=dec)
 136                 */
 137         int initMonth( const QString &m );
 138
 139         /**Interpret the day string as a week ID and a day-of-week ID.  The day-of-week
 140                 *is an integer between 1 (sunday) and 7 (saturday); the week integer can
 141                 *be 1-3 (1st/2nd/third weekday of the month), or 5 (last weekday of the month)
 142                 *@p day the day integer is returned by reference through this value
 143                 *@p week the week integer is returned by reference through this value
 144                 *@return TRUE if the day string was successfully parsed
 145                 */
 146         bool initDay( const QString &d, int &day, int &week );
 147
 148         /**Find the calendar date on which DST starts for the calendar year
 149                 *of the given KStarsDateTime.
 150                 *@p d the date containing the year to be tested
 151                 *@return the calendar date, an integer between 1 and 31. */
 152         int findStartDay( const KStarsDateTime &d );
 153
 154         /**Find the calendar date on which DST ends for the calendar year
 155                 *of the given KStarsDateTime.
 156                 *@p d the date containing the year to be tested
 157                 *@return the calendar date, an integer between 1 and 31. */
 158         int findRevertDay( const KStarsDateTime &d );
 159
 160         int StartDay, RevertDay;
 161         int StartWeek, RevertWeek;
 162         QTime StartTime, RevertTime;
 163         KStarsDateTime next_change_utc, next_change_ltime;
 164         double dTZ, HourOffset;
 165
 166 };
 167
 168 #endif