qttemporalpattern_p.h

Go to the documentation of this file.

// 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