Add advance warning of change of return types coming in Qt6

The QLocale methods that report the fragments used in making up
numbers all return QChar. A note dating from before Qt5 times warned
that we need to change these to return QString (since we might need a
surrogate pair to represent the relevant characters). Give advance
warning in the documentation that this shall happen at Qt 6.

[ChangeLog][QtCore][QLocale] decimalPoint(), groupSeparator(),
percent(), zeroDigit(), negativeSign(), positiveSign() and
exponential() still return QChar but shall be changed to return
QString in Qt 6. Callers are encouraged to switch to QString early,
exploiting the QString(QChar) constructor.

Task-number: QTBUG-81053
Change-Id: Ia802c7665676ecf13669c6a6f173f2e70eac578e
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

2 files changed, 32 insertions, 4 deletions

diff --git a/src/corelib/text/qlocale.cpp b/src/corelib/text/qlocale.cpp
index 425cb87d31..dd3263e5aa 100644
--- a/src/corelib/text/qlocale.cpp
+++ b/src/corelib/text/qlocale.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Copyright (C) 2019 Intel Corporation.
 ** Contact: https://www.qt.io/licensing/
 **
@@ -2525,6 +2525,10 @@ QDateTime QLocale::toDateTime(const QString &string, const QString &format, QCal
     \since 4.1
 
     Returns the decimal point character of this locale.
+
+    \note This function shall change to return a QString instead of QChar in
+    Qt6. Callers are encouraged to exploit the QString(QChar) constructor to
+    convert early in preparation for this.
 */
 QChar QLocale::decimalPoint() const
 {
@@ -2535,6 +2539,10 @@ QChar QLocale::decimalPoint() const
     \since 4.1
 
     Returns the group separator character of this locale.
+
+    \note This function shall change to return a QString instead of QChar in
+    Qt6. Callers are encouraged to exploit the QString(QChar) constructor to
+    convert early in preparation for this.
 */
 QChar QLocale::groupSeparator() const
 {
@@ -2545,6 +2553,10 @@ QChar QLocale::groupSeparator() const
     \since 4.1
 
     Returns the percent character of this locale.
+
+    \note This function shall change to return a QString instead of QChar in
+    Qt6. Callers are encouraged to exploit the QString(QChar) constructor to
+    convert early in preparation for this.
 */
 QChar QLocale::percent() const
 {
@@ -2555,6 +2567,10 @@ QChar QLocale::percent() const
     \since 4.1
 
     Returns the zero digit character of this locale.
+
+    \note This function shall change to return a QString instead of QChar in
+    Qt6. Callers are encouraged to exploit the QString(QChar) constructor to
+    convert early in preparation for this.
 */
 QChar QLocale::zeroDigit() const
 {
@@ -2565,6 +2581,10 @@ QChar QLocale::zeroDigit() const
     \since 4.1
 
     Returns the negative sign character of this locale.
+
+    \note This function shall change to return a QString instead of QChar in
+    Qt6. Callers are encouraged to exploit the QString(QChar) constructor to
+    convert early in preparation for this.
 */
 QChar QLocale::negativeSign() const
 {
@@ -2575,6 +2595,10 @@ QChar QLocale::negativeSign() const
     \since 4.5
 
     Returns the positive sign character of this locale.
+
+    \note This function shall change to return a QString instead of QChar in
+    Qt6. Callers are encouraged to exploit the QString(QChar) constructor to
+    convert early in preparation for this.
 */
 QChar QLocale::positiveSign() const
 {
@@ -2585,6 +2609,10 @@ QChar QLocale::positiveSign() const
     \since 4.1
 
     Returns the exponential character of this locale.
+
+    \note This function shall change to return a QString instead of QChar in
+    Qt6. Callers are encouraged to exploit the QString(QChar) constructor to
+    convert early in preparation for this.
 */
 QChar QLocale::exponential() const
 {
diff --git a/src/corelib/text/qlocale.h b/src/corelib/text/qlocale.h
index 8b73eb5493..513e0f097b 100644
--- a/src/corelib/text/qlocale.h
+++ b/src/corelib/text/qlocale.h
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtCore module of the Qt Toolkit.
@@ -1044,8 +1044,8 @@ public:
     QDateTime toDateTime(const QString &string, const QString &format, QCalendar cal) const;
 #endif
 
-    // ### Qt 5: We need to return QString from these function since
-    //           unicode data contains several characters for these fields.
+    // ### Qt 6: We need to return QString from these function since
+    //           UTF-16 may need surrogate pairs to represent these fields.
     QChar decimalPoint() const;
     QChar groupSeparator() const;
     QChar percent() const;