AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests 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
of the characters and is very fast, but is not what a human would expect.
Consider sorting user-visible strings with QString::localeAwareCompare().
\sa {Comparing Strings}
*/
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
of the characters and is very fast, but is not what a human would expect.
Consider sorting user-visible strings with QString::localeAwareCompare().
\sa {Comparing Strings}
*/
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
of the characters and is very fast, but is not what a human would expect.
Consider sorting user-visible strings with QString::localeAwareCompare().
\sa {Comparing Strings}
*/
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
of the characters and is very fast, but is not what a human would expect.
Consider sorting user-visible strings with QString::localeAwareCompare().
\sa {Comparing Strings}
*/
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
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
operator<(), \l operator<=(), \l operator==(), \l operator>=(),
and so on. Note that the comparison is based exclusively on the
numeric Unicode values of the characters. It is very fast, but is
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
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.
On Unix-like platforms (including Linux, \macos and iOS), when Qt
is linked with the ICU library (which it usually is), its
locale-aware sorting is used. Otherwise, on \macos and iOS, \l
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
@ -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 false.
The comparison is based exclusively on the numeric Unicode values of
the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
localeAwareCompare().
\sa {Comparing Strings}
*/
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
\a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
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.
\sa {Comparing Strings}
*/
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
string \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
localeAwareCompare().
\sa {Comparing Strings}
*/
/*! \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;
otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
localeAwareCompare().
\sa {Comparing Strings}
*/
/*!
@ -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
string \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
localeAwareCompare().
\sa {Comparing Strings}
*/
/*! \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;
otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
localeAwareCompare().
\sa {Comparing Strings}
*/
/*! \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
{compare(s1, s2) < 0}.
The comparison is based exclusively on the numeric Unicode values
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.
\sa {Comparing Strings}
*/
/*!
@ -5558,10 +5558,7 @@ QString& QString::fill(QChar ch, qsizetype size)
otherwise returns \c false. For \a s1 != 0, this is equivalent to \c
{compare(s1, s2) <= 0}.
The comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
\sa {Comparing Strings}
*/
/*!
@ -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 false. Equivalent to \c {compare(s1, s2) > 0}.
The comparison is based exclusively on the numeric Unicode values
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.
\sa {Comparing Strings}
*/
/*!
@ -5585,10 +5579,7 @@ QString& QString::fill(QChar ch, qsizetype size)
otherwise returns \c false. For \a s1 != 0, this is equivalent to \c
{compare(s1, s2) >= 0}.
The comparison is based exclusively on the numeric Unicode values
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.
\sa {Comparing Strings}
*/
/*!
@ -5639,7 +5630,7 @@ QString& QString::fill(QChar ch, qsizetype size)
\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
lists of strings to the user.
On \macos and iOS this function compares according the
"Order for sorted lists" setting in the International preferences panel.
\sa compare(), QLocale
\sa compare(), QLocale, {Comparing Strings}
*/
/*!
@ -5797,6 +5785,8 @@ int QString::compare_helper(const QChar *data1, qsizetype length1, QLatin1String
lists of strings to the user.
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
platform-dependent manner. Use this function to present sorted
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.
Same as \c {localeAwareCompare(*this, other)}.
\sa {Comparing Strings}
*/
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;
otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
\sa {Comparing Strings}
*/
/*!
@ -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;
otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
\sa {Comparing Strings}
*/
/*!
@ -9258,10 +9246,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
Returns \c true if this string is lexically greater than string \a
other; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
\sa {Comparing Strings}
*/
/*!
@ -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
string; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
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.
\sa {Comparing Strings}
*/
/*!
@ -9346,10 +9328,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
Returns \c true if this string is lexically greater than or equal
to string \a other; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
\sa {Comparing Strings}
*/
/*!
@ -9389,10 +9368,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
Returns \c true if this string is lexically less than or equal
to string \a other; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
of the characters and is very fast, but is not what a human would
expect. Consider sorting user-interface strings with
QString::localeAwareCompare().
\sa {Comparing Strings}
*/
/*!
@ -9907,10 +9883,7 @@ bool operator==(QLatin1String s1, const QStringRef &s2) noexcept
Returns \c true if string reference \a s1 is lexically less than
string reference \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
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.
\sa {Comparing Strings}
*/
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
or equal to string reference \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
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.
\sa {Comparing Strings}
*/
/*!\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
or equal to string reference \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
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.
\sa {Comparing Strings}
*/
/*!\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
string reference \a s2; otherwise returns \c false.
The comparison is based exclusively on the numeric Unicode values
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.
\sa {Comparing Strings}
*/
@ -10300,10 +10264,7 @@ QStringRef QStringRef::appendTo(QString *string) const
platform-dependent manner. Use this function to present sorted
lists of strings to the user.
On \macos and iOS, this function compares according the
"Order for sorted lists" setting in the International prefereces panel.
\sa compare(), QLocale
\sa compare(), QLocale, {Comparing Strings}
*/
/*!
@ -10319,6 +10280,7 @@ QStringRef QStringRef::appendTo(QString *string) const
platform-dependent manner. Use this function to present sorted
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
platform-dependent manner. Use this function to present sorted
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
platform-dependent manner. Use this function to present sorted
lists of strings to the user.
\sa {Comparing Strings}
*/
/*!