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.
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,
@ -792,6 +794,14 @@ QByteArray QTimeZone::id() const
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.
*/
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.
As a special case, a \a territory of Qt::AnyTerritory returns those time zones
that do not have any territory related to them, such as UTC. If you require
a list of all time zone IDs for all countries then use the standard
availableTimeZoneIds() method.
As a special case, a \a territory of \l {QLocale::}{AnyTerritory} selects
those time zones that have no kown territorial association, such as UTC. If
you require a list of all time zone IDs for all territories then use the
standard availableTimeZoneIds() method.
This method is only available when feature \c timezone is enabled.
\sa isTimeZoneIdAvailable()
\sa isTimeZoneIdAvailable(), 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.
Because a Windows ID can cover several IANA IDs in several different
countries, 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
best to request the default for a specific country.
territories, this function returns the most frequently used IANA ID with no
regard for the territory and should thus be used with care. It is usually
best to request the default for a specific territory.
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,
the most frequently used IANA ID in that territory is returned.
As a special case, QLocale::AnyTerritory returns the default of those IANA IDs
that do not have any specific territory.
As a special case, \l{QLocale::}{AnyTerritory} returns the default of those
IANA IDs that have no known territorial association.
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);
}
@ -1487,18 +1498,19 @@ QList<QByteArray> QTimeZone::windowsIdToIanaIds(const QByteArray &windowsId)
/*!
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
not have any specific territory.
As a special case, \l{QLocale::}{AnyTerritory} selects those IANA IDs that
have no known territorial association.
The returned list is in order of frequency of usage, i.e. larger zones
within a territory are listed first.
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);
}