Kstars

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

KDE's Doxygen guidelines are available online.