Consolidate documentation of floating-point formatting code

Move the documentation of the format and precision parameters to
QLocale::toString(double, char, int), reference it from various
QString methods (instead of repeating there and referencing one of
those from QLocale). Add brief first lines for various documentation
comments.

Mention the special handling of negative precision in the moved
documentation. Mention QLocale::FloatingPointShortest, add its type to
\sa lines of methods it affects. Change a comment on some code
implementing its special treatment to make clear that it does apply to
'e' and 'f' formats, not only to 'g', even though it has no overt
special handling in that code; and update docs to report the
undocumented behavior the comment previously described.

Document how infinity and NaN are represented. Be somewhat more
consistent about single-quoting the format names where referred to and
applying \c to character constants.

Make clear what things are different between different methods using
these parameters. Reference QString::number() from QByteArray's
relevant methods, since they share its quirks.

In the process, rename the format and precision parameters of relevant
functions so they're consistently named, replacing a mixture of
abbreviated forms.

Pick-to: 6.2
Change-Id: I077521b30346000e4b4f6968a8e750e934f72937
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>

1 files changed, 41 insertions, 74 deletions

diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp
index 32e10b9512..d97375897d 100644
--- a/src/corelib/text/qbytearray.cpp
+++ b/src/corelib/text/qbytearray.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2020 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Copyright (C) 2016 Intel Corporation.
 ** Copyright (C) 2019 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
 ** Contact: https://www.qt.io/licensing/
@@ -899,17 +899,18 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes)
     \section2 Spacing Characters
 
     A frequent requirement is to remove spacing characters from a byte array
-    ('\\n', '\\t', ' ', etc.). If you want to remove spacing from both ends of a
-    QByteArray, use trimmed(). If you want to also replace each run of spacing
-    characters with a single space character within the byte array, use
+    (\c{'\n'}, \c{'\t'}, \c{' '}, etc.). If you want to remove spacing from both
+    ends of a QByteArray, use trimmed(). If you want to also replace each run of
+    spacing characters with a single space character within the byte array, use
     simplified(). Only ASCII spacing characters are recognized for these
     purposes.
 
     \section2 Number-String Conversions
 
-    Functions that perform conversions between numeric data types and strings
-    are performed in the C locale, regardless of the user's locale settings. Use
-    QLocale to perform locale-aware conversions between numbers and strings.
+    Functions that perform conversions between numeric data types and string
+    representations are performed in the C locale, regardless of the user's
+    locale settings. Use QLocale to perform locale-aware conversions between
+    numbers and strings.
 
     \section2 Character Case
 
@@ -923,7 +924,7 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes)
     This issue does not apply to \l{QString}s since they represent characters
     using Unicode.
 
-    \sa  QByteArrayView, QString, QBitArray
+    \sa QByteArrayView, QString, QBitArray
 */
 
 /*!
@@ -3863,8 +3864,10 @@ QByteArray QByteArray::toBase64(Base64Options options) const
 /*!
     \fn QByteArray &QByteArray::setNum(int n, int base)
 
-    Sets the byte array to the printed value of \a n in base \a base (ten by
-    default) and returns a reference to the byte array. Bases 2 through 36 are
+    Represent the whole number \a n as text.
+
+    Sets this byte array to a string representing \a n in base \a base (ten by
+    default) and returns a reference to this byte array. Bases 2 through 36 are
     supported, using letters for digits beyond 9; A is ten, B is eleven and so
     on.
 
@@ -3975,56 +3978,39 @@ QByteArray &QByteArray::setNum(qulonglong n, int base)
 /*!
     \overload
 
-    Sets the byte array to the printed value of \a n, formatted in format
-    \a f with precision \a prec, and returns a reference to the
-    byte array.
-
-    The format \a f can be any of the following:
-
-    \table
-    \header \li Format \li Meaning
-    \row \li \c e \li format as [-]9.9e[+|-]999
-    \row \li \c E \li format as [-]9.9E[+|-]999
-    \row \li \c f \li format as [-]9.9
-    \row \li \c g \li use \c e or \c f format, whichever is the most concise
-    \row \li \c G \li use \c E or \c f format, whichever is the most concise
-    \endtable
+    Represent the floating-point number \a n as text.
 
-    With 'e', 'E', and 'f', \a prec is the number of digits after the
-    decimal point. With 'g' and 'G', \a prec is the maximum number of
-    significant digits (trailing zeroes are omitted).
+    Sets this byte array to a string representating \a n, with a given \a format
+    and \a precision (with the same meanings as for \l {QString::number(double,
+    char, int)}), and returns a reference to this byte array.
 
-    \note The format of the number is not localized; the default C locale is
-    used regardless of the user's locale. Use QLocale to perform locale-aware
-    conversions between numbers and strings.
-
-    \sa toDouble()
+    \sa toDouble(), QLocale::FloatingPointPrecisionOption
 */
 
-QByteArray &QByteArray::setNum(double n, char f, int prec)
+QByteArray &QByteArray::setNum(double n, char format, int precision)
 {
-    return *this = QByteArray::number(n, f, prec);
+    return *this = QByteArray::number(n, format, precision);
 }
 
 /*!
-    \fn QByteArray &QByteArray::setNum(float n, char f, int prec)
+    \fn QByteArray &QByteArray::setNum(float n, char format, int precision)
     \overload
 
-    Sets the byte array to the printed value of \a n, formatted in format
-    \a f with precision \a prec, and returns a reference to the
-    byte array.
+    Represent the floating-point number \a n as text.
 
-    \note The format of the number is not localized; the default C locale is
-    used regardless of the user's locale. Use QLocale to perform locale-aware
-    conversions between numbers and strings.
+    Sets this byte array to a string representating \a n, with a given \a format
+    and \a precision (with the same meanings as for \l {QString::number(double,
+    char, int)}), and returns a reference to this byte array.
 
     \sa toFloat()
 */
 
 /*!
-    Returns a byte array containing the printed value of the number \a n to base
-    \a base (ten by default). Bases 2 through 36 are supported, using letters
-    for digits beyond 9: A is ten, B is eleven and so on.
+    Returns a byte-array representing the whole number \a n as text.
+
+    Returns a byte array containing a string representating \a n, using the
+    specified \a base (ten by default). Bases 2 through 36 are supported, using
+    letters for digits beyond 9: A is ten, B is eleven and so on.
 
     Example:
     \snippet code/src_corelib_text_qbytearray.cpp 41
@@ -4104,45 +4090,26 @@ QByteArray QByteArray::number(qulonglong n, int base)
 
 /*!
     \overload
+    Returns a byte-array representing the floating-point number \a n as text.
 
-    Returns a byte array that contains the printed value of \a n,
-    formatted in format \a f with precision \a prec.
-
-    Argument \a n is formatted according to the \a f format specified,
-    which is \c g by default, and can be any of the following:
-
-    \table
-    \header \li Format \li Meaning
-    \row \li \c e \li format as [-]9.9e[+|-]999
-    \row \li \c E \li format as [-]9.9E[+|-]999
-    \row \li \c f \li format as [-]9.9
-    \row \li \c g \li use \c e or \c f format, whichever is the most concise
-    \row \li \c G \li use \c E or \c f format, whichever is the most concise
-    \endtable
-
-    With 'e', 'E', and 'f', \a prec is the number of digits after the
-    decimal point. With 'g' and 'G', \a prec is the maximum number of
-    significant digits (trailing zeroes are omitted).
+    Returns a byte array containing a string representing \a n, with a given \a
+    format and \a precision, with the same meanings as for \l
+    {QString::number(double, char, int)}. For example:
 
     \snippet code/src_corelib_text_qbytearray.cpp 42
 
-    \note The format of the number is not localized; the default C locale is
-    used regardless of the user's locale. Use QLocale to perform locale-aware
-    conversions between numbers and strings.
-
-    \sa toDouble()
+    \sa toDouble(), QLocale::FloatingPointPrecisionOption
 */
-QByteArray QByteArray::number(double n, char f, int prec)
+QByteArray QByteArray::number(double n, char format, int precision)
 {
     QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
     uint flags = QLocaleData::ZeroPadExponent;
 
-    char lower = asciiLower(uchar(f));
-    if (f != lower)
+    char lower = asciiLower(uchar(format));
+    if (format != lower)
         flags |= QLocaleData::CapitalEorX;
-    f = lower;
 
-    switch (f) {
+    switch (lower) {
         case 'f':
             form = QLocaleData::DFDecimal;
             break;
@@ -4154,12 +4121,12 @@ QByteArray QByteArray::number(double n, char f, int prec)
             break;
         default:
 #if defined(QT_CHECK_RANGE)
-            qWarning("QByteArray::setNum: Invalid format char '%c'", f);
+            qWarning("QByteArray::setNum: Invalid format char '%c'", format);
 #endif
             break;
     }
 
-    return QLocaleData::c()->doubleToString(n, prec, form, -1, flags).toUtf8();
+    return QLocaleData::c()->doubleToString(n, precision, form, -1, flags).toUtf8();
 }
 
 /*!