From 2ab4fe2ac84d0da84b489f9898d44ab77b78fd6b Mon Sep 17 00:00:00 2001 From: Edward Welbourne Date: Wed, 29 Jul 2020 10:24:12 +0200 Subject: Be clearer about the locale-aware comparison QString supports MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Topi Reiniö --- src/corelib/text/qstring.cpp | 156 +++++++++++++++++-------------------------- 1 file changed, 61 insertions(+), 95 deletions(-) (limited to 'src') diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp index 5819771a1a..2afecbca33 100644 --- a/src/corelib/text/qstring.cpp +++ b/src/corelib/text/qstring.cpp @@ -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. - - 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. + function is usually a better choice for sorting user-interface + strings, when such a comparison is available. + + 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} */ /*! -- cgit v1.2.3