Kstars

timezonerule.h
1/*
2 SPDX-FileCopyrightText: 2002 Jason Harris <kstars@30doradus.org>
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
13class 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)*/
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,...
This class provides the information needed to determine whether Daylight Savings Time (DST; a....
KStarsDateTime nextDSTChange() const
double deltaTZ() const
KStarsDateTime nextDSTChange_LTime() const
bool isEmptyRule() const
bool isDSTActive(const KStarsDateTime &date)
Determine whether DST is in effect for the given DateTime, according to this rule.
TimeZoneRule()
Default Constructor.
bool equals(TimeZoneRule *r)
void setDST(bool activate=true)
Toggle DST on/off.
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 ...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:04:47 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.