From bcb2cd49e534077d8b1e2d122d61823e4a3a5762 Mon Sep 17 00:00:00 2001 From: Edward Welbourne Date: Mon, 7 Oct 2024 17:38:55 +0200 Subject: [PATCH] Document potential problems with empty timezone names MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make clear that QTimeZone::displayName() may return an empty string and that Q(Date)?Time::toString() may consequently skip a zone text. In the process, fix a typo in the QTime::toString() docs and add the zone-naming formats to the mention of when applying QLocale::toString() to the Q(Date)?Time may be preferred, moving the earlier discussion of AM/PM that it joins to sit just after the table. Pick-to: 6.5 Change-Id: I313b8b1b452078421252a05aa599bc5f91d43105 Reviewed-by: Thiago Macieira (cherry picked from commit 5d18017213c110d5a99abeaf53cc4d29a6bfb660) Reviewed-by: MÃ¥rten Nordheim --- src/corelib/time/qdatetime.cpp | 21 +++++++++++++-------- src/corelib/time/qtimezone.cpp | 14 ++++++++------ 2 files changed, 21 insertions(+), 14 deletions(-) diff --git a/src/corelib/time/qdatetime.cpp b/src/corelib/time/qdatetime.cpp index 75cebcce32a..4cc989c8466 100644 --- a/src/corelib/time/qdatetime.cpp +++ b/src/corelib/time/qdatetime.cpp @@ -2152,8 +2152,10 @@ QString QTime::toString(Qt::DateFormat format) const \fn QString QTime::toString(const QString &format) const \fn QString QTime::toString(QStringView format) const - Returns the time as a string. The \a format parameter determines - the format of the result string. + Returns a string representing the time. + + The \a format parameter determines the format of the result string. If the + time is invalid, an empty string will be returned. These expressions may be used: @@ -2198,7 +2200,7 @@ QString QTime::toString(Qt::DateFormat format) const change of case. \row \li t \li The timezone abbreviation (for example "CEST"). Note that time zone - abbreviations are not unique. In particular, \l toString() cannot + abbreviations are not unique. In particular, \l fromString() cannot parse this. \row \li tt \li The timezone's offset from UTC with no colon between the hours and @@ -2216,6 +2218,14 @@ QString QTime::toString(Qt::DateFormat format) const in use. \endtable + \note To get localized forms of AM or PM (the \c{AP}, \c{ap}, \c{A}, \c{a}, + \c{aP} or \c{Ap} formats) or of time zone representations (the \c{t} + formats), use QLocale::system().toString(). + + When the timezone cannot be determined or no suitable representation of it + is available, the \c{t} forms to represent it may be skipped. See \l + QTimeZone::displayName() for details of when it returns an empty string. + Any non-empty sequence of characters enclosed in single quotes will be included verbatim in the output string (stripped of the quotes), even if it contains formatting characters. Two consecutive single quotes ("''") are @@ -2236,11 +2246,6 @@ QString QTime::toString(Qt::DateFormat format) const \row \li H:m:s a \li 14:13:9 pm \endtable - If the time is invalid, an empty string will be returned. - - \note To get localized forms of AM or PM (the AP, ap, A, a, aP or Ap - formats), use QLocale::system().toString(). - \note If a format character is repeated more times than the longest expression in the table above using it, this part of the format will be read as several expressions with no separator between them; the longest above, diff --git a/src/corelib/time/qtimezone.cpp b/src/corelib/time/qtimezone.cpp index cf0abf6cc8a..9318e31b9a7 100644 --- a/src/corelib/time/qtimezone.cpp +++ b/src/corelib/time/qtimezone.cpp @@ -928,12 +928,19 @@ QString QTimeZone::comment() const The name returned is the one for the given \a locale, applicable at the given \a atDateTime, and of the form indicated by \a nameType. The display name may change depending on DST or historical events. +//! [display-name-caveats] + If no suitably localized name of the given type is available, another name + type may be used, or an empty string may be returned. If the \a locale is not provided, then the application default locale will be used. For custom timezones created by client code, the data supplied to the constructor are used, as no localization data will be available for it. + If this timezone is invalid, an empty string is returned. This may also + arise for the representation of local time if determining the system time + zone fails. This method is only available when feature \c timezone is enabled. +//! [display-name-caveats] \sa abbreviation() */ @@ -967,12 +974,7 @@ QString QTimeZone::displayName(const QDateTime &atDateTime, NameType nameType, given \a timeType is in effect and of the form indicated by \a nameType. Where the time zone display names have changed over time, the current names will be used. - - If the \a locale is not provided, then the application default locale will - be used. For custom timezones created by client code, the data supplied to - the constructor are used, as no localization data will be available for it. - - This method is only available when feature \c timezone is enabled. + \include qtimezone.cpp display-name-caveats \sa abbreviation() */