1 | /* |
2 | This file is part of the kholidays library. |
3 | |
4 | Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org> |
5 | Copyright (c) 2004 Allen Winter <winter@kde.org> |
6 | Copyright (c) 2008 David Jarvie <djarvie@kde.org> |
7 | Copyright 2010 John Layt <john@layt.net> |
8 | |
9 | This library is free software; you can redistribute it and/or |
10 | modify it under the terms of the GNU Library General Public |
11 | License as published by the Free Software Foundation; either |
12 | version 2 of the License, or (at your option) any later version. |
13 | |
14 | This library is distributed in the hope that it will be useful, |
15 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
17 | GNU Library General Public License for more details. |
18 | |
19 | You should have received a copy of the GNU Library General Public License |
20 | along with this library; see the file COPYING.LIB. If not, write to the |
21 | Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
22 | Boston, MA 02110-1301, USA. |
23 | */ |
24 | |
25 | #ifndef KHOLIDAYS_HOLIDAYREGION_H |
26 | #define KHOLIDAYS_HOLIDAYREGION_H |
27 | |
28 | #include "kholidays_export.h" |
29 | |
30 | #include <QtCore/QList> |
31 | #include <QtCore/QSharedDataPointer> |
32 | #include <QtCore/QString> |
33 | |
34 | #include "holiday.h" |
35 | |
36 | class QDate; |
37 | class QStringList; |
38 | class QFileInfo; |
39 | |
40 | namespace KHolidays { |
41 | |
42 | class KHOLIDAYS_EXPORT HolidayRegion |
43 | { |
44 | public: |
45 | /** |
46 | * Creates a new Holiday Region object for a given standard Region Code. |
47 | * |
48 | * From 4.5 onwards this constructor requires the new Region Code not the |
49 | * deprecated Location Code. If a Location Code is provided the first |
50 | * match will be created. |
51 | * |
52 | * @param regionCode The code for the Holiday Region. |
53 | * If null or unknown, an empty instance will be created. |
54 | */ |
55 | explicit HolidayRegion( const QString ®ionCode = QString() ); |
56 | |
57 | /** |
58 | * Creates a new Holiday Region object from a given holiday file. |
59 | * If file doesn't exist, an empty instance will be created. |
60 | * |
61 | * @param regionFile The code for the Holiday Region. |
62 | */ |
63 | explicit HolidayRegion( const QFileInfo ®ionFile ); |
64 | |
65 | /** |
66 | * Destroys the holidays object. |
67 | */ |
68 | ~HolidayRegion(); |
69 | |
70 | /** |
71 | * @deprecated use regions() instead |
72 | * |
73 | * Return a list of all available location codes which have a holiday definition. |
74 | * |
75 | * One of these can then be passed to the constructor for a new HolidayRegion |
76 | * object. |
77 | * |
78 | * @see regions() |
79 | */ |
80 | static QStringList locations(); |
81 | |
82 | /** |
83 | * @deprecated use regionCode() or countryCode() instead |
84 | * |
85 | * Returns the holiday location. |
86 | * |
87 | * The holiday location is a code representing the holiday region. |
88 | * |
89 | * @return region code, or null if the instance was constructed with |
90 | * an unknown region |
91 | * |
92 | * @see regionCode() |
93 | * @see languageCode() |
94 | */ |
95 | QString location() const; |
96 | |
97 | /** |
98 | * @since 4.5 |
99 | * |
100 | * Return a list of all available Holiday Region codes. |
101 | * |
102 | * One of these can then be passed to the constructor for a new HolidayRegion |
103 | * object, or to name() or language() to obtain the name and language of the region. |
104 | * |
105 | * @see name() |
106 | * @see languageCode() |
107 | */ |
108 | static QStringList regionCodes(); |
109 | |
110 | /** |
111 | * @since 4.6 |
112 | * |
113 | * Return a reasonable default Holiday Region code |
114 | * |
115 | * If a required country/language is not provided then the current KDE |
116 | * country/lanaguage is used. |
117 | * |
118 | * @param country The country to find a default Holiday Region for |
119 | * @param language The lanaguage to find a default Holiday Region for |
120 | * @return the full region code of the default file |
121 | */ |
122 | static QString defaultRegionCode( const QString &country = QString(), |
123 | const QString &language = QString() ); |
124 | |
125 | /** |
126 | * @since 4.5 |
127 | * |
128 | * Returns the unique Holiday Region code. |
129 | * |
130 | * Clients should not infer any meaning from the format of the code. |
131 | * |
132 | * @return region code, or null if the instance was constructed with |
133 | * an unknown region |
134 | */ |
135 | QString regionCode() const; |
136 | |
137 | /** |
138 | * @since 4.5 |
139 | * |
140 | * Return the ISO 3166 country code of the file |
141 | * |
142 | * May be either just a country code ("US" = USA) or may include a regional |
143 | * identifier ("US-CA" = California). Returns "XX" if not a country. |
144 | * |
145 | * See http://en.wikipedia.org/wiki/ISO_3166-2 |
146 | * |
147 | * @return the full region code of the file |
148 | */ |
149 | QString countryCode() const; |
150 | |
151 | /** |
152 | * @since 4.5 |
153 | * |
154 | * Return the ISO 3166 country code of a given Holiday Region |
155 | * |
156 | * May be either just a country code ("US" = USA) or may include a regional |
157 | * identifier ("US-CA" = California). Returns "XX" if not a country. |
158 | * |
159 | * See http://en.wikipedia.org/wiki/ISO_3166-2 |
160 | * |
161 | * @param regionCode The code for the Holiday Region. |
162 | * @return the full region code of the file |
163 | */ |
164 | static QString countryCode( const QString ®ionCode ); |
165 | |
166 | /** |
167 | * @since 4.5 |
168 | * |
169 | * Return the ISO 639-1 language code of the file |
170 | * |
171 | * May be either just a language code ("en" = US English) or may include a country |
172 | * identifier ("en_GB" = British English). |
173 | * |
174 | * @return the language code of the file |
175 | */ |
176 | QString languageCode() const; |
177 | |
178 | /** |
179 | * @since 4.5 |
180 | * |
181 | * Return the ISO 639-1 language code of a given Holiday Region |
182 | * |
183 | * May be either just a language code ("en" = US English) or may include a country |
184 | * identifier ("en_GB" = British English). |
185 | * |
186 | * @param regionCode The code for the Holiday Region. |
187 | * @return the language code of the file |
188 | */ |
189 | static QString languageCode( const QString ®ionCode ); |
190 | |
191 | /** |
192 | * @since 4.5 |
193 | * |
194 | * Return the name of the Holiday Region. |
195 | * This may be a country, region, or type. |
196 | * |
197 | * @return the short name code of the file |
198 | */ |
199 | QString name() const; |
200 | |
201 | /** |
202 | * @since 4.5 |
203 | * |
204 | * Return the name of a given Holiday Region |
205 | * |
206 | * @param regionCode The code for the Holiday Region. |
207 | * @return the name of the Holiday Region |
208 | */ |
209 | static QString name( const QString ®ionCode ); |
210 | |
211 | /** |
212 | * @since 4.5 |
213 | * |
214 | * Return the description of the Holiday Region if available |
215 | * |
216 | * @return the description of the Holiday Region |
217 | */ |
218 | QString description() const; |
219 | |
220 | /** |
221 | * @since 4.5 |
222 | * |
223 | * Return the description of a given Holiday Region if available |
224 | * |
225 | * @return the description of the Holiday Region |
226 | */ |
227 | static QString description( const QString ®ionCode ); |
228 | |
229 | /** |
230 | * @since 4.5 |
231 | * |
232 | * Returns the list of holidays that occur between @p startDate and @p endDate. |
233 | */ |
234 | Holiday::List holidays( const QDate &startDate, const QDate &endDate ) const; |
235 | |
236 | //KDE5: merge with default multidayMode |
237 | /** |
238 | * @since 4.6 |
239 | * |
240 | * Returns the list of holidays that occur between @p startDate and @p endDate. |
241 | */ |
242 | Holiday::List holidays( const QDate &startDate, const QDate &endDate, |
243 | Holiday::MultidayMode multidayMode ) const; |
244 | |
245 | /** |
246 | * Returns the list of holidays that occur on a @p date. |
247 | */ |
248 | Holiday::List holidays( const QDate &date ) const; |
249 | |
250 | //KDE5: merge with default multidayMode |
251 | /** |
252 | * @since 4.6 |
253 | * |
254 | * Returns the list of holidays that occur on a @p date. |
255 | */ |
256 | Holiday::List holidays( const QDate &date, Holiday::MultidayMode multidayMode ) const; |
257 | |
258 | /** |
259 | * @since 4.5 |
260 | * |
261 | * Returns the list of holidays that occur in a calendar year @p calendarYear. |
262 | */ |
263 | Holiday::List holidays( int calendarYear, const QString &calendarType ) const; |
264 | |
265 | //KDE5: merge with default multidayMode |
266 | /** |
267 | * @since 4.6 |
268 | * |
269 | * Returns the list of holidays that occur in a calendar year @p calendarYear. |
270 | */ |
271 | Holiday::List holidays( int calendarYear, const QString &calendarType, |
272 | Holiday::MultidayMode multidayMode ) const; |
273 | |
274 | /** |
275 | * Checks whether there is any holiday defined for a @p date. |
276 | */ |
277 | bool isHoliday( const QDate &date ) const; |
278 | |
279 | /** |
280 | * Returns whether the instance contains any holiday data. |
281 | */ |
282 | bool isValid() const; |
283 | |
284 | /** |
285 | * @since 4.5 |
286 | * |
287 | * Returns whether the Region Code is valid. |
288 | */ |
289 | static bool isValid( const QString ®ionCode ); |
290 | |
291 | private: |
292 | Q_DISABLE_COPY( HolidayRegion ) |
293 | |
294 | class Private; |
295 | Private *const d; |
296 | }; |
297 | |
298 | } |
299 | |
300 | #endif // KHOLIDAYS_HOLIDAYREGION_H |
301 | |