Prepare TextDate to use UTC-offset rather than GMT-offset zone suffixes

There are GMT-offset zones whose convention for the sign of the offset
is the reverse of what we are (still) using, which is the usual
convention for UTC-offset zone: for example, the Olson Database's
Etc/GMT+3 has offset -3 hours in the UTC-based system we use, so we
give it suffix GMT-0300. The UTC-based suffix is also what we use as
the abbreviation for OffsetFromUTC() in toString().

For now this only adds support for parsing a planned future form: the
old form using GMT is retained, to give client code some chance to
prepare for a backwards-compatible transition. Although the GMT prefix
is matched case-insensitively, only match UTC if fully upper-case;
there is no meaningful precedent for case-insensitive usage here.

[ChangeLog][QtCore][QDateTime] The Qt::TextDate format now recognizes
UTC-based offset suffixes in addition to suffixes based on the
deprecated alias GMT. This prepares for toString() to use such
UTC-based suffixes for time-zones (fromString() cannot parse the
present abbreviation suffix). A future release of Qt shall use
UTC-based suffixes in place of the present GMT-based suffixes (which
conflict with GMT-based IANA zone names) for Qt::LocalTime and
Qt::OffsetFromUTC time-specs. Client code is encouraged to use and
recognize UTC-based zone suffixes in preparation for that transition,
unless compatibility with versions before 6.2 is required.

Change-Id: I5a42a488f1232a30f4b427b7954759283423b9b3
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

1 files changed, 15 insertions, 4 deletions

diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index dd6fccd678..c100a7996c 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2020 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Copyright (C) 2020 Klaralvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
 ** Contact: https://www.qt.io/licensing/
 **
@@ -669,9 +669,15 @@
     names will be short names in English (C locale). This effectively uses, for
     a date, format \c{ddd MMM d yyyy}, for a time \c{HH:mm:ss} and combines
     these as \c{ddd MMM d HH:mm:ss yyyy} for a date-time, with an optional
-    suffix indicating time-zone or offset from UTC, where relevant. A fractional
-    part is also recognized on the seconds of a time part, as \c{HH:mm:ss.zzz},
-    when reading from a string.
+    zone-offset suffix, where relevant.  When reading from a string, a
+    fractional part is also recognized on the seconds of a time part, as
+    \c{HH:mm:ss.zzz}, and some minor variants on the format may be recognized,
+    for compatibility with earlier versions of Qt and with changes to the format
+    planned for the future. In particular, the zone-offset suffix presently uses
+    \c{GMT[±tzoff]} with a \c{tzoff} in \c{HH[[:]mm]} format (two-digit hour and
+    optional two-digit minutes, with optional colon separator); this shall
+    change to use \c{UTC} in place of \c{GMT} in a future release of Qt, so the
+    planned \c{UTC} format is recognized.
 
     \value ISODateWithMs \l{ISO 8601} extended format: uses \c{yyyy-MM-dd} for
     dates, \c{HH:mm:ss.zzz} for times or \c{yyyy-MM-ddTHH:mm:ss.zzz}
@@ -721,6 +727,11 @@
     of the format. The plus-or-minus character \c{'±'} here stands for either
     sign character, \c{'-'} for minus or \c{'+'} for plus.
 
+    \note Zone offsets are measured positive to the east of Greenwich, negative
+    to the west, as is usual for UTC-based offset notations (conflicting with
+    some GMT-based zones-names, such as \c{Etc/GMT+3}, which use the opposite
+    convention).
+
     \sa QDate::toString(), QTime::toString(), QDateTime::toString(),
         QDate::fromString(), QTime::fromString(), QDateTime::fromString()
 */