From 6566157df3c5a1352231be87c7b7d2705a46efe3 Mon Sep 17 00:00:00 2001
From: Edward Welbourne <edward.welbourne@qt.io>
Date: Wed, 13 Nov 2019 18:42:00 +0100
Subject: Make Qt::RFC2822Date's doc match up with its implementation

The qdatetime implementation's rfcDateImpl() uses regexes which did
not match its comments; nor did either the regexes or the comments
match what was documented. A review of relevant RFCs suggests we
should revise this in future, probably at Qt 6.

The documentation also only addressed the formats recognized when
parsing a date-time, without indicating how they are serialised or how
dates and times are handled separately.

Added a note to the tests for the read-only formats, to remind the
reader that the RFCs merely recommend recognising these - be
permissive in what you expect and strict in what you deliver.

Change-Id: I0f0bec752e7a50bde98cceceb7e0d11be15c6a6f
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
---
 src/corelib/global/qnamespace.qdoc | 16 ++++++++++++----
 src/corelib/time/qdatetime.cpp     |  4 ++--
 2 files changed, 14 insertions(+), 6 deletions(-)

(limited to 'src')

diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index cce88782e9..bebe67be3f 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -724,9 +724,17 @@
     \value LocalDate \e{This enum value is deprecated.} Use Qt::SystemLocaleShortDate
     instead (or Qt::SystemLocaleLongDate if you want long dates).
 
-    \value RFC2822Date \l{RFC 2822}, \l{RFC 850} and \l{RFC 1036} format: either
-    \c{[ddd,] dd MMM yyyy hh:mm[:ss] +/-TZ} or \c{ddd MMM dd yyyy hh:mm[:ss] +/-TZ}
-    for combined dates and times.
+    \value RFC2822Date \l{RFC 2822}, \l{RFC 850} and \l{RFC 1036} format:
+    either \c{[ddd,] dd MMM yyyy [hh:mm[:ss]][ ±tzoff]}
+    or \c{ddd MMM dd[ hh:mm:ss] yyyy[ ±tzoff]} are recognized for combined dates
+    and times, where \c{tzoff} is a timezone offset in \c{hhmm} format. For
+    dates and times separately, the same formats are matched and the unwanted
+    parts are ignored. In particular, note that a time is not recognized without
+    an accompanying date. When converting dates to string form,
+    format \c{dd MMM yyyy} is used, for times the format is \c{hh:mm:ss}. For
+    combined date and time, these are combined
+    as \c{dd MMM yyyy hh:mm:ss ±tzoff} (omitting the optional leading day of the
+    week from the first format recognized).
 
     \note For \c ISODate formats, each \c Y, \c M and \c D represents a single digit
     of the year, month and day used to specify the date. Each \c H, \c M and \c S
diff --git a/src/corelib/time/qdatetime.cpp b/src/corelib/time/qdatetime.cpp
index 878a2c1e46..e6213c44c0 100644
--- a/src/corelib/time/qdatetime.cpp
+++ b/src/corelib/time/qdatetime.cpp
@@ -164,7 +164,7 @@ static ParsedRfcDateTime rfcDateImpl(const QString &s)
 {
     ParsedRfcDateTime result;
 
-    // Matches "Wdy, dd Mon yyyy HH:mm:ss ±hhmm" (Wdy, being optional)
+    // Matches "[ddd,] dd MMM yyyy[ hh:mm[:ss]] [±hhmm]" - correct RFC 822, 2822, 5322 format
     QRegExp rex(QStringLiteral("^(?:[A-Z][a-z]+,)?[ \\t]*(\\d{1,2})[ \\t]+([A-Z][a-z]+)[ \\t]+(\\d\\d\\d\\d)(?:[ \\t]+(\\d\\d):(\\d\\d)(?::(\\d\\d))?)?[ \\t]*(?:([+-])(\\d\\d)(\\d\\d))?"));
     if (s.indexOf(rex) == 0) {
         const QStringList cap = rex.capturedTexts();
@@ -176,7 +176,7 @@ static ParsedRfcDateTime rfcDateImpl(const QString &s)
         const int minOffset = cap[9].toInt();
         result.utcOffset = ((hourOffset * 60 + minOffset) * (positiveOffset ? 60 : -60));
     } else {
-        // Matches "Wdy Mon dd HH:mm:ss yyyy"
+        // Matches "ddd MMM dd[ hh:mm:ss] yyyy [±hhmm]" - permissive RFC 850, 1036 (read only)
         QRegExp rex(QStringLiteral("^[A-Z][a-z]+[ \\t]+([A-Z][a-z]+)[ \\t]+(\\d\\d)(?:[ \\t]+(\\d\\d):(\\d\\d):(\\d\\d))?[ \\t]+(\\d\\d\\d\\d)[ \\t]*(?:([+-])(\\d\\d)(\\d\\d))?"));
         if (s.indexOf(rex) == 0) {
             const QStringList cap = rex.capturedTexts();
-- 
cgit v1.2.3