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

Improve QTimeZone's documentation about territories

Browse Source 
Clarify that a zone whose territory() is AnyTerritory may simply not
have a known association, or cover several territories.

Added more \sa links to territory(), where relevant.
Fix some surviving uses of country for territory.
Split some long lines.

Pick-to: 6.5 6.2
Change-Id: I9196f785afed9bc185a459608c5d9361127401cb
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
This commit is contained in:
Edward Welbourne 2023-03-24 13:22:10 +01:00
parent 970841235b
commit 455abef6c6
1 changed files with 28 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -501,6 +501,8 @@ QTimeZone::QTimeZone(int offsetSeconds)
default value of QLocale::AnyTerritory. default value of QLocale::AnyTerritory.
This constructor is only available when feature \c timezone is enabled. This constructor is only available when feature \c timezone is enabled.
\sa id(), offsetFromUtc(), displayName(), abbreviation(), territory(), comment()
*/ */
QTimeZone::QTimeZone(const QByteArray &ianaId, int offsetSeconds, const QString &name, QTimeZone::QTimeZone(const QByteArray &ianaId, int offsetSeconds, const QString &name,
@ -792,6 +794,14 @@ QByteArray QTimeZone::id() const
Returns the territory for the time zone. Returns the territory for the time zone.
A return of \l {QLocale::}{AnyTerritory} means the zone has no known
territorial association. In some cases this may be because the zone has no
associated territory - for example, UTC - or because the zone is used in
several territories - for example, CET. In other cases, the QTimeZone
backend may not know which territory the zone is associated with - for
example, because it is not the primary zone of the territory in which it is
used.
This method is only available when feature \c timezone is enabled. This method is only available when feature \c timezone is enabled.
*/ */
QLocale::Territory QTimeZone::territory() const QLocale::Territory QTimeZone::territory() const
@ -1388,14 +1398,14 @@ QList<QByteArray> QTimeZone::availableTimeZoneIds()
/*! /*!
Returns a list of all available IANA time zone IDs for a given \a territory. Returns a list of all available IANA time zone IDs for a given \a territory.
As a special case, a \a territory of Qt::AnyTerritory returns those time zones As a special case, a \a territory of \l {QLocale::}{AnyTerritory} selects
that do not have any territory related to them, such as UTC. If you require those time zones that have no kown territorial association, such as UTC. If
a list of all time zone IDs for all countries then use the standard you require a list of all time zone IDs for all territories then use the
availableTimeZoneIds() method. standard availableTimeZoneIds() method.
This method is only available when feature \c timezone is enabled. This method is only available when feature \c timezone is enabled.
\sa isTimeZoneIdAvailable() \sa isTimeZoneIdAvailable(), territory()
*/ */
QList<QByteArray> QTimeZone::availableTimeZoneIds(QLocale::Territory territory) QList<QByteArray> QTimeZone::availableTimeZoneIds(QLocale::Territory territory)
@ -1436,9 +1446,9 @@ QByteArray QTimeZone::ianaIdToWindowsId(const QByteArray &ianaId)
Returns the default IANA ID for a given \a windowsId. Returns the default IANA ID for a given \a windowsId.
Because a Windows ID can cover several IANA IDs in several different Because a Windows ID can cover several IANA IDs in several different
countries, this function returns the most frequently used IANA ID with no territories, this function returns the most frequently used IANA ID with no
regard for the country and should thus be used with care. It is usually regard for the territory and should thus be used with care. It is usually
best to request the default for a specific country. best to request the default for a specific territory.
This method is only available when feature \c timezone is enabled. This method is only available when feature \c timezone is enabled.
@ -1456,15 +1466,16 @@ QByteArray QTimeZone::windowsIdToDefaultIanaId(const QByteArray &windowsId)
Because a Windows ID can cover several IANA IDs within a given territory, Because a Windows ID can cover several IANA IDs within a given territory,
the most frequently used IANA ID in that territory is returned. the most frequently used IANA ID in that territory is returned.
As a special case, QLocale::AnyTerritory returns the default of those IANA IDs As a special case, \l{QLocale::}{AnyTerritory} returns the default of those
that do not have any specific territory. IANA IDs that have no known territorial association.
This method is only available when feature \c timezone is enabled. This method is only available when feature \c timezone is enabled.
\sa ianaIdToWindowsId(), windowsIdToIanaIds() \sa ianaIdToWindowsId(), windowsIdToIanaIds(), territory()
*/ */
QByteArray QTimeZone::windowsIdToDefaultIanaId(const QByteArray &windowsId, QLocale::Territory territory) QByteArray QTimeZone::windowsIdToDefaultIanaId(const QByteArray &windowsId,
QLocale::Territory territory)
{ {
return QTimeZonePrivate::windowsIdToDefaultIanaId(windowsId, territory); return QTimeZonePrivate::windowsIdToDefaultIanaId(windowsId, territory);
} }
@ -1487,18 +1498,19 @@ QList<QByteArray> QTimeZone::windowsIdToIanaIds(const QByteArray &windowsId)
/*! /*!
Returns all the IANA IDs for a given \a windowsId and \a territory. Returns all the IANA IDs for a given \a windowsId and \a territory.
As a special case QLocale::AnyTerritory returns those IANA IDs that do As a special case, \l{QLocale::}{AnyTerritory} selects those IANA IDs that
not have any specific territory. have no known territorial association.
The returned list is in order of frequency of usage, i.e. larger zones The returned list is in order of frequency of usage, i.e. larger zones
within a territory are listed first. within a territory are listed first.
This method is only available when feature \c timezone is enabled. This method is only available when feature \c timezone is enabled.
\sa ianaIdToWindowsId(), windowsIdToDefaultIanaId() \sa ianaIdToWindowsId(), windowsIdToDefaultIanaId(), territory()
*/ */
QList<QByteArray> QTimeZone::windowsIdToIanaIds(const QByteArray &windowsId, QLocale::Territory territory) QList<QByteArray> QTimeZone::windowsIdToIanaIds(const QByteArray &windowsId,
QLocale::Territory territory)
{ {
return QTimeZonePrivate::windowsIdToIanaIds(windowsId, territory); return QTimeZonePrivate::windowsIdToIanaIds(windowsId, territory);
} }