File indexing completed on 2025-02-09 04:22:30
0001 /* 0002 This file is part of the kholidays library. 0003 0004 SPDX-FileCopyrightText: 2001 Cornelius Schumacher <schumacher@kde.org> 0005 SPDX-FileCopyrightText: 2004 Allen Winter <winter@kde.org> 0006 SPDX-FileCopyrightText: 2008 David Jarvie <djarvie@kde.org> 0007 SPDX-FileCopyrightText: 2010 John Layt <john@layt.net> 0008 0009 SPDX-License-Identifier: LGPL-2.0-or-later 0010 */ 0011 0012 #ifndef KHOLIDAYS_HOLIDAYREGION_H 0013 #define KHOLIDAYS_HOLIDAYREGION_H 0014 0015 #include "kholidays_export.h" 0016 0017 #include <QSharedDataPointer> 0018 #include <QString> 0019 #include <QStringList> 0020 0021 #include "holiday.h" 0022 0023 class QDate; 0024 class QFileInfo; 0025 0026 namespace KHolidays 0027 { 0028 class HolidayRegionPrivate; 0029 0030 /** Represents a holiday region. */ 0031 class KHOLIDAYS_EXPORT HolidayRegion 0032 { 0033 public: 0034 /** 0035 * Creates a new Holiday Region object for a given standard Region Code. 0036 * 0037 * @param regionCode The code for the Holiday Region. 0038 * If null or unknown, an empty instance will be created. 0039 */ 0040 explicit HolidayRegion(const QString ®ionCode = QString()); 0041 0042 /** 0043 * Creates a new Holiday Region object from a given holiday file. 0044 * If file doesn't exist, an empty instance will be created. 0045 * 0046 * @param regionFile The code for the Holiday Region. 0047 */ 0048 explicit HolidayRegion(const QFileInfo ®ionFile); 0049 0050 /** Copy constructor. 0051 * @since 5.77 0052 */ 0053 HolidayRegion(const HolidayRegion &); 0054 /** Move constructor. 0055 * @since 5.77 0056 */ 0057 HolidayRegion(HolidayRegion &&); 0058 0059 /** 0060 * Destroys the holidays object. 0061 */ 0062 ~HolidayRegion(); 0063 0064 /** Assignment operator. 0065 * @since 5.77 0066 */ 0067 HolidayRegion &operator=(const HolidayRegion &); 0068 /** Move Assignment operator. 0069 * @since 5.77 0070 */ 0071 HolidayRegion &operator=(HolidayRegion &&); 0072 0073 /** 0074 * @since 4.5 0075 * 0076 * Return a list of all available Holiday Region codes. 0077 * 0078 * One of these can then be passed to the constructor for a new HolidayRegion 0079 * object, or to name() or language() to obtain the name and language of the region. 0080 * 0081 * @see name() 0082 * @see languageCode() 0083 */ 0084 static QStringList regionCodes(); 0085 0086 /** 0087 * @since 4.6 0088 * 0089 * Return a reasonable default Holiday Region code 0090 * 0091 * If a required country/language is not provided then the current KDE 0092 * country/language is used. 0093 * 0094 * @param country The country or region to find a default Holiday Region for. 0095 * This can be either an ISO 3166-1 or ISO 3166-2 code. 0096 * @param language The language to find a default Holiday Region for 0097 * @return the full region code of the default file 0098 * @warning This methods is expensive as it involves parsing all holiday definition files. 0099 */ 0100 static QString defaultRegionCode(const QString &country = QString(), const QString &language = QString()); 0101 0102 /** 0103 * @since 4.5 0104 * 0105 * Returns the unique Holiday Region code. 0106 * 0107 * Clients should not infer any meaning from the format of the code. 0108 * 0109 * @return region code, or null if the instance was constructed with 0110 * an unknown region 0111 */ 0112 QString regionCode() const; 0113 0114 /** 0115 * @since 4.5 0116 * 0117 * Return the ISO 3166 country code of the file 0118 * 0119 * May be either just a country code ("US" = USA) or may include a regional 0120 * identifier ("US-CA" = California). Returns "XX" if not a country. 0121 * 0122 * See https://en.wikipedia.org/wiki/ISO_3166-2 0123 * 0124 * @return the full region code of the file 0125 */ 0126 QString countryCode() const; 0127 0128 /** 0129 * @since 4.5 0130 * 0131 * Return the ISO 3166 country code of a given Holiday Region 0132 * 0133 * May be either just a country code ("US" = USA) or may include a regional 0134 * identifier ("US-CA" = California). Returns "XX" if not a country. 0135 * 0136 * See https://en.wikipedia.org/wiki/ISO_3166-2 0137 * 0138 * @param regionCode The code for the Holiday Region. 0139 * @return the full region code of the file 0140 * @warning This methods is expensive as it involves parsing the corresponding holiday 0141 * definition file. Prefer HolidayRegion::countryCode(). 0142 */ 0143 static QString countryCode(const QString ®ionCode); 0144 0145 /** 0146 * @since 4.5 0147 * 0148 * Return the ISO 639-1 language code of the file 0149 * 0150 * May be either just a language code ("en" = US English) or may include a country 0151 * identifier ("en_GB" = British English). 0152 * 0153 * @return the language code of the file 0154 */ 0155 QString languageCode() const; 0156 0157 /** 0158 * @since 4.5 0159 * 0160 * Return the ISO 639-1 language code of a given Holiday Region 0161 * 0162 * May be either just a language code ("en" = US English) or may include a country 0163 * identifier ("en_GB" = British English). 0164 * 0165 * @param regionCode The code for the Holiday Region. 0166 * @return the language code of the file 0167 * @warning This methods is expensive as it involves parsing the corresponding holiday 0168 * definition file. Prefer HolidayRegion::languageCode(). 0169 */ 0170 static QString languageCode(const QString ®ionCode); 0171 0172 /** 0173 * @since 4.5 0174 * 0175 * Return the name of the Holiday Region. 0176 * This may be a country, region, or type. 0177 * 0178 * @return the short name code of the file 0179 */ 0180 QString name() const; 0181 0182 /** 0183 * @since 4.5 0184 * 0185 * Return the name of a given Holiday Region 0186 * 0187 * @param regionCode The code for the Holiday Region. 0188 * @return the name of the Holiday Region 0189 */ 0190 static QString name(const QString ®ionCode); 0191 0192 /** 0193 * @since 4.5 0194 * 0195 * Return the description of the Holiday Region if available 0196 * 0197 * @return the description of the Holiday Region 0198 */ 0199 QString description() const; 0200 0201 /** 0202 * @since 4.5 0203 * 0204 * Return the description of a given Holiday Region if available 0205 * 0206 * @return the description of the Holiday Region 0207 */ 0208 static QString description(const QString ®ionCode); 0209 0210 /** 0211 * @since 5.95 0212 * 0213 * Returns the list of holidays that occur between @p startDate and @p endDate. 0214 * 0215 */ 0216 Holiday::List rawHolidaysWithAstroSeasons(const QDate &startDate, const QDate &endDate) const; 0217 0218 /** 0219 * @since 5.97 0220 * 0221 * Returns the list of holidays that occur between @p startDate and @p endDate. 0222 */ 0223 Holiday::List rawHolidays(const QDate &startDate, const QDate &endDate) const; 0224 0225 /** 0226 * @since 5.95 0227 * 0228 * Returns the list of holidays that occur on a @p date. 0229 */ 0230 Holiday::List rawHolidaysWithAstroSeasons(const QDate &date) const; 0231 0232 /** 0233 * @since 5.95 0234 * 0235 * Returns the list of holidays that occur in a Gregorian calendar year @p calendarYear. 0236 */ 0237 Holiday::List rawHolidaysWithAstroSeasons(int calendarYear) const; 0238 0239 /** 0240 * @since 5.95 0241 * 0242 * Returns the list of holidays that occur between @p startDate and @p endDate and with @p category. 0243 */ 0244 Holiday::List rawHolidays(const QDate &startDate, const QDate &endDate, const QString &category) const; 0245 0246 /** 0247 * Checks whether there is any holiday defined for a @p date. 0248 */ 0249 bool isHoliday(const QDate &date) const; 0250 0251 /** 0252 * Returns whether the instance contains any holiday data. 0253 */ 0254 bool isValid() const; 0255 0256 /** 0257 * @since 4.5 0258 * 0259 * Returns whether the Region Code is valid. 0260 */ 0261 static bool isValid(const QString ®ionCode); 0262 0263 private: 0264 QExplicitlySharedDataPointer<HolidayRegionPrivate> d; 0265 }; 0266 0267 } 0268 0269 #endif // KHOLIDAYS_HOLIDAYREGION_H