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

Be clearer about the locale-aware comparison QString supports

Browse Source 
The docs didn't make clear that there's a case where a rather poor
locale-aware compare may be in use - which turns out to be in use on
Android.

In the process, stop duplicating (in two slightly different variants)
the same paragraph in many places when we can use a \sa to refer to a
sub-section of the class doc.

Pick-to: 5.15
Task-number: QTBUG-63518
Change-Id: I5a41b0a269e477e74236131310992e70462734d7
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This commit is contained in:
Edward Welbourne 2020-07-29 10:24:12 +02:00
parent a57419b10d
commit 2ab4fe2ac8
1 changed files with 60 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1279,6 +1279,8 @@ static int qt_compare_strings(QLatin1String lhs, QLatin1String rhs, Qt::CaseSens
Case-sensitive comparison is based exclusively on the numeric Unicode values Case-sensitive comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would expect. of the characters and is very fast, but is not what a human would expect.
Consider sorting user-visible strings with QString::localeAwareCompare(). Consider sorting user-visible strings with QString::localeAwareCompare().
\sa {Comparing Strings}
*/ */
int QtPrivate::compareStrings(QStringView lhs, QStringView rhs, Qt::CaseSensitivity cs) noexcept int QtPrivate::compareStrings(QStringView lhs, QStringView rhs, Qt::CaseSensitivity cs) noexcept
{ {
@ -1299,6 +1301,8 @@ int QtPrivate::compareStrings(QStringView lhs, QStringView rhs, Qt::CaseSensitiv
Case-sensitive comparison is based exclusively on the numeric Unicode values Case-sensitive comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would expect. of the characters and is very fast, but is not what a human would expect.
Consider sorting user-visible strings with QString::localeAwareCompare(). Consider sorting user-visible strings with QString::localeAwareCompare().
\sa {Comparing Strings}
*/ */
int QtPrivate::compareStrings(QStringView lhs, QLatin1String rhs, Qt::CaseSensitivity cs) noexcept int QtPrivate::compareStrings(QStringView lhs, QLatin1String rhs, Qt::CaseSensitivity cs) noexcept
{ {
@ -1319,6 +1323,8 @@ int QtPrivate::compareStrings(QStringView lhs, QLatin1String rhs, Qt::CaseSensit
Case-sensitive comparison is based exclusively on the numeric Unicode values Case-sensitive comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would expect. of the characters and is very fast, but is not what a human would expect.
Consider sorting user-visible strings with QString::localeAwareCompare(). Consider sorting user-visible strings with QString::localeAwareCompare().
\sa {Comparing Strings}
*/ */
int QtPrivate::compareStrings(QLatin1String lhs, QStringView rhs, Qt::CaseSensitivity cs) noexcept int QtPrivate::compareStrings(QLatin1String lhs, QStringView rhs, Qt::CaseSensitivity cs) noexcept
{ {
@ -1339,6 +1345,8 @@ int QtPrivate::compareStrings(QLatin1String lhs, QStringView rhs, Qt::CaseSensit
Case-sensitive comparison is based exclusively on the numeric Latin-1 values Case-sensitive comparison is based exclusively on the numeric Latin-1 values
of the characters and is very fast, but is not what a human would expect. of the characters and is very fast, but is not what a human would expect.
Consider sorting user-visible strings with QString::localeAwareCompare(). Consider sorting user-visible strings with QString::localeAwareCompare().
\sa {Comparing Strings}
*/ */
int QtPrivate::compareStrings(QLatin1String lhs, QLatin1String rhs, Qt::CaseSensitivity cs) noexcept int QtPrivate::compareStrings(QLatin1String lhs, QLatin1String rhs, Qt::CaseSensitivity cs) noexcept
{ {
@ -1585,17 +1593,30 @@ inline char qToLower(char ch)
how many times a particular character or substring occurs in the how many times a particular character or substring occurs in the
string, use count(). string, use count().
To obtain a pointer to the actual character data, call data() or
constData(). These functions return a pointer to the beginning of
the QChar data. The pointer is guaranteed to remain valid until a
non-const function is called on the QString.
\section2 Comparing Strings
QStrings can be compared using overloaded operators such as \l QStrings can be compared using overloaded operators such as \l
operator<(), \l operator<=(), \l operator==(), \l operator>=(), operator<(), \l operator<=(), \l operator==(), \l operator>=(),
and so on. Note that the comparison is based exclusively on the and so on. Note that the comparison is based exclusively on the
numeric Unicode values of the characters. It is very fast, but is numeric Unicode values of the characters. It is very fast, but is
not what a human would expect; the QString::localeAwareCompare() not what a human would expect; the QString::localeAwareCompare()
function is a better choice for sorting user-interface strings. function is usually a better choice for sorting user-interface
strings, when such a comparison is available.
To obtain a pointer to the actual character data, call data() or On Unix-like platforms (including Linux, \macos and iOS), when Qt
constData(). These functions return a pointer to the beginning of is linked with the ICU library (which it usually is), its
the QChar data. The pointer is guaranteed to remain valid until a locale-aware sorting is used. Otherwise, on \macos and iOS, \l
non-const function is called on the QString. localeAwareCompare() compares according the "Order for sorted
lists" setting in the International preferences panel. On other
Unix-like systems without ICU, the comparison falls back to the
system library's \c strcoll(), falling back when it considers
strings equal to QString's (locale-unaware) comparison, described
above,
\section1 Converting Between encoded strings data and QString \section1 Converting Between encoded strings data and QString
@ -3325,10 +3346,7 @@ QString &QString::replace(QChar c, QLatin1String after, Qt::CaseSensitivity cs)
Returns \c true if string \a s1 is equal to string \a s2; otherwise Returns \c true if string \a s1 is equal to string \a s2; otherwise
returns \c false. returns \c false.
The comparison is based exclusively on the numeric Unicode values of \sa {Comparing Strings}
the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
localeAwareCompare().
*/ */
bool operator==(const QString &s1, const QString &s2) noexcept bool operator==(const QString &s1, const QString &s2) noexcept
{ {
@ -3390,10 +3408,7 @@ bool QString::operator==(QLatin1String other) const noexcept
Returns \c true if string \a s1 is lexically less than string Returns \c true if string \a s1 is lexically less than string
\a s2; otherwise returns \c false. \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings using the
QString::localeAwareCompare() function.
*/ */
bool operator<(const QString &s1, const QString &s2) noexcept bool operator<(const QString &s1, const QString &s2) noexcept
{ {
@ -3452,10 +3467,7 @@ bool QString::operator<(QLatin1String other) const noexcept
Returns \c true if string \a s1 is lexically less than or equal to Returns \c true if string \a s1 is lexically less than or equal to
string \a s2; otherwise returns \c false. string \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
localeAwareCompare().
*/ */
/*! \fn bool QString::operator<=(QLatin1String other) const /*! \fn bool QString::operator<=(QLatin1String other) const
@ -3503,10 +3515,7 @@ bool QString::operator<(QLatin1String other) const noexcept
Returns \c true if string \a s1 is lexically greater than string \a s2; Returns \c true if string \a s1 is lexically greater than string \a s2;
otherwise returns \c false. otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
localeAwareCompare().
*/ */
/*! /*!
@ -3557,10 +3566,7 @@ bool QString::operator>(QLatin1String other) const noexcept
Returns \c true if string \a s1 is lexically greater than or equal to Returns \c true if string \a s1 is lexically greater than or equal to
string \a s2; otherwise returns \c false. string \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
localeAwareCompare().
*/ */
/*! \fn bool QString::operator>=(QLatin1String other) const /*! \fn bool QString::operator>=(QLatin1String other) const
@ -3608,10 +3614,7 @@ bool QString::operator>(QLatin1String other) const noexcept
Returns \c true if string \a s1 is not equal to string \a s2; Returns \c true if string \a s1 is not equal to string \a s2;
otherwise returns \c false. otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
localeAwareCompare().
*/ */
/*! \fn bool QString::operator!=(QLatin1String other) const /*! \fn bool QString::operator!=(QLatin1String other) const
@ -5544,10 +5547,7 @@ QString& QString::fill(QChar ch, qsizetype size)
returns \c false. For \a s1 != 0, this is equivalent to \c returns \c false. For \a s1 != 0, this is equivalent to \c
{compare(s1, s2) < 0}. {compare(s1, s2) < 0}.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings using the
QString::localeAwareCompare() function.
*/ */
/*! /*!
@ -5558,10 +5558,7 @@ QString& QString::fill(QChar ch, qsizetype size)
otherwise returns \c false. For \a s1 != 0, this is equivalent to \c otherwise returns \c false. For \a s1 != 0, this is equivalent to \c
{compare(s1, s2) <= 0}. {compare(s1, s2) <= 0}.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
*/ */
/*! /*!
@ -5571,10 +5568,7 @@ QString& QString::fill(QChar ch, qsizetype size)
Returns \c true if \a s1 is lexically greater than \a s2; otherwise Returns \c true if \a s1 is lexically greater than \a s2; otherwise
returns \c false. Equivalent to \c {compare(s1, s2) > 0}. returns \c false. Equivalent to \c {compare(s1, s2) > 0}.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings using the
QString::localeAwareCompare() function.
*/ */
/*! /*!
@ -5585,10 +5579,7 @@ QString& QString::fill(QChar ch, qsizetype size)
otherwise returns \c false. For \a s1 != 0, this is equivalent to \c otherwise returns \c false. For \a s1 != 0, this is equivalent to \c
{compare(s1, s2) >= 0}. {compare(s1, s2) >= 0}.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings using the
QString::localeAwareCompare() function.
*/ */
/*! /*!
@ -5639,7 +5630,7 @@ QString& QString::fill(QChar ch, qsizetype size)
\snippet qstring/main.cpp 16 \snippet qstring/main.cpp 16
\sa operator==(), operator<(), operator>() \sa operator==(), operator<(), operator>(), {Comparing Strings}
*/ */
/*! /*!
@ -5777,10 +5768,7 @@ int QString::compare_helper(const QChar *data1, qsizetype length1, QLatin1String
platform-dependent manner. Use this function to present sorted platform-dependent manner. Use this function to present sorted
lists of strings to the user. lists of strings to the user.
On \macos and iOS this function compares according the \sa compare(), QLocale, {Comparing Strings}
"Order for sorted lists" setting in the International preferences panel.
\sa compare(), QLocale
*/ */
/*! /*!
@ -5797,6 +5785,8 @@ int QString::compare_helper(const QChar *data1, qsizetype length1, QLatin1String
lists of strings to the user. lists of strings to the user.
Same as \c {localeAwareCompare(*this, other)}. Same as \c {localeAwareCompare(*this, other)}.
\sa {Comparing Strings}
*/ */
/*! /*!
@ -5811,6 +5801,8 @@ int QString::compare_helper(const QChar *data1, qsizetype length1, QLatin1String
The comparison is performed in a locale- and also The comparison is performed in a locale- and also
platform-dependent manner. Use this function to present sorted platform-dependent manner. Use this function to present sorted
lists of strings to the user. lists of strings to the user.
\sa {Comparing Strings}
*/ */
@ -5832,6 +5824,8 @@ int QString::compare_helper(const QChar *data1, qsizetype length1, QLatin1String
lists of strings to the user. lists of strings to the user.
Same as \c {localeAwareCompare(*this, other)}. Same as \c {localeAwareCompare(*this, other)}.
\sa {Comparing Strings}
*/ */
int QString::localeAwareCompare(const QString &other) const int QString::localeAwareCompare(const QString &other) const
{ {
@ -9171,10 +9165,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
Returns \c true if this string is equal to string \a other; Returns \c true if this string is equal to string \a other;
otherwise returns \c false. otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
*/ */
/*! /*!
@ -9214,10 +9205,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
Returns \c true if this string is not equal to string \a other; Returns \c true if this string is not equal to string \a other;
otherwise returns \c false. otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
*/ */
/*! /*!
@ -9258,10 +9246,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
Returns \c true if this string is lexically greater than string \a Returns \c true if this string is lexically greater than string \a
other; otherwise returns \c false. other; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
*/ */
/*! /*!
@ -9302,10 +9287,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
Returns \c true if this string is lexically less than the \a other Returns \c true if this string is lexically less than the \a other
string; otherwise returns \c false. string; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings using the
QString::localeAwareCompare() function.
*/ */
/*! /*!
@ -9346,10 +9328,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
Returns \c true if this string is lexically greater than or equal Returns \c true if this string is lexically greater than or equal
to string \a other; otherwise returns \c false. to string \a other; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
*/ */
/*! /*!
@ -9389,10 +9368,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
Returns \c true if this string is lexically less than or equal Returns \c true if this string is lexically less than or equal
to string \a other; otherwise returns \c false. to string \a other; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
*/ */
/*! /*!
@ -9907,10 +9883,7 @@ bool operator==(QLatin1String s1, const QStringRef &s2) noexcept
Returns \c true if string reference \a s1 is lexically less than Returns \c true if string reference \a s1 is lexically less than
string reference \a s2; otherwise returns \c false. string reference \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings using the
QString::localeAwareCompare() function.
*/ */
bool operator<(const QStringRef &s1,const QStringRef &s2) noexcept bool operator<(const QStringRef &s1,const QStringRef &s2) noexcept
{ {
@ -9924,10 +9897,7 @@ bool operator<(const QStringRef &s1,const QStringRef &s2) noexcept
Returns \c true if string reference \a s1 is lexically less than Returns \c true if string reference \a s1 is lexically less than
or equal to string reference \a s2; otherwise returns \c false. or equal to string reference \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings using the
QString::localeAwareCompare() function.
*/ */
/*!\fn bool operator>=(const QStringRef &s1,const QStringRef &s2) /*!\fn bool operator>=(const QStringRef &s1,const QStringRef &s2)
@ -9937,10 +9907,7 @@ bool operator<(const QStringRef &s1,const QStringRef &s2) noexcept
Returns \c true if string reference \a s1 is lexically greater than Returns \c true if string reference \a s1 is lexically greater than
or equal to string reference \a s2; otherwise returns \c false. or equal to string reference \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings using the
QString::localeAwareCompare() function.
*/ */
/*!\fn bool operator>(const QStringRef &s1,const QStringRef &s2) /*!\fn bool operator>(const QStringRef &s1,const QStringRef &s2)
@ -9950,10 +9917,7 @@ bool operator<(const QStringRef &s1,const QStringRef &s2) noexcept
Returns \c true if string reference \a s1 is lexically greater than Returns \c true if string reference \a s1 is lexically greater than
string reference \a s2; otherwise returns \c false. string reference \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values \sa {Comparing Strings}
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings using the
QString::localeAwareCompare() function.
*/ */
@ -10300,10 +10264,7 @@ QStringRef QStringRef::appendTo(QString *string) const
platform-dependent manner. Use this function to present sorted platform-dependent manner. Use this function to present sorted
lists of strings to the user. lists of strings to the user.
On \macos and iOS, this function compares according the \sa compare(), QLocale, {Comparing Strings}
"Order for sorted lists" setting in the International prefereces panel.
\sa compare(), QLocale
*/ */
/*! /*!
@ -10319,6 +10280,7 @@ QStringRef QStringRef::appendTo(QString *string) const
platform-dependent manner. Use this function to present sorted platform-dependent manner. Use this function to present sorted
lists of strings to the user. lists of strings to the user.
\sa {Comparing Strings}
*/ */
/*! /*!
@ -10333,6 +10295,8 @@ QStringRef QStringRef::appendTo(QString *string) const
The comparison is performed in a locale- and also The comparison is performed in a locale- and also
platform-dependent manner. Use this function to present sorted platform-dependent manner. Use this function to present sorted
lists of strings to the user. lists of strings to the user.
\sa {Comparing Strings}
*/ */
/*! /*!
@ -10347,6 +10311,8 @@ QStringRef QStringRef::appendTo(QString *string) const
The comparison is performed in a locale- and also The comparison is performed in a locale- and also
platform-dependent manner. Use this function to present sorted platform-dependent manner. Use this function to present sorted
lists of strings to the user. lists of strings to the user.
\sa {Comparing Strings}
*/ */
/*! /*!