File indexing completed on 2022-12-06 19:13:35

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 &regionCode = 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 &regionFile);
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 &regionCode);
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 &regionCode);
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 &regionCode);
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 &regionCode);
0209 
0210 #if KHOLIDAYS_ENABLE_DEPRECATED_SINCE(5, 95)
0211     /**
0212      * @since 4.6
0213      *
0214      * Returns the list of holidays that occur between @p startDate and @p endDate.
0215      *
0216      * @deprecated Since 5.95, use rawHolidaysWithAstroSeasons() instead.
0217      */
0218     KHOLIDAYS_DEPRECATED_VERSION(5, 95, "use rawHolidaysWithAstroSeasons() instead")
0219     Holiday::List holidays(const QDate &startDate, const QDate &endDate) const;
0220 #endif
0221 
0222     /**
0223      * @since 5.95
0224      *
0225      * Returns the list of holidays that occur between @p startDate and @p endDate.
0226      *
0227      */
0228     Holiday::List rawHolidaysWithAstroSeasons(const QDate &startDate, const QDate &endDate) const;
0229 
0230     /**
0231      * @since 5.97
0232      *
0233      * Returns the list of holidays that occur between @p startDate and @p endDate.
0234      */
0235     Holiday::List rawHolidays(const QDate &startDate, const QDate &endDate) const;
0236 
0237 #if KHOLIDAYS_ENABLE_DEPRECATED_SINCE(5, 95)
0238     /**
0239      * @since 4.6
0240      *
0241      * Returns the list of holidays that occur on a @p date.
0242      *
0243      * @deprecated Since 5.95, use rawHolidaysWithAstroSeasons() instead.
0244      */
0245     KHOLIDAYS_DEPRECATED_VERSION(5, 95, "use rawHolidaysWithAstroSeasons() instead")
0246     Holiday::List holidays(const QDate &date) const;
0247 #endif
0248 
0249     /**
0250      * @since 5.95
0251      *
0252      * Returns the list of holidays that occur on a @p date.
0253      */
0254     Holiday::List rawHolidaysWithAstroSeasons(const QDate &date) const;
0255 
0256 #if KHOLIDAYS_ENABLE_DEPRECATED_SINCE(5, 95)
0257     /**
0258      * @since 4.6
0259      *
0260      * Returns the list of holidays that occur in a Gregorian calendar year @p calendarYear.
0261      *
0262      * @deprecated Since 5.95, use rawHolidaysWithAstroSeasons() instead.
0263      */
0264     KHOLIDAYS_DEPRECATED_VERSION(5, 95, "use rawHolidaysWithAstroSeasons() instead")
0265     Holiday::List holidays(int calendarYear) const;
0266 #endif
0267 
0268     /**
0269      * @since 5.95
0270      *
0271      * Returns the list of holidays that occur in a Gregorian calendar year @p calendarYear.
0272      */
0273     Holiday::List rawHolidaysWithAstroSeasons(int calendarYear) const;
0274 
0275     /**
0276      * @since 5.95
0277      *
0278      * Returns the list of holidays that occur between @p startDate and @p endDate and with @p category.
0279      */
0280     Holiday::List rawHolidays(const QDate &startDate, const QDate &endDate, const QString &category) const;
0281 
0282     /**
0283      * Checks whether there is any holiday defined for a @p date.
0284      */
0285     bool isHoliday(const QDate &date) const;
0286 
0287     /**
0288      * Returns whether the instance contains any holiday data.
0289      */
0290     bool isValid() const;
0291 
0292     /**
0293      * @since 4.5
0294      *
0295      * Returns whether the Region Code is valid.
0296      */
0297     static bool isValid(const QString &regionCode);
0298 
0299 private:
0300     QExplicitlySharedDataPointer<HolidayRegionPrivate> d;
0301 };
0302 
0303 }
0304 
0305 #endif // KHOLIDAYS_HOLIDAYREGION_H