1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Consolidate documentation of floating-point formatting code

Browse Source 
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>
This commit is contained in:
Edward Welbourne 2021-07-27 17:51:57 +02:00
parent 11476e5403
commit b61a6e2507
7 changed files with 170 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
src/corelib/text/qbytearray.cpp
View File

@ -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) 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> ** 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/ ** Contact: https://www.qt.io/licensing/
@ -899,17 +899,18 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes)
\section2 Spacing Characters \section2 Spacing Characters
A frequent requirement is to remove spacing characters from a byte array 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 (\c{'\n'}, \c{'\t'}, \c{' '}, etc.). If you want to remove spacing from both
QByteArray, use trimmed(). If you want to also replace each run of spacing ends of a QByteArray, use trimmed(). If you want to also replace each run of
characters with a single space character within the byte array, use spacing characters with a single space character within the byte array, use
simplified(). Only ASCII spacing characters are recognized for these simplified(). Only ASCII spacing characters are recognized for these
purposes. purposes.
\section2 Number-String Conversions \section2 Number-String Conversions
Functions that perform conversions between numeric data types and strings Functions that perform conversions between numeric data types and string
are performed in the C locale, regardless of the user's locale settings. Use representations are performed in the C locale, regardless of the user's
QLocale to perform locale-aware conversions between numbers and strings. locale settings. Use QLocale to perform locale-aware conversions between
numbers and strings.
\section2 Character Case \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 This issue does not apply to \l{QString}s since they represent characters
using Unicode. 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) \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 Represent the whole number \a n as text.
default) and returns a reference to the byte array. Bases 2 through 36 are
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 supported, using letters for digits beyond 9; A is ten, B is eleven and so
on. on.
@ -3975,56 +3978,39 @@ QByteArray &QByteArray::setNum(qulonglong n, int base)
/*! /*!
\overload \overload
Sets the byte array to the printed value of \a n, formatted in format Represent the floating-point number \a n as text.
\a f with precision \a prec, and returns a reference to the
byte array.
The format \a f can be any of the following: 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.
\table \sa toDouble(), QLocale::FloatingPointPrecisionOption
\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).
\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()
*/ */
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 \overload
Sets the byte array to the printed value of \a n, formatted in format Represent the floating-point number \a n as text.
\a f with precision \a prec, and returns a reference to the
byte array.
\note The format of the number is not localized; the default C locale is Sets this byte array to a string representating \a n, with a given \a format
used regardless of the user's locale. Use QLocale to perform locale-aware and \a precision (with the same meanings as for \l {QString::number(double,
conversions between numbers and strings. char, int)}), and returns a reference to this byte array.
\sa toFloat() \sa toFloat()
*/ */
/*! /*!
Returns a byte array containing the printed value of the number \a n to base Returns a byte-array representing the whole number \a n as text.
\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 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: Example:
\snippet code/src_corelib_text_qbytearray.cpp 41 \snippet code/src_corelib_text_qbytearray.cpp 41
@ -4104,45 +4090,26 @@ QByteArray QByteArray::number(qulonglong n, int base)
/*! /*!
\overload \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, Returns a byte array containing a string representing \a n, with a given \a
formatted in format \a f with precision \a prec. format and \a precision, with the same meanings as for \l
{QString::number(double, char, int)}. For example:
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).
\snippet code/src_corelib_text_qbytearray.cpp 42 \snippet code/src_corelib_text_qbytearray.cpp 42
\note The format of the number is not localized; the default C locale is \sa toDouble(), QLocale::FloatingPointPrecisionOption
used regardless of the user's locale. Use QLocale to perform locale-aware
conversions between numbers and strings.
\sa toDouble()
*/ */
QByteArray QByteArray::number(double n, char f, int prec) QByteArray QByteArray::number(double n, char format, int precision)
{ {
QLocaleData::DoubleForm form = QLocaleData::DFDecimal; QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
uint flags = QLocaleData::ZeroPadExponent; uint flags = QLocaleData::ZeroPadExponent;
char lower = asciiLower(uchar(f)); char lower = asciiLower(uchar(format));
if (f != lower) if (format != lower)
flags |= QLocaleData::CapitalEorX; flags |= QLocaleData::CapitalEorX;
f = lower;
switch (f) { switch (lower) {
case 'f': case 'f':
form = QLocaleData::DFDecimal; form = QLocaleData::DFDecimal;
break; break;
@ -4154,12 +4121,12 @@ QByteArray QByteArray::number(double n, char f, int prec)
break; break;
default: default:
#if defined(QT_CHECK_RANGE) #if defined(QT_CHECK_RANGE)
qWarning("QByteArray::setNum: Invalid format char '%c'", f); qWarning("QByteArray::setNum: Invalid format char '%c'", format);
#endif #endif
break; break;
} }
return QLocaleData::c()->doubleToString(n, prec, form, -1, flags).toUtf8(); return QLocaleData::c()->doubleToString(n, precision, form, -1, flags).toUtf8();
} }
/*! /*!

10
src/corelib/text/qbytearray.h
View File

@ -375,8 +375,8 @@ public:
inline QByteArray &setNum(ulong, int base = 10); inline QByteArray &setNum(ulong, int base = 10);
QByteArray &setNum(qlonglong, int base = 10); QByteArray &setNum(qlonglong, int base = 10);
QByteArray &setNum(qulonglong, int base = 10); QByteArray &setNum(qulonglong, int base = 10);
inline QByteArray &setNum(float, char f = 'g', int prec = 6); inline QByteArray &setNum(float, char format = 'g', int precision = 6);
QByteArray &setNum(double, char f = 'g', int prec = 6); QByteArray &setNum(double, char format = 'g', int precision = 6);
QByteArray &setRawData(const char *a, qsizetype n); QByteArray &setRawData(const char *a, qsizetype n);
[[nodiscard]] static QByteArray number(int, int base = 10); [[nodiscard]] static QByteArray number(int, int base = 10);
@ -385,7 +385,7 @@ public:
[[nodiscard]] static QByteArray number(ulong, int base = 10); [[nodiscard]] static QByteArray number(ulong, int base = 10);
[[nodiscard]] static QByteArray number(qlonglong, int base = 10); [[nodiscard]] static QByteArray number(qlonglong, int base = 10);
[[nodiscard]] static QByteArray number(qulonglong, int base = 10); [[nodiscard]] static QByteArray number(qulonglong, int base = 10);
[[nodiscard]] static QByteArray number(double, char f = 'g', int prec = 6); [[nodiscard]] static QByteArray number(double, char format = 'g', int precision = 6);
[[nodiscard]] static QByteArray fromRawData(const char *data, qsizetype size) [[nodiscard]] static QByteArray fromRawData(const char *data, qsizetype size)
{ {
return QByteArray(DataPointer(nullptr, const_cast<char *>(data), size)); return QByteArray(DataPointer(nullptr, const_cast<char *>(data), size));
@ -609,8 +609,8 @@ inline QByteArray &QByteArray::setNum(long n, int base)
{ return setNum(qlonglong(n), base); } { return setNum(qlonglong(n), base); }
inline QByteArray &QByteArray::setNum(ulong n, int base) inline QByteArray &QByteArray::setNum(ulong n, int base)
{ return setNum(qulonglong(n), base); } { return setNum(qulonglong(n), base); }
inline QByteArray &QByteArray::setNum(float n, char f, int prec) inline QByteArray &QByteArray::setNum(float n, char format, int precision)
{ return setNum(double(n),f,prec); } { return setNum(double(n), format, precision); }
inline std::string QByteArray::toStdString() const inline std::string QByteArray::toStdString() const
{ return std::string(constData(), length()); } { return std::string(constData(), length()); }

55
src/corelib/text/qlocale.cpp
View File

@ -1072,7 +1072,7 @@ size_t qHash(const QLocale &key, size_t seed) noexcept
Sets the \a options related to number conversions for this Sets the \a options related to number conversions for this
QLocale instance. QLocale instance.
\sa numberOptions() \sa numberOptions(), FloatingPointPrecisionOption
*/ */
void QLocale::setNumberOptions(NumberOptions options) void QLocale::setNumberOptions(NumberOptions options)
{ {
@ -1088,7 +1088,7 @@ void QLocale::setNumberOptions(NumberOptions options)
By default, no options are set for the standard locales, except By default, no options are set for the standard locales, except
for the "C" locale, which has OmitGroupSeparator set by default. for the "C" locale, which has OmitGroupSeparator set by default.
\sa setNumberOptions(), toString(), groupSeparator() \sa setNumberOptions(), toString(), groupSeparator(), FloatingPointPrecisionOption
*/ */
QLocale::NumberOptions QLocale::numberOptions() const QLocale::NumberOptions QLocale::numberOptions() const
{ {
@ -2528,18 +2528,46 @@ static char qToLower(char c)
/*! /*!
\overload \overload
Returns a string representing the floating-point number \a f.
\a f and \a prec have the same meaning as in QString::number(double, char, int). The form of the representation is controlled by the \a format and \a
precision parameters.
\sa toDouble(), numberOptions(), exponential(), decimalPoint(), zeroDigit(), positiveSign(), percent() The \a format defaults to \c{'g'}. It 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 more concise
\row \li \c 'G' \li use \c 'E' or \c 'f' format, whichever is more concise
\endtable
For the \c 'e', \c 'E', and \c 'f' formats, the \a precision represents the
number of digits \e after the decimal point. For the \c 'g' and \c 'G'
formats, the \a precision represents the maximum number of significant
digits (trailing zeroes are omitted). The special \a precision value
QLocale::FloatingPointShortest selects the shortest representation that,
when read as a number, gets back the original floating-point value. Aside
from that, any negative \a precision is ignored in favor of the default, 6.
For the \c 'e', \c 'f' and \c 'g' formats, positive infinity is represented
as "inf", negative infinity as "-inf" and floating-point NaN (not-a-number)
values are represented as "nan". For the \c 'E' and \c 'G' formats, "INF"
and "NAN" are used instead. This does not vary with locale.
\sa toDouble(), numberOptions(), exponential(), decimalPoint(), zeroDigit(),
positiveSign(), percent(), toCurrencyString(), formattedDataSize(),
QLocale::FloatingPointPrecisionOption
*/ */
QString QLocale::toString(double i, char f, int prec) const QString QLocale::toString(double f, char format, int precision) const
{ {
QLocaleData::DoubleForm form = QLocaleData::DFDecimal; QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
uint flags = qIsUpper(f) ? QLocaleData::CapitalEorX : 0; uint flags = qIsUpper(format) ? QLocaleData::CapitalEorX : 0;
switch (qToLower(f)) { switch (qToLower(format)) {
case 'f': case 'f':
form = QLocaleData::DFDecimal; form = QLocaleData::DFDecimal;
break; break;
@ -2559,7 +2587,7 @@ QString QLocale::toString(double i, char f, int prec) const
flags |= QLocaleData::ZeroPadExponent; flags |= QLocaleData::ZeroPadExponent;
if (d->m_numberOptions & IncludeTrailingZeroesAfterDot) if (d->m_numberOptions & IncludeTrailingZeroesAfterDot)
flags |= QLocaleData::AddTrailingZeroes; flags |= QLocaleData::AddTrailingZeroes;
return d->m_data->doubleToString(i, prec, form, -1, flags); return d->m_data->doubleToString(f, precision, form, -1, flags);
} }
/*! /*!
@ -3374,8 +3402,11 @@ QString QCalendarBackend::dateTimeToString(QStringView format, const QDateTime &
QString QLocaleData::doubleToString(double d, int precision, DoubleForm form, QString QLocaleData::doubleToString(double d, int precision, DoubleForm form,
int width, unsigned flags) const int width, unsigned flags) const
{ {
// Undocumented: aside from F.P.Shortest, precision < 0 is treated as // Although the special handling of F.P.Shortest below is limited to
// default, 6 - same as printf(). // DFSignificantDigits, the double-conversion library does treat it
// specially for the other forms, shedding trailing zeros for DFDecimal and
// using the shortest mantissa that faithfully represents the value for
// DFExponent.
if (precision != QLocale::FloatingPointShortest && precision < 0) if (precision != QLocale::FloatingPointShortest && precision < 0)
precision = 6; precision = 6;
if (width < 0) if (width < 0)
@ -3387,8 +3418,8 @@ QString QLocaleData::doubleToString(double d, int precision, DoubleForm form,
bufSize += std::numeric_limits<double>::max_digits10; bufSize += std::numeric_limits<double>::max_digits10;
else if (form == DFDecimal && qIsFinite(d)) else if (form == DFDecimal && qIsFinite(d))
bufSize += wholePartSpace(qAbs(d)) + precision; bufSize += wholePartSpace(qAbs(d)) + precision;
else // Add extra digit due to different interpretations of precision. Also, "nan" has to fit. else // Add extra digit due to different interpretations of precision.
bufSize += qMax(2, precision) + 1; bufSize += qMax(2, precision) + 1; // Must also be big enough for "nan" or "inf"
QVarLengthArray<char> buf(bufSize); QVarLengthArray<char> buf(bufSize);
int length; int length;

6
src/corelib/text/qlocale.h
View File

@ -994,9 +994,9 @@ public:
QString toString(ushort i) const { return toString(qulonglong(i)); } QString toString(ushort i) const { return toString(qulonglong(i)); }
QString toString(int i) const { return toString(qlonglong(i)); } QString toString(int i) const { return toString(qlonglong(i)); }
QString toString(uint i) const { return toString(qulonglong(i)); } QString toString(uint i) const { return toString(qulonglong(i)); }
QString toString(double i, char f = 'g', int prec = 6) const; QString toString(double f, char format = 'g', int precision = 6) const;
QString toString(float i, char f = 'g', int prec = 6) const QString toString(float f, char format = 'g', int precision = 6) const
{ return toString(double(i), f, prec); } { return toString(double(f), format, precision); }
#if QT_STRINGVIEW_LEVEL < 2 #if QT_STRINGVIEW_LEVEL < 2
// (Can't inline first two: passing by value doesn't work when only forward-declared.) // (Can't inline first two: passing by value doesn't work when only forward-declared.)

26
src/corelib/text/qlocale.qdoc
View File

@ -995,23 +995,23 @@
dot when parsing a number in scientific or decimal representation. The dot when parsing a number in scientific or decimal representation. The
default is to accept trailing zeroes. default is to accept trailing zeroes.
\sa setNumberOptions(), numberOptions() \sa setNumberOptions(), numberOptions(), FloatingPointPrecisionOption
*/ */
/*! /*!
\enum QLocale::FloatingPointPrecisionOption \enum QLocale::FloatingPointPrecisionOption
This enum defines constants that can be given as precision to QString::number(), This enum defines a constant that can be given as precision to QString::number(),
QByteArray::number(), and QLocale::toString() when converting floats or doubles, QByteArray::number(), and QLocale::toString() when converting floats or doubles,
in order to express a variable number of digits as precision. in order to express a variable number of digits as precision.
\value FloatingPointShortest The conversion algorithm will try to find the \value FloatingPointShortest The conversion algorithm will try to find the
shortest accurate representation for the given number. "Accurate" means shortest accurate representation for the given number. "Accurate" means
that you get the exact same number back from an inverse conversion on that you get the exact same number back from an inverse conversion on
the generated string representation. the generated string representation. In particular, trailing zeros are
omitted (from the mantissa, in exponent formats).
\sa toString(), QString, QByteArray
\sa toString(), QString::number(), QByteArray::number()
\since 5.7 \since 5.7
*/ */
@ -1256,13 +1256,17 @@
*/ */
/*! /*!
\fn QString QLocale::toString(float i, char f = 'g', int prec = 6) const \fn QString QLocale::toString(float f, char format = 'g', int precision = 6) const
\overload \overload
\a f and \a prec have the same meaning as in QString::number(double, char, int). Returns a string representing the floating-point number \a f.
\sa toDouble() The \a format and \a precision have the same meanings as described in \l
{toString(double, char, int)}.
\sa toFloat(), toDouble(), numberOptions(), exponential(), decimalPoint(), zeroDigit(),
positiveSign(), percent(), toCurrencyString(), formattedDataSize(),
QLocale::FloatingPointPrecisionOption
*/ */
/*! /*!

146
src/corelib/text/qstring.cpp
View File

@ -1846,26 +1846,33 @@ inline char qToLower(char ch)
(\e not nullptr) to a '\\0' character for a null string. We (\e not nullptr) to a '\\0' character for a null string. We
recommend that you always use the isEmpty() function and avoid isNull(). recommend that you always use the isEmpty() function and avoid isNull().
\section1 Argument Formats \section1 Number Formats
In member functions where an argument \e format can be specified When a QString::arg() \c{'%'} format specifier includes the \c{'L'} locale
(e.g., arg(), number()), the argument \e format can be one of the qualifier, and the base is ten (its default), the default locale is
following: used. This can be set using \l{QLocale::setDefault()}. For more refined
control of localized string representations of numbers, see
QLocale::toString(). All other number formatting done by QString follows the
C locale's representation of numbers.
\table When QString::arg() applies left-padding to numbers, the fill character
\header \li Format \li Meaning \c{'0'} is treated specially. If the number is negative, its minus sign will
\row \li \c e \li format as [-]9.9e[+|-]999 appear before the zero-padding. If the field is localized, the
\row \li \c E \li format as [-]9.9E[+|-]999 locale-appropriate zero character is used in place of \c{'0'}. For
\row \li \c f \li format as [-]9.9 floating-point numbers, this special treatment only applies if the number is
\row \li \c g \li use \c e or \c f format, whichever is the most concise finite.
\row \li \c G \li use \c E or \c f format, whichever is the most concise
\endtable
A \e precision is also specified with the argument \e format. For \section2 Floating-point Formats
the 'e', 'E', and 'f' formats, the \e precision represents the
number of digits \e after the decimal point. For the 'g' and 'G' In member functions (e.g., arg(), number()) that represent floating-point
formats, the \e precision represents the maximum number of numbers (\c float or \c double) as strings, the form of display can be
significant digits (trailing zeroes are omitted). controlled by a choice of \e format and \e precision, whose meanings are as
for \l {QLocale::toString(double, char, int)}.
If the selected \e format includes an exponent, localized forms follow the
locale's convention on digits in the exponent. For non-localized formatting,
the exponent shows its sign and includes at least two digits, left-padding
with zero if needed.
\section1 More Efficient String Construction \section1 More Efficient String Construction
@ -7226,26 +7233,17 @@ QString &QString::setNum(qulonglong n, int base)
*/ */
/*! /*!
\fn QString &QString::setNum(double n, char format, int precision)
\overload \overload
Sets the string to the printed value of \a n, formatted according Sets the string to the printed value of \a n, formatted according to the
to the given \a format and \a precision, and returns a reference given \a format and \a precision, and returns a reference to the string.
to the string.
The \a format can be 'e', 'E', 'f', 'g' or 'G' (see \sa number(), QLocale::FloatingPointPrecisionOption, {Number Formats}
\l{Argument Formats} for an explanation of the formats).
The formatting always uses QLocale::C, i.e., English/UnitedStates.
To get a localized string representation of a number, use
QLocale::toString() with the appropriate locale.
\sa number()
*/ */
QString &QString::setNum(double n, char f, int prec) QString &QString::setNum(double n, char format, int precision)
{ {
return *this = number(n, f, prec); return *this = number(n, format, precision);
} }
/*! /*!
@ -7353,26 +7351,25 @@ QString QString::number(qulonglong n, int base)
/*! /*!
\fn QString QString::number(double n, char format, int precision) Returns a string representing the floating-point number \a n.
Returns a string equivalent of the number \a n, formatted Returns a string that represents \a n, formatted according to the specified
according to the specified \a format and \a precision. See \a format and \a precision.
\l{Argument Formats} for details.
Unlike QLocale::toString(), this function does not honor the For formats with an exponent, the exponent will show its sign and have at
user's locale settings. least two digits, left-padding the exponent with zero if needed.
\sa setNum(), QLocale::toString() \sa setNum(), QLocale::toString(), QLocale::FloatingPointPrecisionOption, {Number Formats}
*/ */
QString QString::number(double n, char f, int prec) QString QString::number(double n, char format, int precision)
{ {
QLocaleData::DoubleForm form = QLocaleData::DFDecimal; QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
uint flags = QLocaleData::ZeroPadExponent; uint flags = QLocaleData::ZeroPadExponent;
if (qIsUpper(f)) if (qIsUpper(format))
flags |= QLocaleData::CapitalEorX; flags |= QLocaleData::CapitalEorX;
switch (qToLower(f)) { switch (qToLower(format)) {
case 'f': case 'f':
form = QLocaleData::DFDecimal; form = QLocaleData::DFDecimal;
break; break;
@ -7384,12 +7381,12 @@ QString QString::number(double n, char f, int prec)
break; break;
default: default:
#if defined(QT_CHECK_RANGE) #if defined(QT_CHECK_RANGE)
qWarning("QString::setNum: Invalid format char '%c'", f); qWarning("QString::setNum: Invalid format char '%c'", format);
#endif #endif
break; break;
} }
return QLocaleData::c()->doubleToString(n, prec, form, -1, flags); return QLocaleData::c()->doubleToString(n, precision, form, -1, flags);
} }
namespace { namespace {
@ -7986,15 +7983,13 @@ QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
The '%' can be followed by an 'L', in which case the sequence is The '%' can be followed by an 'L', in which case the sequence is
replaced with a localized representation of \a a. The conversion replaced with a localized representation of \a a. The conversion
uses the default locale, set by QLocale::setDefault(). If no default uses the default locale, set by QLocale::setDefault(). If no default
locale was specified, the "C" locale is used. The 'L' flag is locale was specified, the system locale is used. The 'L' flag is
ignored if \a base is not 10. ignored if \a base is not 10.
\snippet qstring/main.cpp 12 \snippet qstring/main.cpp 12
\snippet qstring/main.cpp 14 \snippet qstring/main.cpp 14
If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is \sa {Number Formats}
used. For negative numbers, zero padding might appear before the
minus sign.
*/ */
/*! \fn QString QString::arg(uint a, int fieldWidth, int base, QChar fillChar) const /*! \fn QString QString::arg(uint a, int fieldWidth, int base, QChar fillChar) const
@ -8003,9 +7998,7 @@ QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
The \a base argument specifies the base to use when converting the The \a base argument specifies the base to use when converting the
integer \a a into a string. The base must be between 2 and 36. integer \a a into a string. The base must be between 2 and 36.
If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is \sa {Number Formats}
used. For negative numbers, zero padding might appear before the
minus sign.
*/ */
/*! \fn QString QString::arg(long a, int fieldWidth, int base, QChar fillChar) const /*! \fn QString QString::arg(long a, int fieldWidth, int base, QChar fillChar) const
@ -8029,12 +8022,11 @@ QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
\snippet qstring/main.cpp 12 \snippet qstring/main.cpp 12
\snippet qstring/main.cpp 14 \snippet qstring/main.cpp 14
If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is \sa {Number Formats}
used. For negative numbers, zero padding might appear before the
minus sign.
*/ */
/*! \fn QString QString::arg(ulong a, int fieldWidth, int base, QChar fillChar) const /*!
\fn QString QString::arg(ulong a, int fieldWidth, int base, QChar fillChar) const
\overload arg() \overload arg()
\a fieldWidth specifies the minimum amount of space that \a a is \a fieldWidth specifies the minimum amount of space that \a a is
@ -8046,9 +8038,7 @@ QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
integer \a a to a string. The base must be between 2 and 36, with 8 integer \a a to a string. The base must be between 2 and 36, with 8
giving octal, 10 decimal, and 16 hexadecimal numbers. giving octal, 10 decimal, and 16 hexadecimal numbers.
If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is \sa {Number Formats}
used. For negative numbers, zero padding might appear before the
minus sign.
*/ */
/*! /*!
@ -8063,9 +8053,7 @@ QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
integer \a a into a string. The base must be between 2 and 36, with integer \a a into a string. The base must be between 2 and 36, with
8 giving octal, 10 decimal, and 16 hexadecimal numbers. 8 giving octal, 10 decimal, and 16 hexadecimal numbers.
If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is \sa {Number Formats}
used. For negative numbers, zero padding might appear before the
minus sign.
*/ */
QString QString::arg(qlonglong a, int fieldWidth, int base, QChar fillChar) const QString QString::arg(qlonglong a, int fieldWidth, int base, QChar fillChar) const
{ {
@ -8107,9 +8095,7 @@ QString QString::arg(qlonglong a, int fieldWidth, int base, QChar fillChar) cons
integer \a a into a string. \a base must be between 2 and 36, with 8 integer \a a into a string. \a base must be between 2 and 36, with 8
giving octal, 10 decimal, and 16 hexadecimal numbers. giving octal, 10 decimal, and 16 hexadecimal numbers.
If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is \sa {Number Formats}
used. For negative numbers, zero padding might appear before the
minus sign.
*/ */
QString QString::arg(qulonglong a, int fieldWidth, int base, QChar fillChar) const QString QString::arg(qulonglong a, int fieldWidth, int base, QChar fillChar) const
{ {
@ -8153,9 +8139,7 @@ QString QString::arg(qulonglong a, int fieldWidth, int base, QChar fillChar) con
integer \a a into a string. The base must be between 2 and 36, with integer \a a into a string. The base must be between 2 and 36, with
8 giving octal, 10 decimal, and 16 hexadecimal numbers. 8 giving octal, 10 decimal, and 16 hexadecimal numbers.
If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is \sa {Number Formats}
used. For negative numbers, zero padding might appear before the
minus sign.
*/ */
/*! /*!
@ -8171,9 +8155,7 @@ QString QString::arg(qulonglong a, int fieldWidth, int base, QChar fillChar) con
integer \a a into a string. The base must be between 2 and 36, with integer \a a into a string. The base must be between 2 and 36, with
8 giving octal, 10 decimal, and 16 hexadecimal numbers. 8 giving octal, 10 decimal, and 16 hexadecimal numbers.
If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is \sa {Number Formats}
used. For negative numbers, zero padding might appear before the
minus sign.
*/ */
/*! /*!
@ -8195,11 +8177,10 @@ QString QString::arg(char a, int fieldWidth, QChar fillChar) const
} }
/*! /*!
\fn QString QString::arg(double a, int fieldWidth, char format, int precision, QChar fillChar) const
\overload arg() \overload arg()
Argument \a a is formatted according to the specified \a format and Argument \a a is formatted according to the specified \a format and
\a precision. See \l{Argument Formats} for details. \a precision. See \l{Floating-point Formats} for details.
\a fieldWidth specifies the minimum amount of space that \a a is \a fieldWidth specifies the minimum amount of space that \a a is
padded to and filled with the character \a fillChar. A positive padded to and filled with the character \a fillChar. A positive
@ -8208,18 +8189,9 @@ QString QString::arg(char a, int fieldWidth, QChar fillChar) const
\snippet code/src_corelib_text_qstring.cpp 2 \snippet code/src_corelib_text_qstring.cpp 2
The '%' can be followed by an 'L', in which case the sequence is \sa QLocale::toString(), QLocale::FloatingPointPrecisionOption, {Number Formats}
replaced with a localized representation of \a a. The conversion
uses the default locale, set by QLocale::setDefault(). If no
default locale was specified, the "C" locale is used.
If \a fillChar is '0' (the number 0, ASCII 48), this function will
use the locale's zero to pad. For negative numbers, the zero padding
will probably appear before the minus sign.
\sa QLocale::toString()
*/ */
QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillChar) const QString QString::arg(double a, int fieldWidth, char format, int precision, QChar fillChar) const
{ {
ArgEscapeData d = findArgEscapes(*this); ArgEscapeData d = findArgEscapes(*this);
@ -8232,11 +8204,11 @@ QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillCha
if (fillChar == QLatin1Char('0')) if (fillChar == QLatin1Char('0'))
flags |= QLocaleData::ZeroPadded; flags |= QLocaleData::ZeroPadded;
if (qIsUpper(fmt)) if (qIsUpper(format))
flags |= QLocaleData::CapitalEorX; flags |= QLocaleData::CapitalEorX;
QLocaleData::DoubleForm form = QLocaleData::DFDecimal; QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
switch (qToLower(fmt)) { switch (qToLower(format)) {
case 'f': case 'f':
form = QLocaleData::DFDecimal; form = QLocaleData::DFDecimal;
break; break;
@ -8248,14 +8220,14 @@ QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillCha
break; break;
default: default:
#if defined(QT_CHECK_RANGE) #if defined(QT_CHECK_RANGE)
qWarning("QString::arg: Invalid format char '%c'", fmt); qWarning("QString::arg: Invalid format char '%c'", format);
#endif #endif
break; break;
} }
QString arg; QString arg;
if (d.occurrences > d.locale_occurrences) if (d.occurrences > d.locale_occurrences)
arg = QLocaleData::c()->doubleToString(a, prec, form, fieldWidth, flags | QLocaleData::ZeroPadExponent); arg = QLocaleData::c()->doubleToString(a, precision, form, fieldWidth, flags | QLocaleData::ZeroPadExponent);
QString locale_arg; QString locale_arg;
if (d.locale_occurrences > 0) { if (d.locale_occurrences > 0) {
@ -8268,7 +8240,7 @@ QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillCha
flags |= QLocaleData::ZeroPadExponent; flags |= QLocaleData::ZeroPadExponent;
if (numberOptions & QLocale::IncludeTrailingZeroesAfterDot) if (numberOptions & QLocale::IncludeTrailingZeroesAfterDot)
flags |= QLocaleData::AddTrailingZeroes; flags |= QLocaleData::AddTrailingZeroes;
locale_arg = locale.d->m_data->doubleToString(a, prec, form, fieldWidth, flags); locale_arg = locale.d->m_data->doubleToString(a, precision, form, fieldWidth, flags);
} }
return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar); return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);

8
src/corelib/text/qstring.h
View File

@ -464,7 +464,7 @@ public:
QChar fillChar = QLatin1Char(' ')) const; QChar fillChar = QLatin1Char(' ')) const;
[[nodiscard]] QString arg(ushort a, int fieldWidth = 0, int base = 10, [[nodiscard]] QString arg(ushort a, int fieldWidth = 0, int base = 10,
QChar fillChar = QLatin1Char(' ')) const; QChar fillChar = QLatin1Char(' ')) const;
[[nodiscard]] QString arg(double a, int fieldWidth = 0, char fmt = 'g', int prec = -1, [[nodiscard]] QString arg(double a, int fieldWidth = 0, char format = 'g', int precision = -1,
QChar fillChar = QLatin1Char(' ')) const; QChar fillChar = QLatin1Char(' ')) const;
[[nodiscard]] QString arg(char a, int fieldWidth = 0, [[nodiscard]] QString arg(char a, int fieldWidth = 0,
QChar fillChar = QLatin1Char(' ')) const; QChar fillChar = QLatin1Char(' ')) const;
@ -854,8 +854,8 @@ public:
QString &setNum(ulong, int base=10); QString &setNum(ulong, int base=10);
QString &setNum(qlonglong, int base=10); QString &setNum(qlonglong, int base=10);
QString &setNum(qulonglong, int base=10); QString &setNum(qulonglong, int base=10);
QString &setNum(float, char f='g', int prec=6); QString &setNum(float, char format='g', int precision=6);
QString &setNum(double, char f='g', int prec=6); QString &setNum(double, char format='g', int precision=6);
static QString number(int, int base=10); static QString number(int, int base=10);
static QString number(uint, int base=10); static QString number(uint, int base=10);
@ -863,7 +863,7 @@ public:
static QString number(ulong, int base=10); static QString number(ulong, int base=10);
static QString number(qlonglong, int base=10); static QString number(qlonglong, int base=10);
static QString number(qulonglong, int base=10); static QString number(qulonglong, int base=10);
static QString number(double, char f='g', int prec=6); static QString number(double, char format='g', int precision=6);
friend bool operator==(const QString &s1, const QString &s2) noexcept friend bool operator==(const QString &s1, const QString &s2) noexcept
{ return (s1.size() == s2.size()) && QtPrivate::compareStrings(s1, s2, Qt::CaseSensitive) == 0; } { return (s1.size() == s2.size()) && QtPrivate::compareStrings(s1, s2, Qt::CaseSensitive) == 0; }