qttemporalpattern_p.h

++ // Copyright (C) 2026 The Qt Company Ltd.

++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only

++ // Qt-Security score:significant reason:default

++

++ #ifndef QTTEMPORALPATTERN_P_H

++ #define QTTEMPORALPATTERN_P_H

++

++ //

++ //  W A R N I N G

++ //  -------------

++ //

++ // This file is not part of the Qt API. It exists purely as an implementation

++ // detail. This header file may change from version to version without notice,

++ // or even be removed.

++ //

++ // We mean it.

++ //

++

++ #include <QtCore/qcalendar.h>

++ #include <QtCore/qdatetime.h>

++ #include <QtCore/qflags.h>

++ #include <QtCore/qlist.h>

++ #include <QtCore/qlocale.h>

++ #include <QtCore/qmetaobject.h>

++ #include <QtCore/qspan.h>

++ #include <QtCore/qstring.h>

++ #include <QtCore/qstringview.h>

++

++ #include <optional>

++

++ QT_REQUIRE_CONFIG(datestring);

++ QT_BEGIN_NAMESPACE

++

++ namespace QtTemporalPattern {

++

++     // Model the LDML spec's range of possible fields, see QTBUG-70516 and

++     // https://www.unicode.org/reports/tr35/tr35-dates.html#table-date-field-symbol-table

++     enum class TemporalFieldCategory : quint8 {

++         Literal = 0,

++

++         // Special:

++         TimeZone = 4,

++

++         // Time:

++         // MillisecondInDay = 17,

++         Second = 20, SecondFraction = 21,

++         Minute = 24, // MinuteFraction = 25,

++         HourMod12 = 30, Hour = 31, // HourFraction = 32,

++         PeriodInDay = 33, // am/pm; LDML also has noon, midnight, "at night" and others.

++

++         // Date:

++         DayOfWeek = 64, DayOfMonth = 65, // DayOfYear = 68, JulianDay = 69,

++         // WeekOfMonth = 72,

++         // WeekOfYear = 73, // QTBUG-57212, QTBUG-83678, QTBUG-117055

++         Month = 80,

++         // Quarter = 84,

++         // RelatedGregorianYear = 90, Century = 91,

++         YearWithinCentury = 92, Year = 93,

++         // Era = 100,

++

++         EndCategories

++     };

++     constexpr inline

++     auto EndTemporalFieldCategories = qToUnderlying(TemporalFieldCategory::EndCategories);

++

++     enum class TemporalFieldFlag : quint32 {

++         Numeric = 1, Verbal = 2, Standalone = 4,

++         Narrow = 0x10, Abbreviated = 0x20, Short = 0x40, Wide = 0x80,

++         ZeroPad = 0x0100, // For TimeZone, ZeroPad applies only to hour fields.

++         SpacePad = 0x0200, FlexSpace = 0x0400, StrictSpace = 0x0800,

++         // Qt used to impose case on am/pm fields:

++         LowerCase = 0x1000, UpperCase = 0x2000, // Otherwise follow locale-supplied case.

++         IgnoreCase = 0x4000, // Parsing Literal or Verbal: match case insensitively

++         // (0x8000 free)

++         // Special cases:

++         RoundFraction = 0x01'0000, // Fractional part accepts extra digits, rounding suitably

++         // (0x02'0000, 0x04'0000 free)

++         YearSignIso8601 = 0x08'0000, // Require sign when excess digits

++         // Zone-specific:

++         LocalizedZone = 0x10'0000, // Localized forms, various.

++         Iso8601 = 0x20'0000, // Non-localized standard offset forms.

++         AcceptUtcPrefix = 0x40'0000, NeedNoUtcPrefix = 0x80'0000, // On offsets

++         AllowZSuffix = 0x0100'0000, // Iso8601 zero-offset may be indicated by Z.

++         // Time-types (if none specified, infer time type from date/time fields):

++         GenericTime = 0x0200'0000, StandardTime = 0x0400'0000, DaylightSavingTime = 0x0800'0000,

++         // (0x1000'0000, 0x2000'0000, 0x4000'0000 free)

++         // Local time from system info:

++         LocalTimeName = 0x8000'0000 // That's the last bit available to us.

++     };

++     Q_DECLARE_FLAGS(TemporalFieldFlags, TemporalFieldFlag)

++     Q_DECLARE_OPERATORS_FOR_FLAGS(TemporalFieldFlags)

++

++     namespace FieldGroup {

++         constexpr TemporalFieldFlags FormMask = TemporalFieldFlag::Numeric

++             | TemporalFieldFlag::Verbal | TemporalFieldFlag::Standalone;

++         constexpr TemporalFieldFlags WidthMask

++             = TemporalFieldFlag::Narrow | TemporalFieldFlag::Abbreviated

++             | TemporalFieldFlag::Short | TemporalFieldFlag::Wide;

++         constexpr TemporalFieldFlags PaddingMask

++             = TemporalFieldFlag::ZeroPad | TemporalFieldFlag::SpacePad;

++         constexpr TemporalFieldFlags LocalizationMask

++             = TemporalFieldFlag::LocalizedZone | TemporalFieldFlag::Iso8601;

++         constexpr TemporalFieldFlags UtcPrefixMask

++             = TemporalFieldFlag::AcceptUtcPrefix | TemporalFieldFlag::NeedNoUtcPrefix;

++         constexpr TemporalFieldFlags SeasonMask = TemporalFieldFlag::GenericTime

++             | TemporalFieldFlag::StandardTime | TemporalFieldFlag::DaylightSavingTime;

++     }

++

++     // Implement group-related tests:

++     constexpr inline

++     bool matchesFlagWithin(QtTemporalPattern::TemporalFieldFlags flags,

++                            QtTemporalPattern::TemporalFieldFlag sought,

++                            QtTemporalPattern::TemporalFieldFlags group)

++     {

++         Q_ASSERT(group.testFlag(sought)); // In case caller passed the wrong group.

++         return flags.testFlag(sought) || !flags.testAnyFlags(group);

++     }

++

++     constexpr inline

++     bool matchesFlagsWithin(QtTemporalPattern::TemporalFieldFlags flags,

++                             QtTemporalPattern::TemporalFieldFlags sought,

++                             QtTemporalPattern::TemporalFieldFlags group)

++     {

++         Q_ASSERT(!(sought & ~group)); // i.e. all of sought are in group.

++         return flags.testAnyFlags(sought) || !flags.testAnyFlags(group);

++     }

++

++     // Classify the categories:

++     enum class DateTimePart { None, Date = 1, Time = 2, Zone = 4 };

++     Q_DECLARE_FLAGS(DateTimeParts, DateTimePart)

++     Q_DECLARE_OPERATORS_FOR_FLAGS(DateTimeParts)

++ #ifdef QT_BUILD_INTERNAL

++     Q_NAMESPACE_EXPORT(Q_CORE_EXPORT)

++     Q_FLAG_NS(TemporalFieldFlags)

++     Q_FLAG_NS(DateTimeParts)

++ #endif // For testing.

++

++     inline DateTimePart classify(TemporalFieldCategory category) noexcept

++     {

++         if (category == TemporalFieldCategory::Literal)

++             return DateTimePart::None;

++         if (quint8(category) < 16)

++             return DateTimePart::Zone;

++         if (quint8(category) < 64) // a.k.a. 0x40

++             return DateTimePart::Time;

++         return DateTimePart::Date;

++     }

++

++     // Combine with related information:

++     struct TemporalField {

++         QString literal; // Only relevant to Literal

++         qsizetype width; // Lower bound, usually only relevant to Numeric.

++         TemporalFieldFlags options;

++         TemporalFieldCategory category;

++         DateTimePart part() const noexcept { return classify(category); }

++         friend bool comparesEqual(const TemporalField &lhs, const TemporalField &rhs) noexcept

++         {

++             return lhs.literal == rhs.literal

++                 && lhs.width == rhs.width

++                 && lhs.options == rhs.options

++                 && lhs.category == rhs.category;

++         }

++         Q_DECLARE_EQUALITY_COMPARABLE(TemporalField)

++     };

++

++     inline DateTimeParts hasFieldsFor(QSpan<const TemporalField> range)

++     {

++         DateTimeParts result = DateTimePart::None;

++         for (const TemporalField &it : range)

++             result |= it.part();

++         return result;

++     }

++

++     enum class SupportType { Partial = -1, None = 0, Clear = 1, HasStrays };

++     Q_CORE_EXPORT

++     SupportType supports(DateTimeParts wanted, QSpan<const TemporalField> range,

++                          bool hasBaseYear = false) noexcept;

++ } // namespace QtTemporalPattern

++

++ /* We may eventually want to make the following public API (along with a

++    forward-declaration of QtTemporalPattern::TemporalField), while leaving the

++    above in a private header. See QTBUG-70516, QTBUG-81056.

++

++    This may, of course, involve splitting the types below into a public facade

++    with the actual data members hidden from view behind a shared d-pointer to a

++    private internal class.

++

++    Please bear that in mind when considering the design of the APIs below, and

++    any future changes thereto.

++ */

++

++ namespace QtTemporalPattern {

++ template <typename Payload>

++ struct ParseResult

++ {

++     Payload payload;

++     qsizetype size = 0;

++ };

++ } // namespace QtTemporalPattern

++

++ class QDateTimePattern

++ {

++     using Field = QtTemporalPattern::TemporalField;

++     QList<Field> m_fields;

++     QLocale m_locale;

++     QCalendar m_calendar;

++     std::optional<int> m_baseYear;

++     explicit QDateTimePattern(const QList<Field> &fs) : m_fields(fs) {}

++     explicit QDateTimePattern(const QList<Field> &fs, int centuryStart)

++         : m_fields(fs), m_baseYear(centuryStart) {}

++

++     QtTemporalPattern::SupportType dateTimeSupport() const noexcept

++     {

++         using namespace QtTemporalPattern;

++         constexpr DateTimeParts NeededParts = DateTimePart::Date | DateTimePart::Time;

++         const DateTimeParts got = hasFieldsFor(m_fields);

++         // Must have date and time (zone optional) and support what it has:

++         if (got.testFlags(NeededParts))

++             return supports(got, m_fields, m_baseYear.has_value());

++         return got ? SupportType::Partial : SupportType::None;

++     }

++ public:

++     bool isNull() const noexcept { return m_fields.isEmpty(); }

++     bool isValid() const noexcept

++     {

++         return dateTimeSupport() == QtTemporalPattern::SupportType::Clear;

++     }

++     void setLocale(const QLocale &loc) { m_locale = loc; }

++     const QLocale &locale() const noexcept { return m_locale; }

++

++     void setBaseYear(int centuryStart) { m_baseYear = centuryStart; }

++     void clearBaseYear() noexcept { m_baseYear = std::nullopt; }

++     std::optional<int> baseYear() const noexcept { return m_baseYear; }

++

++     void setCalendar(QCalendar cal) { m_calendar = cal; }

++     QCalendar calendar() const noexcept { return m_calendar; }

++

++     Q_CORE_EXPORT QtTemporalPattern::ParseResult<QDateTime>

++     parse(QStringView text, const QDateTime &defaults = {}) const;

++     Q_CORE_EXPORT QString serialize(const QDateTime &datetime) const;

++

++     static Q_CORE_EXPORT QDateTimePattern fromQtFormat(QStringView format);

++     static

++     QDateTimePattern forLocale(const QLocale &locale,

++                                QLocale::FormatType format = QLocale::LongFormat)

++     {

++         auto pat = fromQtFormat(locale.dateTimeFormat(format));

++         pat.setLocale(locale);

++         return pat;

++     }

++ };

++

++ class QTimePattern

++ {

++     using Field = QtTemporalPattern::TemporalField;

++     QList<Field> m_fields;

++     QLocale m_locale;

++     explicit QTimePattern(const QList<Field> &fs) : m_fields(fs) {}

++

++     QtTemporalPattern::SupportType timeSupport() const noexcept

++     {

++         using namespace QtTemporalPattern;

++         return supports({DateTimePart::Time}, m_fields);

++     }

++ public:

++     bool isNull() const noexcept { return m_fields.isEmpty(); }

++     bool isValid() const noexcept

++     {

++         return timeSupport() == QtTemporalPattern::SupportType::Clear;

++     }

++     void setLocale(const QLocale &loc) { m_locale = loc; }

++     const QLocale &locale() const noexcept { return m_locale; }

++

++     Q_CORE_EXPORT QtTemporalPattern::ParseResult<QTime>

++     parse(QStringView text, QTime defaults = {}) const;

++     Q_CORE_EXPORT QString serialize(const QTime &time) const;

++

++     static Q_CORE_EXPORT QTimePattern fromQtFormat(QStringView format);

++     static

++     QTimePattern forLocale(const QLocale &locale, QLocale::FormatType format = QLocale::LongFormat)

++     {

++         auto pat = fromQtFormat(locale.timeFormat(format));

++         pat.setLocale(locale);

++         return pat;

++     }

++ };

++

++ class QDatePattern

++ {

++     using Field = QtTemporalPattern::TemporalField;

++     QList<Field> m_fields;

++     QLocale m_locale;

++     QCalendar m_calendar;

++     std::optional<int> m_baseYear;

++     explicit QDatePattern(const QList<Field> &fs) : m_fields(fs) {}

++     explicit QDatePattern(const QList<Field> &fs, int centuryStart)

++         : m_fields(fs), m_baseYear(centuryStart) {}

++

++     QtTemporalPattern::SupportType dateSupport() const noexcept

++     {

++         using namespace QtTemporalPattern;

++         return supports({DateTimePart::Date}, m_fields, m_baseYear.has_value());

++     }

++ public:

++     bool isNull() const noexcept { return m_fields.isEmpty(); }

++     bool isValid() const noexcept

++     {

++         return dateSupport() == QtTemporalPattern::SupportType::Clear;

++     }

++     void setLocale(const QLocale &loc) { m_locale = loc; }

++     const QLocale &locale() const noexcept { return m_locale; }

++

++     void setBaseYear(int centuryStart) { m_baseYear = centuryStart; }

++     void clearBaseYear() noexcept { m_baseYear = std::nullopt; }

++     std::optional<int> baseYear() const noexcept { return m_baseYear; }

++

++     void setCalendar(QCalendar cal) { m_calendar = cal; }

++     QCalendar calendar() const noexcept { return m_calendar; }

++

++     Q_CORE_EXPORT QtTemporalPattern::ParseResult<QDate>

++     parse(QStringView text, QDate defaults = {}) const;

++     Q_CORE_EXPORT QString serialize(const QDate &date) const;

++

++     static Q_CORE_EXPORT QDatePattern fromQtFormat(QStringView format);

++     static

++     QDatePattern forLocale(const QLocale &locale, QLocale::FormatType format = QLocale::LongFormat)

++     {

++         auto pat = fromQtFormat(locale.dateFormat(format));

++         pat.setLocale(locale);

++         return pat;

++     }

++ };

++

++ QT_END_NAMESPACE

++

++ #endif // QTTEMPORALPATTERN_P_H

Revision control