include/QtCore/qcalendar.h

0001 // Copyright (C) 2021 The Qt Company Ltd.
0002 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0003
0004 #ifndef QCALENDAR_H
0005 #define QCALENDAR_H
0006
0007 #include <limits>
0008
0009 #include <QtCore/qglobal.h>
0010 #include <QtCore/qlocale.h>
0011 #include <QtCore/qstring.h>
0012 #include <QtCore/qstringview.h>
0013
0014 /* Suggested enum names for other calendars known to CLDR (v33.1)
0015
0016    Not yet implemented - see QCalendar::System - contributions welcome:
0017
0018    * Buddhist -- Thai Buddhist, to be specific
0019    * Chinese
0020    * Coptic
0021    * Dangi -- Korean
0022    * Ethiopic (Amete Mihret - epoch approx. 8 C.E.)
0023    * EthiopicAmeteAlem (Amete Alem - epoch approx. 5493 B.C.E; data from
0024      type="ethiopic-amete-alem", an alias for type="ethioaa")
0025    * Hebrew
0026    * Indian -- National
0027    * Islamic -- Based on astronomical observations, not predictions, so hard to
0028      implement. CLDR's data for type="islamic" apply, unless overridden, to the
0029      other Islamic calendar variants, i.e. IslamicCivil, above, and the three
0030      following. See QHijriCalendar, a common base to provide that data.
0031    * IslamicTabular -- tabular, astronomical epoch (same as IslamicCivil, except
0032      for epoch), CLDR type="islamic-tbla"
0033    * Saudi -- Saudi Arabia, sighting; CLDR type="islamic-rgsa"
0034    * UmmAlQura -- Umm al-Qura, Saudi Arabia, calculated; CLDR type="islamic-umalqura"
0035    * Iso8601 -- as Gregorian, but treating ISO 8601 weeks as "months"
0036    * Japanese -- Imperial calendar
0037    * Minguo -- Republic of China, Taiwan; CLDR type="roc"
0038
0039    See:
0040    http://www.unicode.org/repos/cldr/tags/latest/common/bcp47/calendar.xml
0041
0042    These can potentially be supported, as features, using CLDR's data; any
0043    others shall need hand-crafted localization data; it would probably be best
0044    to do that by contributing data for them to CLDR.
0045 */
0046
0047 QT_BEGIN_NAMESPACE
0048
0049 class QCalendarBackend;
0050 class QDate;
0051
0052 class Q_CORE_EXPORT QCalendar
0053 {
0054     Q_GADGET
0055 public:
0056     // (Extra parentheses to suppress bogus reading of min() as a macro.)
0057     enum : int { Unspecified = (std::numeric_limits<int>::min)() };
0058     struct YearMonthDay
0059     {
0060         YearMonthDay() = default;
0061         YearMonthDay(int y, int m = 1, int d = 1) : year(y), month(m), day(d) {}
0062
0063         bool isValid() const
0064         { return month != Unspecified && day != Unspecified; }
0065         // (The first year supported by QDate has year == Unspecified.)
0066
0067         int year = Unspecified;
0068         int month = Unspecified;
0069         int day = Unspecified;
0070     };
0071     // Feature (\w+)calendar uses CLDR type="\1" data, except as noted in type="..." comments below
0072     enum class System
0073     {
0074         Gregorian, // CLDR: type = "gregory", alias = "gregorian"
0075 #ifndef QT_BOOTSTRAPPED
0076         Julian = 8,
0077         Milankovic = 9,
0078 #endif // These are Roman-based, so share Gregorian's CLDR data
0079
0080         // Feature-controlled calendars:
0081 #if QT_CONFIG(jalalicalendar) // type="persian"
0082         Jalali = 10,
0083 #endif
0084 #if QT_CONFIG(islamiccivilcalendar) // type="islamic-civil", uses data from type="islamic"
0085         IslamicCivil = 11,
0086         // tabular, civil epoch
0087         // 30 year cycle, leap on 2, 5, 7, 10, 13, 16, 18, 21, 24, 26 and 29
0088         // (Other variants: 2, 5, 8, (10|11), 13, 16, 19, 21, 24, 27 and 29.)
0089 #endif
0090
0091         Last = 11, // Highest number of any above
0092         User = -1
0093     };
0094     // New entries must be added to the \enum doc in qcalendar.cpp and
0095     // handled in QCalendarBackend::fromEnum()
0096     Q_ENUM(System)
0097     class SystemId
0098     {
0099         size_t id;
0100         friend class QCalendarBackend;
0101         constexpr bool isInEnum() const { return id <= size_t(QCalendar::System::Last); }
0102         constexpr explicit SystemId(QCalendar::System e) : id(size_t(e)) { }
0103         constexpr explicit SystemId(size_t i) : id(i) { }
0104
0105     public:
0106         constexpr SystemId() : id(~size_t(0)) {}
0107         constexpr size_t index() const noexcept { return id; }
0108         constexpr bool isValid() const noexcept { return ~id; }
0109     };
0110
0111     explicit QCalendar(); // Gregorian, optimised
0112     explicit QCalendar(System system);
0113 #if QT_CORE_REMOVED_SINCE(6, 4)
0114     explicit QCalendar(QLatin1StringView name);
0115     explicit QCalendar(QStringView name);
0116 #endif
0117     explicit QCalendar(QAnyStringView name);
0118     explicit QCalendar(SystemId id);
0119
0120     // QCalendar is a trivially copyable value type.
0121     bool isValid() const { return d_ptr != nullptr; }
0122
0123     // Date queries:
0124     int daysInMonth(int month, int year = Unspecified) const;
0125     int daysInYear(int year) const;
0126     int monthsInYear(int year) const;
0127     bool isDateValid(int year, int month, int day) const;
0128
0129     // Leap years:
0130     bool isLeapYear(int year) const;
0131
0132     // Properties of the calendar:
0133     bool isGregorian() const;
0134     bool isLunar() const;
0135     bool isLuniSolar() const;
0136     bool isSolar() const;
0137     bool isProleptic() const;
0138     bool hasYearZero() const;
0139     int maximumDaysInMonth() const;
0140     int minimumDaysInMonth() const;
0141     int maximumMonthsInYear() const;
0142     QString name() const;
0143
0144     // QDate conversions:
0145     QDate dateFromParts(int year, int month, int day) const;
0146     QDate dateFromParts(const YearMonthDay &parts) const;
0147     QDate matchCenturyToWeekday(const YearMonthDay &parts, int dow) const;
0148     YearMonthDay partsFromDate(QDate date) const;
0149     int dayOfWeek(QDate date) const;
0150
0151     // Month and week-day names (as in QLocale):
0152     QString monthName(const QLocale &locale, int month, int year = Unspecified,
0153                       QLocale::FormatType format=QLocale::LongFormat) const;
0154     QString standaloneMonthName(const QLocale &locale, int month, int year = Unspecified,
0155                                 QLocale::FormatType format = QLocale::LongFormat) const;
0156     QString weekDayName(const QLocale &locale, int day,
0157                         QLocale::FormatType format = QLocale::LongFormat) const;
0158     QString standaloneWeekDayName(const QLocale &locale, int day,
0159                                   QLocale::FormatType format=QLocale::LongFormat) const;
0160
0161     // Formatting of date-times:
0162     QString dateTimeToString(QStringView format, const QDateTime &datetime,
0163                              QDate dateOnly, QTime timeOnly,
0164                              const QLocale &locale) const;
0165
0166     // What's available ?
0167     static QStringList availableCalendars();
0168 private:
0169     // Always supplied by QCalendarBackend and expected to be a singleton
0170     // Note that the calendar registry destroys all backends when it is itself
0171     // destroyed. The code should check if the registry is destroyed before
0172     // dereferencing this pointer.
0173     const QCalendarBackend *d_ptr;
0174 };
0175
0176 QT_END_NAMESPACE
0177
0178 #endif // QCALENDAR_H