Document potential problems with empty timezone names
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:
parent
450dd785c0
commit
bcb2cd49e5
@ -2152,8 +2152,10 @@ QString QTime::toString(Qt::DateFormat format) const
|
|||||||
\fn QString QTime::toString(const QString &format) const
|
\fn QString QTime::toString(const QString &format) const
|
||||||
\fn QString QTime::toString(QStringView format) const
|
\fn QString QTime::toString(QStringView format) const
|
||||||
|
|
||||||
Returns the time as a string. The \a format parameter determines
|
Returns a string representing the time.
|
||||||
the format of the result string.
|
|
||||||
|
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:
|
These expressions may be used:
|
||||||
|
|
||||||
@ -2198,7 +2200,7 @@ QString QTime::toString(Qt::DateFormat format) const
|
|||||||
change of case.
|
change of case.
|
||||||
\row \li t
|
\row \li t
|
||||||
\li The timezone abbreviation (for example "CEST"). Note that time zone
|
\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.
|
parse this.
|
||||||
\row \li tt
|
\row \li tt
|
||||||
\li The timezone's offset from UTC with no colon between the hours and
|
\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.
|
in use.
|
||||||
\endtable
|
\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
|
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
|
included verbatim in the output string (stripped of the quotes), even if it
|
||||||
contains formatting characters. Two consecutive single quotes ("''") are
|
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
|
\row \li H:m:s a \li 14:13:9 pm
|
||||||
\endtable
|
\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
|
\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
|
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,
|
as several expressions with no separator between them; the longest above,
|
||||||
|
@ -928,12 +928,19 @@ QString QTimeZone::comment() const
|
|||||||
The name returned is the one for the given \a locale, applicable at the
|
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
|
given \a atDateTime, and of the form indicated by \a nameType. The display
|
||||||
name may change depending on DST or historical events.
|
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
|
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
|
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.
|
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.
|
This method is only available when feature \c timezone is enabled.
|
||||||
|
//! [display-name-caveats]
|
||||||
|
|
||||||
\sa abbreviation()
|
\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.
|
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
|
Where the time zone display names have changed over time, the current names
|
||||||
will be used.
|
will be used.
|
||||||
|
\include qtimezone.cpp display-name-caveats
|
||||||
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.
|
|
||||||
|
|
||||||
\sa abbreviation()
|
\sa abbreviation()
|
||||||
*/
|
*/
|
||||||
|
Loading…
x
Reference in New Issue
Block a user