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
36class QDate;
37class QStringList;
38class QFileInfo;
39
40namespace KHolidays {
41
42class 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 &regionCode = 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 &regionFile );
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 &regionCode );
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 &regionCode );
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 &regionCode );
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 &regionCode );
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 &regionCode );
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