From 90ff2bc5c61371e37344f453d1466db2e1c8a417 Mon Sep 17 00:00:00 2001 From: Jaishree Vyas Date: Wed, 4 Oct 2023 14:55:37 +0200 Subject: [PATCH] Improve the documentation of compare() overloads for string-like types Also update the QCollator::compare() docs for consistency. Pick-to: 6.5 6.2 Task-number: QTBUG-114822 Change-Id: I5fca896cacedd93ce5a4a1a8aead1986a21f6993 Reviewed-by: Ivan Solovev (cherry picked from commit 19b17667da951799506abbb9cc7dc29c724b22c1) --- src/corelib/text/qanystringview.qdoc | 4 +++- src/corelib/text/qcollator.cpp | 9 +++++---- src/corelib/text/qlatin1stringview.qdoc | 12 +++++++----- src/corelib/text/qstring.cpp | 13 ++++++------- src/corelib/text/qstringview.cpp | 15 +++++++++------ src/corelib/text/qutf8stringview.qdoc | 5 +++-- 6 files changed, 33 insertions(+), 25 deletions(-) diff --git a/src/corelib/text/qanystringview.qdoc b/src/corelib/text/qanystringview.qdoc index 0fb68f182af..5f09f6d1a94 100644 --- a/src/corelib/text/qanystringview.qdoc +++ b/src/corelib/text/qanystringview.qdoc @@ -561,7 +561,9 @@ /*! \fn QAnyStringView::compare(QAnyStringView lhs, QAnyStringView rhs, Qt::CaseSensitivity cs) - Returns an integer that compares to zero as \a lhs compares to \a rhs. + Compares the string view \a lhs with the string view \a rhs and returns a + negative integer if \a lhs is less than \a rhs, a positive integer if it is + greater than \a rhs, and zero if they are equal. If \a cs is Qt::CaseSensitive (the default), the comparison is case sensitive; otherwise the comparison is case-insensitive. diff --git a/src/corelib/text/qcollator.cpp b/src/corelib/text/qcollator.cpp index 3e17f8cc2d2..2b49b8178b0 100644 --- a/src/corelib/text/qcollator.cpp +++ b/src/corelib/text/qcollator.cpp @@ -317,8 +317,8 @@ bool QCollator::ignorePunctuation() const Compares \a s1 with \a s2. - Returns an integer less than, equal to, or greater than zero depending on - whether \a s1 sorts before, with or after \a s2. + Returns a negative integer if \a s1 is less than \a s2, a positive integer + if it is greater than \a s2, and zero if they are equal. */ /*! @@ -341,8 +341,9 @@ bool QCollator::ignorePunctuation() const Compares \a s1 with \a s2. \a len1 and \a len2 specify the lengths of the QChar arrays pointed to by \a s1 and \a s2. - Returns an integer less than, equal to, or greater than zero depending on - whether \a s1 sorts before, with or after \a s2. + Returns a negative integer if \a s1 is less than \a s2, a positive integer + if it is greater than \a s2, and zero if they are equal. + \note In Qt versions prior to 6.4, the length arguments were of type \c{int}, not \c{qsizetype}. diff --git a/src/corelib/text/qlatin1stringview.qdoc b/src/corelib/text/qlatin1stringview.qdoc index 3bd93122322..7bde6ef5668 100644 --- a/src/corelib/text/qlatin1stringview.qdoc +++ b/src/corelib/text/qlatin1stringview.qdoc @@ -404,9 +404,10 @@ \fn int QLatin1StringView::compare(QChar ch, Qt::CaseSensitivity cs) const \since 5.14 - Returns an integer that compares to zero as this string view compares - to the UTF-16 string viewed by \a str, the Latin-1 string viewed by \a l1, - or the character \a ch, respectively. + Compares this string view with UTF-16 string view \a str, Latin-1 string view \a l1, + or the character \a ch, respectively. Returns a negative integer if this + string is less than \a str, \a l1 or \a ch, returns a positive integer if it + is greater than \a str, \a l1 or \a ch, and zero if they are equal. \include qstring.qdocinc {search-comparison-case-sensitivity} {search} @@ -417,8 +418,9 @@ \fn int QLatin1StringView::compare(QUtf8StringView str, Qt::CaseSensitivity cs) const \since 6.5 - Returns an integer that compares to zero as this string view compares to the - string view \a str. + Compares this string view with \a str and returns a negative integer if + this string view is less than \a str, a positive integer if it is greater than + \a str, and zero if they are equal. \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp index ae1732ede53..d2af9ff2abf 100644 --- a/src/corelib/text/qstring.cpp +++ b/src/corelib/text/qstring.cpp @@ -6422,9 +6422,9 @@ QString& QString::fill(QChar ch, qsizetype size) \fn int QString::compare(const QString &s1, const QString &s2, Qt::CaseSensitivity cs) \since 4.2 - Compares \a s1 with \a s2 and returns an integer less than, equal - to, or greater than zero if \a s1 is less than, equal to, or - greater than \a s2. + Compares the string \a s1 with the string \a s2 and returns a negative integer + if \a s1 is less than \a s2, a positive integer if it is greater than \a s2, + and zero if they are equal. \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} @@ -6486,10 +6486,9 @@ QString& QString::fill(QChar ch, qsizetype size) \overload compare() \since 4.2 - Lexically compares this string with the \a other string and - returns an integer less than, equal to, or greater than zero if - this string is less than, equal to, or greater than the other - string. + Lexically compares this string with the string \a other and returns + a negative integer if this string is less than \a other, a positive + integer if it is greater than \a other, and zero if they are equal. Same as compare(*this, \a other, \a cs). */ diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp index 302637eebf8..ecd266b5c46 100644 --- a/src/corelib/text/qstringview.cpp +++ b/src/corelib/text/qstringview.cpp @@ -724,8 +724,9 @@ QT_BEGIN_NAMESPACE \fn int QStringView::compare(QStringView str, Qt::CaseSensitivity cs) const \since 5.12 - Returns an integer that compares to zero as this string view compares to the - string view \a str. + Compares this string view with string view \a str and returns a negative integer if + this string view is less than \a str, a positive integer if it is greater than + \a str, and zero if they are equal. \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} @@ -736,8 +737,9 @@ QT_BEGIN_NAMESPACE \fn int QStringView::compare(QUtf8StringView str, Qt::CaseSensitivity cs) const \since 6.5 - Returns an integer that compares to zero as this string view compares to the - string view \a str. + Compares this string view with QUtf8StringView \a str and returns a negative integer if + this string view is less than \a str, a positive integer if it is greater than + \a str, and zero if they are equal. \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} @@ -750,8 +752,9 @@ QT_BEGIN_NAMESPACE \fn int QStringView::compare(QChar ch, Qt::CaseSensitivity cs) const \since 5.15 - Returns an integer that compares to zero as this string view compares to the - Latin-1 string viewed by \a l1, or the character \a ch, respectively. + Compares this string view to the Latin-1 string view \a l1, or the character \a ch. + Returns a negative integer if this string view is less than \a l1 or \a ch, + a positive integer if it is greater than \a l1 or \a ch, and zero if they are equal. \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} diff --git a/src/corelib/text/qutf8stringview.qdoc b/src/corelib/text/qutf8stringview.qdoc index e7c1daaca7b..1e5f8b50eb5 100644 --- a/src/corelib/text/qutf8stringview.qdoc +++ b/src/corelib/text/qutf8stringview.qdoc @@ -665,8 +665,9 @@ \fn int QUtf8StringView::compare(QStringView str, Qt::CaseSensitivity cs) const \since 6.5 - Returns an integer that compares to zero as this string view compares to the - string view \a str. + Compares this string view with \a str and returns a negative integer if + this string view is less than \a str, a positive integer if it is greater than + \a str, and zero if they are equal. \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} */