1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document potential problems with empty timezone names

Browse Source 
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 <thiago.macieira@intel.com>
(cherry picked from commit 5d18017213c110d5a99abeaf53cc4d29a6bfb660)
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
This commit is contained in:
Edward Welbourne 2024-10-07 17:38:55 +02:00
parent 450dd785c0
commit bcb2cd49e5
2 changed files with 21 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
src/corelib/time/qdatetime.cpp
View File

@ -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,

14
src/corelib/time/qtimezone.cpp
View File

@ -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()
*/