Revision control
++ // 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
++ #include "private/qttemporalpattern_p.h"
++
++ #include "private/qlocale_p.h"
++ #include "private/qtparseqttemporalformat_p.h"
++ #if QT_CONFIG(datetimeparser)
++ # include "private/qtparsetemporal_p.h"
++ #endif
++
++ #include <bitset>
++
++ QT_BEGIN_NAMESPACE
++
++ namespace QtTemporalPattern {
++ /*!
++ \internal
++ \since 6.12
++ \namespace QtTemporalPattern
++ \brief Supporting types and functions for temporal patterns.
++
++ Temporal patterns describe how a date, time or datetime may be serialized as
++ text or parsed from text. This namespace provides the common tools used by
++ the classes describing such patterns: \l QDateTimePattern, \l QTimePattern
++ and \l QDatePattern.
++ */
++
++ /* Note (QTBUG-70516): For now (Qt 6.12) it suffices to cover everything that
++ the existing Qt datetime format strings are capable of. However, the intent
++ is to eventually expand this to fully support CLDR's datetime formats so that
++ we can switch from converting those to Qt formats when we scan CLDR to
++ actually storing the CLDR format in the qlocale_data_p.h tables and
++ constructing our Q(Date|Time)+Pattern objects from those formats. See comment
++ in header for a link to the relevant parts of LDML.
++ */
++
++ /*!
++ \enum QtTemporalPattern::TemporalFieldCategory
++
++ This enumeration characterizes the information supplied by a field.
++
++ For the details of how that information is conveyed, see \l
++ {QtTemporalPattern::}{TemporalFieldFlag}. For the classification of fields
++ by whether they specify date, time or zone, see \l
++ {QtTemporalPattern::}{DateTimePart}.
++
++ \value Literal Describes a text fragment that frames the data, such as
++ separators and delimiters.
++ \value TimeZone Identifies the timezone or offset from UTC of a datetime.
++ \value SecondFraction The fraction of a second (an optional time field).
++ \value Second The second within the minute (an optional time field).
++ \value Minute The minute within the hour (a time field).
++ \value PeriodInDay A subdivision of the day, such as before noon vs after
++ noon (a time field). May serve to disambiguate the hour
++ when specified only modulo 12. (Currently only the am/pm
++ distinction is supported.)
++ \value HourMod12 The hour in the range 1 through 12 (a time field). May be
++ ambiguous on its own.
++ \value Hour The hour in the range from 0 through 23 (a time field).
++
++ \value DayOfWeek The day within the week (a date field). Usually specified
++ by name. Some locales may use numbers for their Narrow
++ Verbal and/or Standalone forms. No form is supported for
++ Numeric | DayOfWeek.
++ \value DayOfMonth The day number within the month (a date field). Runs from
++ 1 for the first day of the month up to the length of the
++ month. Always numeric, regardless of field flags.
++
++ \value Month The month within the year (a date field). When specified
++ numerically, the first month of the year is numbered 1; there
++ is no month 0. Some locales may use numbers for their Narrow
++ Verbal form.
++
++ \value YearWithinCentury The two-digit year number (a date field). Widely
++ used in date formats, despite its potential for
++ ambiguity. May be disambiguated by other fields or
++ by specifying base year for the hundred years
++ presumed when only two digits are given and other
++ fields don't disambiguate.
++ \value Year The full year number (a date field).
++
++ Fields identified as numbers, along with hour, minute, second and fraction
++ of second, are always given in numeric form (regardless of Numeric, Verbal
++ or Standalone flags). Where a field is given in numeric form, its field
++ width is the smallest number of digits that can match it. Further digits are
++ accepted, up to the greatest number of significant digits that can appear in
++ a valid value for it. (If the field width exceeds this, fields of this width
++ are accepted, provided the numeric value is valid. This may require
++ zero-padding.)
++
++ The SecondFraction field describes the digits immediately following the
++ fractional-part separator in a decimal representation of the seconds with
++ fractional part. It is up to the format to position it suitably in relation
++ to a Second field and a Literal field for the separator. Leading zeros are
++ significant and not considered to be padding: trailing zeros are understood
++ as padding.
++
++ As QTime and QDateTime only handle times to millisecond precision, normally
++ their allowed range of values runs from 0 to 999 and no more than three
++ digits are accepted, or the field width if greater. If the \l
++ {QtTemporalPattern::TemporalFieldFlag} {RoundFraction} flag is passed,
++ digits beyond this are accepted and will affect the result only via
++ appropriate rounding. (If fewer than three digits are parsed, the value is
++ implicitly extended on the right with zeros to obtain milliseconds
++ precision. Whether such a field is accepted will depend on the setting of
++ the \c width of the field and the absence of \l
++ {QtTemporalPattern::TemporalFieldFlag} {ZeroPad} from its \l
++ {QtTemporalPattern::TemporalField} {\c options}, in the usual ways.)
++
++ Where a SecondFraction field accepts more than three digits (either because
++ its field width exceeds three or because the RoundFraction flag is
++ specified), the resulting fractional part is rounded to three significant
++ digits. If rounding would require increasing the Second field, however, the
++ Second field is retained unchanged and the fractional part is rounded to 999
++ milliseconds. For example, 29.9997 seconds is rounded to 29.999 seconds, to
++ preserve the fact that the time is strictly before the 30 second mark.
++
++ \note For negative years, the YearWithinCentury will be understood as the
++ number of completed years since the start of the most recent year that is a
++ multiple of 100. Thus year -1 (which Qt understands, when using the
++ Gregorian calendar, to mean 1 BCE) has a YearWithinCentury value of 99,
++ since the last year that's a multiple of 100 is -100 (for Gregorian, 100
++ BCE).
++
++ \omitvalue EndCategories
++
++ \sa {QtTemporalPattern::}{TemporalFieldFlag}, {QtTemporalPattern::}{DateTimePart}
++ */
++
++ /* For numbers as narrow days of the week, at least three different numberings
++ are used, all of which are used in locales whose "first day of the week" is
++ Monday. (Furthermore, some locales with digits as narrow names only do that
++ for some days, with letters for others.) So there is no way to determine how
++ days of the week are numbered from one locale to the next, except in so far
++ as their narrow Verbal or Standalone forms use digits. A Numeric version of
++ the day of the week field would thus either not know what to do for most
++ locales, be inconsistent between locales or be inconsistent, for some
++ locales, between Narrow Verbal / Standalone formats and Numeric format.
++ Hence the lack of a meaning of Numeric for DayOfWeek.
++
++ Some locales use month numbers for the narrow format of months; but none are
++ known to do so inconsistently with the usual month numbering (although Pashto
++ does this only partially, using non-numeric narrow standalone forms for the
++ first two months). This does still conflict with the numeric form of months,
++ at least in some cases, that use ASCII digits for narrow forms of month
++ numbers but locale-appropriate digits for their numeric forms. However, the
++ conflict is only in how the numbers are represented, not in the numeric
++ values used for months.
++ */
++
++ /*!
++ \internal
++ \namespace QtTemporalPattern::FieldGroup
++ \brief Masks identifying mutually-exclusive families of options.
++
++ Each constant in this namespace is of type \l {QtTemporalPattern::}
++ {TemporalFieldFlags} and combines a mutually-exclusive family of \l
++ {QtTemporalPattern::} {TemporalFieldFlag} values into a mask by which to
++ identify that family. Within each such family, if none of the flags is
++ specified, any of them may be applied but if any of them are specified then
++ only one of those specified may be applied.
++
++ \value FormMask The three general forms of a field: numeric, verbal and
++ standalone.
++ \value WidthMask The four field widths: wide, short, abbreviated, and
++ narrow.
++ \value UtcPrefixMask The two options for prefixes on offset forms of
++ timezones, with and without a UTC prefix.
++ \value PaddingMask The two padding options for when fields don't fill the
++ width allotted to them: spaces and zeros.
++ \value SeasonMask The three perspectives from which to describe a timezone:
++ the generic, regardless of the time of year, the standard,
++ and how it's described when exercising daylight-saving
++ time (if it does at all).
++ */
++ /* Namespace QtParseCommon has helper functions, defined in qtparsetimezone_p.h,
++ to apply the above rule related to these masks.
++ */
++
++ /*!
++ \enum QtTemporalPattern::TemporalFieldFlag
++
++ This enumeration describes how datetime fields are expressed in text.
++
++ A combination of these flags is used to qualify a \l {QtTemporalPattern::}
++ {TemporalFieldCategory}, indicating whether it is conveyed by words or
++ numbers, how tersely or in which terms, depending on the field
++ category. Interpretation of a flag in this enumeration varies with the field
++ category it is qualifying and with other flags combined with it.
++
++ Some flags, such as the four width options, are mutually exclusive. For each
++ group of mutually-exclusive flags, a mask constant is defined in namespace
++ QtTemporalPattern::FieldGroup, of type \l {QtTemporalPattern::}
++ {TemporalFieldFlags}, that combines the members of that group. If no member
++ of such a group is set in a flags variable, it is treated as if all members
++ of that group were set. When serializing, the behavior when two or more
++ conflicting flags, in a group relevant to the field, are combined is
++ unspecified. It may depend on other fields or variables passed to the
++ serialization function. When parsing, such conflicting flags allow the
++ parser to match any of the conflicting options specified. If this leads to
++ ambiguity, parsing prefers the option that consumes more of the text to
++ parse.
++
++ Unless otherwise indicated, fields are localized. For example, ZeroPad pads
++ with, and Numeric uses, locale-appropriate digits when localized, and the
++ names of months, days of the week and timezones are translated into the
++ appropriate language (if possible).
++
++ The primary distinction in how fields are expressed is the form of the
++ field. These first three options are mutually incompatible and are grouped
++ together as the \l {QtTemporalPattern::FieldGroup::} {FormMask} constant:
++
++ \value Numeric Express the field numerically as a series of digits.
++ \value Verbal Name the field value in its usual in-format grammatical form.
++ \value Standalone Name the field value in its stand-alone grammatical form.
++
++ Next comes the width of the field. The meanings of these fields depends on
++ other flags and the field category, where relevant. Some field categories
++ may ignore these entirely, others may draw fewer distinctions and use the
++ same meaning for some widths. These four options are mutually exclusive and
++ grouped together as the \l {QtTemporalPattern::FieldGroup::} {WidthMask}
++ constant:
++
++ \value Narrow Use a the narrowest supported form for the field. In some
++ locales, the Narrow Verbal forms of some fields may use
++ numbers, potentially conflicting with one of its Numeric
++ forms.
++ \value Abbreviated Use an abbreviated form of the field.
++ \value Short Use a short form of the field.
++ \value Wide Use a wide form of the field.
++
++ \section2 Padding
++
++ Where a \c width is specified for a field but the field's value is naturally
++ shorter, it is necessary to indicate how to pad it to the desired width.
++ These two options are mutually exclusive and grouped together as the \l
++ {QtTemporalPattern::FieldGroup::} {PaddingMask} constant:
++
++ \value ZeroPad Only for numeric fields: pad to \c width with zeros. When
++ parsing, accept zeros that don't affect value, reject fields
++ that are narrower than their specified \c width.
++ \value SpacePad For a field with a positive \c width, pad to that \c width
++ with spaces. When parsing, allow leading and trailing
++ spacing characters.
++
++ If neither form of padding is indicated, the natural representation of a
++ value is used even if it fails to reach the \c width specified and parsing
++ will accept a narrower field (although it will prefer a match with full
++ width). In a \l {QtTemporalPattern::TemporalFieldCategory} {TimeZone} field
++ (see below) using an offset form, SpacePad is ignored and ZeroPad or its
++ absence only has its usual meaning for hour fields, while controlling the
++ presence of zero minute and second offsets following the hour field.
++
++ \section2 Space
++
++ Where a text to be matched (for example, a literal or the name of a month or
++ day of the week) contains spaces, by default plain space (ASCII SPACE,
++ U+0020) and the various Unicode spacing characters outside the ASCII range
++ (of various widths, some of them non-breaking) are all accepted as matches
++ for one another, while the number and placement of such short horizontal
++ spaces must match. Other spacing characters (newline, tab, etc.) must match
++ exactly. Since users commonly do not distinguish the short horizontal
++ spaces, this default usually suffices. In some cases, there may be reason to
++ insist on exact matching of spaces, without treating short horizontal spaces
++ as equivalent. Where the text to be parsed is taken from a larger text,
++ however, it's also possible that this larger text has been flowed, as a
++ paragraph, which may have turned some spaces into line breaks, possibly with
++ added indentation, or the text may be split across a page boundary. Coping
++ with such cases is supported by the options
++
++ \value FlexSpace Where a field to be matched contains spacing characters, or
++ a run of them, any spacing character or run of them will be
++ accepted as matching. A character is deemed to be a spacing
++ character if \l QChar::isSpace() is true for it.
++ \value StrictSpace Spacing characters must be matched exactly.
++ Ignored if FlexSpace is also set.
++
++ \section2 Letter case
++
++ The following options are only relevant to Verbal and Standalone
++ fields. They are not treated as a group or descrbed by a mask, as the locale
++ provides relevant fields with the appropriate (possibly mixed) case for the
++ lcoale. By default, the locale's form is used when serializing and matched
++ (case-sensitively) when parsing. The first two of these are mutually
++ exclusive. They change that default, forcing the case when serializing and
++ requiring the specified case (or one of the specified cases) when
++ parsing. The third has no effect when serializing and overrides the other
++ two, if either is present, when parsing.
++
++ \value LowerCase When serializing, force lower-case.
++ \value UpperCase When serializing, force upper-case.
++ \value IgnoreCase When parsing, match the field case-insensitively.
++
++ \section2 Extended fields
++
++ The following options modify the handling of specific fields where there is
++ no intrinsic limit to the number of significant digits in a valid value.
++ They are described in more detail below.
++
++ \value RoundFraction Allows excess precision in a fractional part.
++ \value YearSignIso8601 Requires a sign if there are extra digits in a year.
++
++ By default a \l {QtTemporalPattern::TemporalFieldCategory} {SecondFraction}
++ field only accepts up to three digits or as many digits as its field width
++ specifies. The RoundFraction modifies the field to allow more digits than
++ this, using the excess precision only to resolve rounding to the appropriate
++ precision, as described above for the SecondFraction field.
++
++ Modern revisions of ISO 8601 permit years outside the range from 0 through
++ 9999 but require that they have a sign. By default a + sign on a positive
++ year is allowed and silently ignored (without counting towards its \c
++ width), but the YearSignIso8601 applies a modified version of the ISO rule:
++ the year field will only match a text with more digits than its specified \c
++ width if that text starts with a sign. When the field's \c width is 4, this
++ implements the ISO rule, but it can be applied to other widths, if needed.
++
++ In contrast to ISO's use of year 0000 to indicate 1 BCE, with negative year
++ values representing successively earlier years, where the calendar in use
++ has no year zero, Qt describes the year before year 1 as year -1, skipping
++ over 0 and treating 0 as an invalid value for the year. In particular, this
++ applies to the Gregorian calendar, which is used by default: 1 CE is
++ represented as year 1, with 1 BC as year -1. If the calendar in use reports
++ \c true from \l {QCalendar::} {hasYearZero()}, Qt duly accepts a year 0
++ between years -1 and +1. ISO also specifies that years before 1583 (the
++ first full year after the Gregorian calendar came into play) or after 9999
++ should not be used except by prior agreement between the producer and
++ consumer of the serialized date or datetime. Qt leaves such agreement as a
++ matter between the user and those they communicate with, simply accepting
++ any year number within the range of QDate or QDateTime, as appropriate.
++
++ \section2 Timezone representation
++
++ The following options are only relevant to timezones. If used with other
++ categories of field, they are ignored. By default, when the other fields of
++ a timestamp determine a datetime, the zone's localized name in effect at
++ that datetime is used when serializing and matched when parsing.
++
++ There are both localized and international standard formats available. The
++ following pair of options select which of those to use. They are grouped
++ together as the \l {QtTemporalPattern::FieldGroup::} {LocalizationMask}
++ constant:
++
++ \value LocalizedZone For a TimeZone, use localized forms.
++ \value Iso8601 For a TimeZone, use an ISO 8601 offset format.
++
++ When both are specified, or neither is, localized forms are preferred. See
++ \l {Locale-independent offset forms}, below, for details of the ISO
++ 8601-based formats. See \c{Standalone | Short} below for the IANA DB and
++ \l{Local time} for a system-dependent form, both of which ignore the choice
++ between LocalizedZone and Iso8601.
++
++ The following three options, selecting seasonal variations, are mutually
++ exclusive and only relevant to Verbal or Standalone forms. They are
++ independent of the choice between LocalizedZone and Iso8601. They are
++ grouped together as the \l {QtTemporalPattern::FieldGroup::} {SeasonMask}
++ constant:
++
++ \value GenericTime For a non-Numeric TimeZone, use its generic name.
++ \value StandardTime For a non-Numeric TimeZone, use its standard-time name.
++ \value DaylightSavingTime For a non-Numeric TimeZone, use its
++ daylight-saving name.
++
++ For localized timezones, Numeric selects a basic offset format or an offset
++ format with a base prefix (typically a localized form of UTC or GMT), Verbal
++ selects a form of the zone's name, and Standalone selects the IANA ID or a
++ localized name based on a city that serves as exemplar for the zone (for the
++ given locale). The effects of the width options above then depend on which
++ of these is used. When LocalizedZone is set, the following forms are
++ available:
++
++ \list
++ \li For Numeric, the timezone offset is used:
++ \list
++ \li Wide uses the hour, minute and second, as for Short, but when
++ parsing it will accept a fractional part of the seconds (following
++ the locale-appropriate separator, after the whole number part of
++ the seconds), if present. As Qt only supports whole numbers of
++ seconds as offsets, this fractional part's only effect is to round
++ up the second part if it is at least a half second. (See note on
++ rounding in the next section.)
++ \li Short uses the hour, minute and second, rounding to the nearest
++ second if the offset is not a whole number of seconds.
++ \li Abbreviated uses the hour and minute, rounding to the nearest
++ minute if the offset is not a whole number of minutes.
++ \li Narrow uses the hour, rounding to nearest if the actual offset is
++ not a whole number of hours.
++ \endlist
++ \li For Verbal, the zone name is used:
++ \list
++ \li Wide uses the full name of the zone, e.g. "Pacific Time", "Pacific
++ Standard Time" or "Pacific Daylight Time", depending on season.
++ \li Short is treated as Wide.
++ \li Abbreviated uses the zone abbreviation, e.g. "PT", "PST" or "PDT".
++ Note that these cannot be reliably parsed.
++ \li Narrow is treated as Abbreviated.
++ \endlist
++ \li For Standalone, the city name:
++ \list
++ \li Wide uses the locale's generic location format, such as "Los
++ Angeles Time".
++ \li Short uses the full IANA ID, such as America/Los_Angeles.
++ This is not localized (the LocalizedZone flag is ignored).
++ \li Abbreviated just gives the localized exemplar city, e.g. "Los
++ Angeles".
++ \li Narrow is treated as Abbreviated.
++ \endlist
++ \endlist
++
++ Where a timezone is specified simply in terms of an offset from UTC, it does
++ not necessarily have an associated city or a name other than its offset
++ representations. For such zones, when serializing, Verbal and Standalone are
++ treated as Numeric, with the exception of \c{Staldalone | Short}, as the
++ IANA ID is not localized and this form, like an IANA ID, is accepted by the
++ QTimeZone(QByteArray) constructor. (Note that these do not include ZeroPad:
++ see the next section for its effect on offset forms.) When parsing,
++ therefore, these offset formats are accepted for the Verbal and Standalone
++ forms that would map to them for offset zones. This applies to \l
++ {QTimeZone::fromDurationAheadOfUtc()} lightweight time representations (for
++ which \l {QTimeZone::}{isUtcOrFixedOffset()} is true) as well as to those,
++ with a UTC-offset backend, constructed by QTimeZone(int) or, with an ID of
++ form \c{"UTC"} or \c{"UTC±HH:mm"}, by QTimeZone(QByteArray),
++
++ \section3 Offset modifiers
++
++ In the various timezone offset formats (both above and below), there are
++ potentially hour, minute and second parts of the offset, depending on the
++ width option selected. The minute and second parts, when present, always use
++ two digits, rendering the usual meaning of ZeroPad redundant. Instead, for
++ these parts, ZeroPad controls whether trailing zero parts are included.
++ When ZeroPad is set they are included when serializing and required to be
++ present when parsing. When ZeroPad is not set, they are omitted when
++ serializing and, if trailng parts are missing when parsing, they are taken
++ to have value zero. Zero parts are always accepted when parsing, even when
++ ZeroPad is not set.
++
++ The hour part of an offset is never omitted when serializing and is always
++ required when parsing. When ZeroPad is not set, when parsing offset formats
++ with separators between parts, a single-digit hour is accepted. (For the
++ localized offset formats above, whether there are separators between parts
++ depends on the locale.) When ZeroPad is not set, serialization only produces
++ a single-digit hour if there are no later parts (typically because they were
++ all zero, hence omitted). Otherwise, the hour part is always serialized with
++ two digits and parsing requires it to have two digits.
++
++ As ever, if more than one width is specified, any given is allowed. On
++ serializing, narrower formats are preferred unless they lose precision in
++ the offset that an allowed longer format would include. Thus \c{Narrow |
++ Short} would include only the hours for a whole-hour offset, but would
++ include hours, minutes and seconds for an hour-and-a-half offset (albeit
++ omitting the zero seconds unless ZeroPad is set). Where the width thus
++ selected requires rounding due to omitting a part of the offset that isn't
++ zero, exact halves round away from zero. On parsing, the longest allowed
++ form for which a match is found will be used.
++
++ Offset formats may also include a prefix (localized in the forms above) that
++ identifies the offset as being relative to UTC or GMT. The following pair of
++ mutually exclusive options control whether that is omitted or included.
++ They are grouped together as the \l {QtTemporalPattern::FieldGroup::}
++ {UtcPrefixMask} constant:
++
++ \value AcceptUtcPrefix Include a UTC prefix on offsets when serializing and
++ require it when parsing.
++ \value NeedNoUtcPrefix Leave off the UTC prefix when serializing and reject
++ it when parsing.
++
++ If neither or both of these are specified, serializing omits the prefix and
++ parsing permits it but does not require it.
++
++ \section3 Locale-independent offset forms
++
++ In addition to these localized forms, a timestamp may also represent its
++ zone in a locale-independent offset form. In effect, this use the C locale,
++ with ASCII digits 0 through 9, the ASCII + and - as signs, and the ASCII
++ colon as separator (where relevant). These are selected by the \c Iso8601
++ flag.
++
++ \value AllowZSuffix Modifies Iso8601 to allow use of a \c{Z} suffix to
++ denote a zero UTC offset. See RFC 9557 note below.
++
++ If AllowZSuffix is set and ZeroPad is not, serialization will use \c{Z} to
++ represent a zero offset. When ZeroPad is set, serialization ignores
++ AllowZSuffix. If AllowZSufix is set, regardless of ZeroPad, parsing will
++ accept a \c{Z} suffix as meaning zero offset.
++
++ The Iso8601 format is modified by other flags as follows (when not using
++ \c{Z} to represent a zero offset):
++ \list
++ \li With Numeric it uses a basic format (with no separators), with Verbal
++ or Standalone it uses separators between hours, minutes and seconds,
++ in so far as these appear.
++ \li The width options Wide, Short, Abbreviated and Narrow have the same
++ meanings as for Numeric localized offset formats, modified by the
++ ZeroPad option, as described above.
++ \endlist
++
++ \note In some contexts, notably where \l
++ {https://www.rfc-editor.org/rfc/rfc9557.html} {RFC 9557} is used, a zone
++ indicator on a timestamp may be understood as giving context to the
++ information in which it appears, as opposed to only indicating the zone with
++ respect to which the timestamp itself is expressed. In such contexts, a
++ \c{Z} suffix, applied by \c AllowZSuffix, only indicates that the timestamp
++ itself is given with respect to UTC and does not give any context to the
++ information in which it appears. For contrast, in such contexts, a +00:00
++ suffix does indicate not only that the timestamp is given in UTC but also
++ that UTC is the relevant zone for the context of the information. Prior to
++ RFC 9557, some RFCs (incompatibly with ISO 8601) proposed using -00:00 to
++ indicate what RFC 9557 has specified as the meaning for a \c{Z}
++ suffix. Nothing in Qt attends to this distinction.
++
++ \section3 Local time
++
++ Where Qt can determine how the local system describes its local time, Qt has
++ no control over the form in which the system supplies it, nor does Qt know
++ whether, or how, it is localized, with the result that this representation
++ is system-dependent. As another system may be using a different local time,
++ or representing it differently, there is no guarantee that what one system
++ supplies for local time can be successfully understood on another system. To
++ opt in to using this system-dependent representation of local time, supply
++ the following option. Even then, when serializing, if the options given
++ permit any other available representation of the timezone, that is preferred
++ over this.
++
++ \value LocalTimeName Allow the system-supplied local time name to describe
++ the system's local time.
++
++ The system local time may come in separate forms for standard time and
++ daylight-saving time. When it does, the options above for selecting between
++ these affect LocalTimeName as usual, with GenericTime ignored.
++
++ \sa {QtTemporalPattern::}{TemporalFieldCategory}, {QtTemporalPattern::}{TemporalFieldFlags}
++ */
++ // RFC 9557: see QTBUG-114172
++
++ // TemporalFieldFlags and DateTimeParts: docs taken care of automagically by
++ // QDoc, recognizing QFLAG() usage.
++
++ /*!
++ \fn constexpr bool QtTemporalPattern::matchesFlagWithin(QtTemporalPattern::TemporalFieldFlags flags, QtTemporalPattern::TemporalFieldFlag sought, QtTemporalPattern::TemporalFieldFlags group)
++
++ Tests \a flags for a \a sought flag within a \a group.
++
++ Implements the per-flag check for a single TemporalFieldFlag with respect to
++ its FieldGroup entry. If no flag in a group is given in \a flags, then all
++ flags in the group are allowed; otherwise, only the given flags in the group
++ match.
++ */
++
++ /*!
++ \fn constexpr bool QtTemporalPattern::matchesFlagsWithin(QtTemporalPattern::TemporalFieldFlags flags, QtTemporalPattern::TemporalFieldFlags sought, QtTemporalPattern::TemporalFieldFlags group)
++
++ Similar to \l matchesFlagWithin(), but if any of those \a sought is found in
++ \a flags, or if none of group are, it's counted as a match.
++
++ In some contexts, some flags are treated as equivalent, so to check for what
++ they represent pass the equivalent flags |-joined as \a sought.
++ */
++
++
++ /*!
++ \enum QtTemporalPattern::DateTimePart
++ \brief This enumeraction classifies the various field categories.
++
++ The classification addresses which parts of a datetime a field contributes
++ data to.
++
++ \value None A literal field contributes no data.
++ \value Date Various fields contribute to the date.
++ \value Time Various fields contribute to the time.
++ \value Zone Only the \l {QtTemporalPattern::TemporalFieldFlag::}{TimeZone}
++ field contributes information about the timezone.
++
++ These may be combined in a \l {QtTemporalPattern::}{DateTimeParts} to
++ express a set of parts that a set of fields might suffice to describe,
++ whether fully or only in part.
++
++ \sa {QtTemporalPattern::}{TemporalFieldCategory}, {QtTemporalPattern::}{supports()}
++ */
++
++ /*!
++ \fn QtTemporalPattern::classify(QtTemporalPattern::TemporalFieldCategory category) noexcept
++ \brief Classify a field category according to the part of a datetime it contributes to.
++
++ This maps a \l {QtTemporalPattern::}{TemporalFieldCategory} to the \l
++ {QtTemporalPattern::}{DateTimePart} for which it supplies data.
++ */
++
++ /*!
++ \class QtTemporalPattern::TemporalField
++ \brief Describes one field in a temporal pattern.
++
++ A single field is characterized by its \l
++ {QtTemporalPattern::TemporalFieldCategory}{category}, some \l
++ {QtTemporalPattern::TemporalFieldFlags}{options} identifying how the field
++ is to be expressed and, where relevant, a datum. For a Literal field, the
++ datum is the string to be matched.
++
++ For numeric fields, a width may optionally be specified, indicating
++ the expected number of digits in the field. If options specifies
++ zero-padding, this is a minimum number of digits; otherwise, shorter fields
++ are accepted. In any case, longer values are accepted, where the resulting
++ numeric value is valid for the field. A zero width does not mean an empty
++ field will be accepted: it is effectively equivalent to a width of 1.
++
++ \note in some locales, the digits may require surrogate pairs to encode, so
++ the UTF-16 length of the field may exceed the number of digits. In a year
++ field with a sign, the sign does not count towards the width of the
++ field. The width only counts digits. The width is, in any case, a lower
++ bound: more digits may be read, if present and not consumed by some later
++ field. The \c endIndex of any parse result is the only reliable source of
++ truth on the UTF-16 end of the text parsed.
++ */
++ // TODO: should we support digit grouping in year numbers, at least with > 4 digits ?
++
++ /*!
++ \fn QtTemporalPattern::hasFieldsFor(QSpan<const QtTemporalPattern::TemporalField> range)
++ \brief Identify the parts to which the given fields contribute data.
++
++ Takes a \a range of TemporalField instances and returns a \l
++ {QtTemporalPattern::}{DateTimeParts} indicating which parts \l classify()
++ says any of the fields contribute to. Note that this only tessts for
++ contribution to a part, not for full coverage of the part. See \l supports()
++ for that.
++
++ \sa classify(), supports()
++ */
++
++ /*!
++ \enum QtTemporalPattern::SupportType
++ \brief This enumeration identifies how well some fields describe requested datetime parts.
++
++ The fields of a pattern may contain partial or complete data on each of the
++ \l {QtTemporalPattern::TemporalFieldPart}{parts of} a datetime. When parsing
++ or serializing only a date or only a time, fields for the other or for
++ timezone are extraneous, making the pattern unable to serialize just the
++ intended type, as it lacks the data for those fields. It would also, when
++ parsing, be obliged discard some of the data it parses, as the type it
++ returns cannot express it.
++
++ When serializing a datetime, if the fields present do not suffice to fully
++ encode the date or time, it will not be possible for a reader of the
++ resulting text to unambiguously determine the datetime. If timezone is not
++ specified, it is possible to convert the datetime to some specific choice of
++ zone: provided both ends of the communication use the same zone, it is then
++ possible to recover the exact point in time, albeit without knowing the
++ timezone originally used to encode it.
++
++ Where data is partially supplied, it is possible that the partial data
++ suffices to meet the readers needs, although this typically involves the
++ reader in making some default assumptions about the missing fields. For
++ example, a two-digit year may need some assumptions about the century
++ (possibly aided by information about the date and day of the week) to
++ determine what year to presume the sender intended.
++
++ \value None No fields were found.
++ \value HasStrays Some field not relevant to the requested parts was present.
++ \value Partial Either some requested part is present and some other is
++ missing or some fields for a requested part are present but
++ not enough to fully describe that part.
++ \value Clear Enough fields of the requested parts were found to fully
++ determine them and no fields of unwanted parts were present.
++
++ Where partial fields for the requested parts were found along with fields
++ for unwanted parts, HasStrays is used in preference to Partial, as it is
++ considered a more significant defect.
++
++ \sa {QtTemporalPattern::}{TemporalFieldPart}, {QtTemporalPattern::}{supports()}
++ */
++
++ /*!
++ \fn QtTemporalPattern::supports(QtTemporalPattern::DateTimeParts wanted, QSpan<QtTemporalPattern::TemporalField> range, bool hasBaseYear) noexcept
++ \brief Assess how well the given fields support the \a wanted parts.
++
++ If any field in \a range belongs to a part not included in \a wanted,
++ returns \l {SupportType::}{HasStrays}. Otherwise,
++
++ \list
++ \li If no fields are present, aside from \l
++ {TemporalFieldCategory::}{Literal} ones, returns \l
++ {SupportType::}{None}.
++ \li If the fields present completely specify all parts in \a wanted,
++ returns \l {SupportType::}{Clear}.
++ \li If some fields are specified but some \a wanted part is inadequately
++ specified, or entirely unspecified, returns \l
++ {SupportType::}{Partial}.
++ \endlist
++
++ For these purposes,
++
++ \list
++ \li The \l {DateTimePart::}{Zone} part is specified by the \l
++ {TemporalFieldCategory::}{TimeZone}.
++ \li The \l {DateTimePart::}{Time} part is specified by any combination of
++ fields that identify the hour and minute. If the \l
++ {TemporalFieldCategory::}{SecondFractions} field is present, the part is
++ considered incompletely specified unless the \l
++ {TemporalFieldCategory::}{Seconds} field is also present.
++ \li The \l {DateTimePart::}{Date} part is specified by any combination of
++ fields that identify a date. This usually means \l
++ {TemporalFieldCategory::}{Year}, \l {TemporalFieldCategory::}{Month}
++ and \l {TemporalFieldCategory::}{DayOfMonth} although Year may be
++ indirectly specified by \l
++ {TemporalFieldCategory::}{YearWithinCentury} if the presence of \l
++ {TemporalFieldCategory::}{DayOfWeek} enables disambiguation among
++ centuries close to the present, given the other date fields.
++ \endlist
++ */
++
++ template <typename Enum, size_t Size>
++ class EnumIndexedBitSet
++ {
++ std::bitset<Size> bits;
++ static size_t map(Enum cat) { return qToUnderlying(cat); }
++ public:
++ void set(Enum cat) { bits[map(cat)] = true; }
++ bool test(Enum cat) const { return bits[map(cat)]; }
++ };
++
++ SupportType supports(DateTimeParts wanted, QSpan<const TemporalField> range,
++ bool hasBaseYear) noexcept
++ {
++ // TODO: may need to take into account calendar (and perhaps locale).
++ SupportType support = SupportType::HasStrays;
++ SupportType zone = SupportType::None;
++ EnumIndexedBitSet<TemporalFieldCategory, EndTemporalFieldCategories> categories;
++ for (const TemporalField &field : range) {
++ const DateTimePart part = field.part();
++ switch (part) {
++ case DateTimePart::None: // Literal contributes no data.
++ continue;
++ case DateTimePart::Date:
++ case DateTimePart::Time:
++ categories.set(field.category);
++ break;
++ case DateTimePart::Zone:
++ if (field.options.testAnyFlags(TemporalFieldFlag::Wide | TemporalFieldFlag::Short)
++ || field.options.testAnyFlags(TemporalFieldFlag::Numeric
++ | TemporalFieldFlag::Standalone
++ | TemporalFieldFlag::Iso8601)) {
++ zone = SupportType::Clear;
++ } else if (zone == SupportType::None) {
++ // Zone name abbreviation: does not uniquely identify zone.
++ zone = SupportType::Partial;
++ }
++ break;
++ }
++ if (!wanted.testFlag(part))
++ return support;
++ }
++
++ bool partsSeen = wanted.testFlag(DateTimePart::Zone);
++ support = partsSeen ? zone : SupportType::None;
++
++ constexpr auto join = [](SupportType lhs, SupportType rhs) -> SupportType {
++ Q_PRE(lhs != SupportType::HasStrays);
++ Q_PRE(rhs != SupportType::HasStrays);
++ // For combining SupportTypes from different Parts to determine support
++ // for their composite. Simplest case is when they're the same:
++ if (lhs == rhs)
++ return lhs;
++ // Every combination of distinct values among the other three is partial:
++ return SupportType::Partial;
++ };
++
++ #define CHECK(field) (categories.test(TemporalFieldCategory::field))
++
++ if (wanted.testFlag(DateTimePart::Date)) {
++ const SupportType hasDate = [&] {
++ // if (CHECK(JulianDay)) return SupportType::Clear;
++ int fields = 0;
++ bool partial = false;
++ if (CHECK(Year)) {
++ ++fields;
++ } else if (CHECK(YearWithinCentury)) {
++ if (hasBaseYear) {
++ ++fields;
++ // } else if (CHECK(Century)) { ++fields;
++ } else if (CHECK(DayOfWeek) && CHECK(DayOfMonth) && CHECK(Month)) {
++ // We can infer century from those three by assuming it's
++ // close to the present.
++ ++fields;
++ } else {
++ partial = true;
++ }
++ // } else if (CHECK(Century)) { partial = true;
++ }
++ if (CHECK(Month))
++ ++fields;
++ if (CHECK(DayOfMonth))
++ ++fields;
++ else if (CHECK(DayOfWeek))
++ partial = true;
++ if (fields == 3 && !partial)
++ return SupportType::Clear;
++ if (fields || partial)
++ return SupportType::Partial;
++ return SupportType::None;
++ }();
++ support = partsSeen ? join(support, hasDate) : hasDate;
++ partsSeen = true;
++ }
++
++ if (wanted.testFlag(DateTimePart::Time)) {
++ const SupportType hasTime = [&] {
++ // if (CHECK(MillisecondInDay)) return SupportType::Clear;
++ int fields = 0;
++ bool partial = false;
++ if (CHECK(Hour)) {
++ ++fields;
++ } else if (CHECK(HourMod12)) {
++ if (CHECK(PeriodInDay))
++ ++fields;
++ else
++ partial = true;
++ } else if (CHECK(PeriodInDay)) {
++ partial = true;
++ }
++ if (CHECK(Minute))
++ ++fields;
++ // Hour and minute are required, but seconds and later are optional;
++ // however, having a finer field without an coarser one leaves a gap => Partial.
++ if (CHECK(Second))
++ partial = fields < 2;
++ else if (CHECK(SecondFraction))
++ partial = true;
++ if (fields == 2 && !partial)
++ return SupportType::Clear;
++ if (fields || partial)
++ return SupportType::Partial;
++ return SupportType::None;
++ }();
++ support = partsSeen ? join(support, hasTime) : hasTime;
++ partsSeen = true;
++ }
++
++ #undef CHECK
++
++ // Shall still be None if we've seen no fields:
++ Q_ASSERT(partsSeen || support == SupportType::None);
++ return support;
++ }
++
++ } // namespace QtTemporalPattern
++
++ /*!
++ \internal
++ \since 6.12
++ \class QDateTimePattern
++ \brief A description of a serialization format for a datetime
++ */
++
++ /*!
++ \fn QDateTimePattern::forLocale(const QLocale &locale, QLocale::FormatType format)
++ Construct a QDateTimePattern appropriate to the given \a locale.
++
++ The \a format can be used to select how compact or expansive the pattern is.
++
++ \sa fromQtFormat()
++ */
++
++ /*!
++ \fn QDateTimePattern::isNull() const noexcept
++
++ Returns \c true if this pattern has no fields, otherwise \a false.
++
++ \sa fromQtFormat()
++ */
++
++ /*
++ //! [is-valid]
++ Returns \c true if this pattern can be used to reliably transmit {\1}s.
++
++ Returns \c false if there is unresolved ambiguity in the texts it will
++ produce when serializing or the texts that will match it when parsing.
++ Some apparent ambiguities may be resolved by interactions between other
++ fields or the \c{defaults} parameter to \l{parse()}.
++ //! [is-valid]
++ */
++
++ // TODO: currently (see supports(), above) doesn't take locale or calendar into account.
++ /*!
++ \fn QDateTimePattern::isValid() const noexcept
++
++ \include qttemporalpattern.cpp {is-valid} {datetime}
++ \include qttemporalpattern.cpp base-year-disambiguates
++
++ Timezone abbreviations are ambiguous.
++
++ \sa isNull()
++ */
++
++ /*!
++ \fn QDateTimePattern::setLocale(const QLocale &loc) noexcept
++
++ //! [set-locale]
++ Sets the locale, for use for fields whose representation depends on locale,
++ to \a loc. By default the application's current default locale is used.
++
++ \sa QLocale::setDefault()
++ //! [set-locale]
++ */
++
++ /*!
++ \fn QDateTimePattern::locale() const noexcep
++
++ Returns the current locale in use by this pattern.
++
++ \sa setLocale()
++ */
++
++ /*!
++ \fn QDateTimePattern::setCalendar(QCalendar calendar) noexcept
++
++ \include qttemporalpattern.cpp set-calendar
++ */
++
++ /*!
++ \fn QDateTimePattern::calendar(QCalendar calendar) const noexcept
++
++ Returns the current calendar in use by this pattern.
++
++ \sa setCalendar()
++ */
++
++ /*!
++ \fn QDateTimePattern::setBaseYear(int centuryStart) noexcept
++
++ \include qttemporalpattern.cpp set-base-year
++ */
++
++ /*!
++ \fn QDateTimePattern::clearBaseYear() noexcept
++
++ \include qttemporalpattern.cpp clear-base-year
++ */
++
++ /*!
++ \fn QDateTimePattern::baseYear() const noexcept
++
++ \include qttemporalpattern.cpp get-base-year
++ */
++
++ /*!
++ Parse and return the datetime represented by \a text.
++
++ //! [parser-defaults]
++ If \a defaults is provided and valid, any fields the format described by
++ this pattern does not provide will be copied from \a defaults to construct
++ the returned value.
++ //! [parser-defaults]
++ */
++
++ QtTemporalPattern::ParseResult<QDateTime>
++ QDateTimePattern::parse(QStringView text, const QDateTime &defaults) const
++ {
++ #if QT_CONFIG(datetimeparser)
++ const auto seen = QtParseTemporal::prefix(text, m_fields, m_locale, m_calendar, m_baseYear);
++ if (!m_fields.isEmpty() && !seen) // Failed to parse.
++ return {};
++
++ const QDate date = seen.date(m_calendar, defaults.date());
++ const QTime time = seen.time(defaults.time());
++
++ if (QDateTime result(date, time, seen.zone, seen.resolveType()); result.isValid())
++ return {std::move(result), seen.size()};
++ // Fall back to default transition resolution:
++ return {QDateTime(date, time, seen.zone), seen.size()};
++ #else
++ Q_UNUSED(text);
++ Q_UNUSED(defaults);
++ return {};
++ #endif // datetimeparser
++ }
++
++ /*!
++ Serialize the given \a datetime to a string representation.
++ */
++
++ QString QDateTimePattern::serialize(const QDateTime &datetime) const
++ {
++ Q_UNUSED(datetime);
++ return {};
++ }
++
++ /*!
++ Construct a QDateTimePattern described by the given \a format string.
++
++ If the format is empty or malformed, the returned pattern's \c isNull() shall
++ be \c true. Otherwise, \c isNull() shall be \c false.
++
++ \sa forLocale(), isNull()
++ */
++
++ QDateTimePattern QDateTimePattern::fromQtFormat(QStringView format)
++ {
++ using namespace QtTemporalPattern;
++ constexpr DateTimeParts form = DateTimePart::Date | DateTimePart::Time | DateTimePart::Zone;
++ const auto qt = QtParseQtTemporalFormat::prefix(format, form);
++ if (qt.size() == format.size())
++ return QDateTimePattern(qt.fields);
++ return QDateTimePattern({});
++ }
++
++ /*!
++ \internal
++ \since 6.12
++ \class QTimePattern
++ \brief A description of a serialization format for a time
++ */
++
++ /*!
++ \fn QTimePattern::forLocale(const QLocale &locale, QLocale::FormatType format)
++ Construct a QTimePattern appropriate to the given \a locale.
++
++ The \a format can be used to select how compact or expansive the pattern is.
++
++ \sa fromQtFormat()
++ */
++
++ /*!
++ \fn QTimePattern::isNull() const noexcept
++
++ Returns \c true if this pattern has no fields, otherwise \a false.
++
++ \sa fromQtFormat()
++ */
++
++ /*!
++ \fn QTimePattern::isValid() const noexcept
++
++ \include qttemporalpattern.cpp {is-valid} {time}
++
++ \sa isNull()
++ */
++
++ /*!
++ \fn QTimePattern::setLocale(const QLocale &loc) noexcept
++
++ \include qttemporalpattern.cpp set-locale
++ */
++
++ /*!
++ \fn QTimePattern::locale() const noexcep
++
++ Returns the current locale in use by this pattern.
++
++ \sa setLocale()
++ */
++
++ /*!
++ Parse and return the time represented by \a text.
++
++ \include qttemporalpattern.cpp parser-defaults
++ */
++
++ QtTemporalPattern::ParseResult<QTime>
++ QTimePattern::parse(QStringView text, QTime defaults) const
++ {
++ #if QT_CONFIG(datetimeparser)
++ const auto seen = QtParseTemporal::prefix(text, m_fields, m_locale, QCalendar());
++ if (!m_fields.isEmpty() && !seen) // Failed to parse.
++ return {};
++ return {seen.time(defaults), seen.size()};
++ #else
++ Q_UNUSED(text);
++ Q_UNUSED(defaults);
++ return {};
++ #endif // datetimeparser
++ }
++
++ /*!
++ Serialize the given \a time to a string representation.
++ */
++
++ QString QTimePattern::serialize(const QTime &time) const
++ {
++ Q_UNUSED(time);
++ return {};
++ }
++
++ /*!
++ Construct a QTimePattern described by the given \a format string.
++
++ If the format is empty or malformed, the returned pattern's \c isNull() shall
++ be \c true. Otherwise, \c isNull() shall be \c false.
++
++ \sa forLocale(), isNull()
++ */
++
++ QTimePattern QTimePattern::fromQtFormat(QStringView format)
++ {
++ using namespace QtTemporalPattern;
++ constexpr DateTimeParts form{DateTimePart::Time};
++ const auto qt = QtParseQtTemporalFormat::prefix(format, form);
++ if (qt.size() == format.size())
++ return QTimePattern(qt.fields);
++ return QTimePattern({});
++ }
++
++ /*!
++ \internal
++ \since 6.12
++ \class QDatePattern
++ \brief A description of a serialization format for a date
++ */
++
++ /*!
++ \fn QDatePattern::forLocale(const QLocale &locale, QLocale::FormatType format)
++ Construct a QDatePattern appropriate to the given \a locale.
++
++ The \a format can be used to select how compact or expansive the pattern is.
++
++ \sa fromQtFormat()
++ */
++
++ /*!
++ \fn QDatePattern::isNull() const noexcept
++
++ Returns \c true if this pattern has no fields, otherwise \a false.
++
++ \sa fromQtFormat()
++ */
++
++ /*!
++ \fn QDatePattern::isValid() const noexcept
++
++ \include qttemporalpattern.cpp {is-valid} {date}
++
++ //! [base-year-disambiguates]
++ The ambiguity of two-digit years may be resolved by configuring the hundred
++ years among which to select a matching years.
++ //! [base-year-disambiguates]
++
++ \sa setBaseYear(), isNull()
++ */
++
++ /*!
++ \fn QDatePattern::setLocale(const QLocale &loc) noexcept
++
++ \include qttemporalpattern.cpp set-locale
++ */
++
++ /*!
++ \fn QDatePattern::locale() const noexcep
++
++ Returns the current locale in use by this pattern.
++
++ \sa setLocale()
++ */
++
++ /*!
++ \fn QDatePattern::setCalendar(QCalendar calendar) noexcept
++
++ //! [set-calendar]
++ Sets the calendar used by this pattern. This influences the names and
++ lengths of months and how these vary from year to year. In some cases it may
++ also influence the number of months in the year or even the pattern and
++ names of days of the week.
++
++ By default the Gregorian calendar is used.
++
++ \sa getCalendar(), QCalendar
++ //! [set-calendar]
++ */
++
++ /*!
++ \fn QDatePattern::calendar(QCalendar calendar) const noexcept
++
++ Returns the current calendar in use by this pattern.
++
++ \sa setCalendar()
++ */
++
++ /*!
++ \fn QDatePattern::setBaseYear(int centuryStart) noexcept
++
++ //! [set-base-year]
++ Configures the handling of two-digit years, if any are present in the pattern.
++
++ If a two-digit year is present, the year ending in those two digits in the
++ range from \a centuryStart to \c {centuryStart + 99} shall be its default
++ interpretation. This may be amended if the month, day of the month and day
++ of the week indicate some other nearby century.
++
++ \note the years here, including \a centuryStart, are expressed with respect
++ to \c{calendar()}, whose year numbering need not match that of the Gregorian
++ calendar.
++
++ Calling this method makes no difference unless the pattern does in fact use
++ a two-digit year, nor does it affect serialization.
++
++ \sa clearBaseYear()
++ //! [set-base-year]
++ */
++
++ // TODO: should the default state be clear or some specific year ?
++ // That year could depend on the present, e.g. present minus 49 years.
++
++ /*!
++ \fn QDatePattern::clearBaseYear() noexcept
++
++ //! [clear-base-year]
++ Leaves the handling of two-digit years to other fields to disambiguate.
++
++ This is the default state, so has no effect unless \l setBaseYear() has
++ previously been called.
++
++ If a two-digit year is present, this leaves unspecified which hundred years
++ to presume it lies within. If a two-digit year is present and other fields
++ of the pattern do not suffice to make clear which hundred years to select
++ based on the given last two digits, the text produced when serializing with
++ this format shall generally be ambiguous. While readers of the text may be
++ able to disambiguate the year anyway, there is scope for misunderstanding if
++ their heuristics for doing so do not match your expectation. On parsing, the
++ pattern may deliver a result that is off by some whole number of centuries
++ from what the parsed text's author intended.
++
++ \sa setBaseYear(), isValid()
++ //! [clear-base-year]
++ */
++
++ /*!
++ \fn QDatePattern::baseYear() const noexcept
++
++ //! [get-base-year]
++
++ Returns the current base year, with respect to \c{calendar()}, used by this
++ pattern if it needs to resolve a two-digit year. The result is \c
++ {std::nullopt} when no base year is set, which is the default state.
++
++ \sa setBaseYear()
++ //! [get-base-year]
++ */
++
++ /*!
++ Parse and return the date represented by \a text.
++
++ \include qttemporalpattern.cpp parser-defaults
++ */
++
++ QtTemporalPattern::ParseResult<QDate>
++ QDatePattern::parse(QStringView text, QDate defaults) const
++ {
++ #if QT_CONFIG(datetimeparser)
++ const auto seen = QtParseTemporal::prefix(text, m_fields, m_locale, m_calendar, m_baseYear);
++ if (!m_fields.isEmpty() && !seen) // Failed to parse.
++ return {};
++ return {seen.date(m_calendar, defaults), seen.size()};
++ #else
++ Q_UNUSED(text);
++ Q_UNUSED(defaults);
++ return {};
++ #endif // datetimeparser
++ }
++
++ /*!
++ Serialize the given \a date to a string representation.
++
++ \sa parse()
++ */
++
++ QString QDatePattern::serialize(const QDate &date) const
++ {
++ Q_UNUSED(date);
++ return {};
++ }
++
++ /*!
++ Construct a QDatePattern described by the given \a format string.
++
++ If the format is empty or malformed, the returned pattern's \c isNull() shall
++ be \c true. Otherwise, \c isNull() shall be \c false.
++
++ \sa forLocale(), isNull()
++ */
++
++ QDatePattern QDatePattern::fromQtFormat(QStringView format)
++ {
++ using namespace QtTemporalPattern;
++ constexpr DateTimeParts form{DateTimePart::Date};
++ const auto qt = QtParseQtTemporalFormat::prefix(format, form);
++ if (qt.size() == format.size())
++ return QDatePattern(qt.fields);
++ return QDatePattern({});
++ }
++
++ QT_END_NAMESPACE