Make compare(QU8SV) a non-template, document it

Templates have different overload characteristics from normal
functions, and treating q_no_char8_t and q_has_char8_t::QUtf8StingView
separately is never necessary, as one implicitly converts into the
other.

Add docs for the new UTF-8 compare() functions.

Amends b977ae371a753a82e1d0bb32c5b62099da663721.

Found in API review.

Change-Id: I58b4b28a3eccde1976d71cfa3412b734d46f314d
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
(cherry picked from commit bbb9cf225fd030a87818cb867c24ab651f797100)

5 files changed, 75 insertions, 26 deletions

diff --git a/src/corelib/text/qstring.h b/src/corelib/text/qstring.h
index 9fc9462fad..cc3fcac01c 100644
--- a/src/corelib/text/qstring.h
+++ b/src/corelib/text/qstring.h
@@ -121,17 +121,11 @@ public:
     { return QtPrivate::compareStrings(*this, other, cs); }
     [[nodiscard]] int compare(QLatin1StringView other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept
     { return QtPrivate::compareStrings(*this, other, cs); }
+    [[nodiscard]] inline int compare(QUtf8StringView other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept;
     [[nodiscard]] constexpr int compare(QChar c) const noexcept
     { return isEmpty() ? -1 : front() == c ? int(size() > 1) : uchar(m_data[0]) - c.unicode(); }
     [[nodiscard]] int compare(QChar c, Qt::CaseSensitivity cs) const noexcept
     { return QtPrivate::compareStrings(*this, QStringView(&c, 1), cs); }
-    template<bool UseChar8T>
-    [[nodiscard]] int compare(QBasicUtf8StringView<UseChar8T> other,
-                              Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept
-    {
-        return QtPrivate::compareStrings(*this, other, cs);
-    }
-
     [[nodiscard]] bool startsWith(QStringView s, Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept
     { return QtPrivate::startsWith(*this, s, cs); }
     [[nodiscard]] bool startsWith(QLatin1StringView s, Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept
@@ -1220,12 +1214,26 @@ public:
 };
 
 //
+// QLatin1StringView inline members that require QUtf8StringView:
+//
+
+int QLatin1StringView::compare(QUtf8StringView other, Qt::CaseSensitivity cs) const noexcept
+{ return QtPrivate::compareStrings(*this, other, cs); }
+
+//
 // QLatin1StringView inline members that require QString:
 //
 
 QString QLatin1StringView::toString() const { return *this; }
 
 //
+// QStringView inline members that require QUtf8StringView:
+//
+
+int QStringView::compare(QUtf8StringView other, Qt::CaseSensitivity cs) const noexcept
+{ return QtPrivate::compareStrings(*this, other, cs); }
+
+//
 // QStringView inline members that require QString:
 //
 
@@ -1250,6 +1258,17 @@ ushort QStringView::toUShort(bool *ok, int base) const
 { return QString::toIntegral_helper<ushort>(*this, ok, base); }
 
 //
+// QUtf8StringView inline members that require QStringView:
+//
+
+template <bool UseChar8T>
+int QBasicUtf8StringView<UseChar8T>::compare(QStringView other, Qt::CaseSensitivity cs) const noexcept
+{
+    return QtPrivate::compareStrings(*this, other, cs);
+}
+
+
+//
 // QUtf8StringView inline members that require QString:
 //
 
diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp
index a4d9ac62e8..6b6168924f 100644
--- a/src/corelib/text/qstringview.cpp
+++ b/src/corelib/text/qstringview.cpp
@@ -733,6 +733,18 @@ 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.
+
+    \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
+
+    \sa operator==(), operator<(), operator>()
+*/
+
+/*!
     \fn int QStringView::compare(QLatin1StringView l1, Qt::CaseSensitivity cs) const
     \fn int QStringView::compare(QChar ch) const
     \fn int QStringView::compare(QChar ch, Qt::CaseSensitivity cs) const
@@ -1357,6 +1369,17 @@ or the character \a ch
     \since 6.0
 */
 
+/*!
+    \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.
+
+    \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
+
+    \sa operator==(), operator<(), operator>()
+*/
 
 /*!
     \fn template <typename Needle, typename...Flags> auto QStringView::tokenize(Needle &&sep, Flags...flags) const
diff --git a/src/corelib/text/qstringview.h b/src/corelib/text/qstringview.h
index 20b61f1865..3dc8b5ce0b 100644
--- a/src/corelib/text/qstringview.h
+++ b/src/corelib/text/qstringview.h
@@ -8,7 +8,6 @@
 #include <QtCore/qbytearray.h>
 #include <QtCore/qstringliteral.h>
 #include <QtCore/qstringalgorithms.h>
-#include <QtCore/qutf8stringview.h>
 
 #include <string>
 #include <QtCore/q20type_traits.h>
@@ -24,6 +23,9 @@ class QString;
 class QStringView;
 class QRegularExpression;
 class QRegularExpressionMatch;
+#ifdef Q_QDOC
+class QUtf8StringView;
+#endif
 
 namespace QtPrivate {
 template <typename Char>
@@ -261,12 +263,7 @@ public:
     [[nodiscard]] int compare(QStringView other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept
     { return QtPrivate::compareStrings(*this, other, cs); }
     [[nodiscard]] inline int compare(QLatin1StringView other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept;
-    template<bool UseChar8T>
-    [[nodiscard]] int compare(QBasicUtf8StringView<UseChar8T> other,
-                              Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept
-    {
-        return QtPrivate::compareStrings(*this, other, cs);
-    }
+    [[nodiscard]] inline int compare(QUtf8StringView other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept;
     [[nodiscard]] constexpr int compare(QChar c) const noexcept
     { return size() >= 1 ? compare_single_char_helper(*utf16() - c.unicode()) : -1; }
     [[nodiscard]] int compare(QChar c, Qt::CaseSensitivity cs) const noexcept
@@ -467,15 +464,6 @@ inline QStringView qToStringViewIgnoringNull(const QStringLike &s) noexcept
                                    R{{char16_t(c), u'\0'}} ;
 }
 
-// QBasicUtf8StringView functions:
-
-template<bool UseChar8T>
-[[nodiscard]] int QBasicUtf8StringView<UseChar8T>::compare(QStringView other,
-                                                           Qt::CaseSensitivity cs) const noexcept
-{
-    return QtPrivate::compareStrings(*this, other, cs);
-}
-
 QT_END_NAMESPACE
 
 #endif /* QSTRINGVIEW_H */
diff --git a/src/corelib/text/qutf8stringview.h b/src/corelib/text/qutf8stringview.h
index c60d0e0c9a..9d7f01b708 100644
--- a/src/corelib/text/qutf8stringview.h
+++ b/src/corelib/text/qutf8stringview.h
@@ -178,6 +178,7 @@ public:
 
 #ifdef Q_QDOC
     QBasicUtf8StringView(const QByteArray &str) noexcept;
+    constexpr QBasicUtf8StringView(const storage_type *d, qsizetype n) noexcept {};
 #else
     template <typename String, if_compatible_qstring_like<String> = true>
     QBasicUtf8StringView(const String &str) noexcept
@@ -188,7 +189,7 @@ public:
     constexpr QBasicUtf8StringView(const Container &c) noexcept
         : QBasicUtf8StringView(std::data(c), lengthHelperContainer(c)) {}
 
-#ifdef __cpp_char8_t
+#if defined(__cpp_char8_t) && !defined(Q_QDOC)
     constexpr QBasicUtf8StringView(QBasicUtf8StringView<!UseChar8T> other)
         : QBasicUtf8StringView(other.data(), other.size()) {}
 #endif
@@ -201,7 +202,7 @@ public:
 
     [[nodiscard]] constexpr qsizetype size() const noexcept { return m_size; }
     [[nodiscard]] const_pointer data() const noexcept { return reinterpret_cast<const_pointer>(m_data); }
-#if defined(__cpp_char8_t) || defined(Q_QDOC)
+#ifdef __cpp_char8_t
     [[nodiscard]] const char8_t *utf8() const noexcept { return reinterpret_cast<const char8_t*>(m_data); }
 #endif
 
@@ -338,11 +339,11 @@ private:
 #else
 template <bool UseChar8T>
 Q_DECLARE_TYPEINFO_BODY(QBasicUtf8StringView<UseChar8T>, Q_PRIMITIVE_TYPE);
-#endif // Q_QDOC
 
 template <typename QStringLike, std::enable_if_t<std::is_same_v<QStringLike, QByteArray>, bool> = true>
 [[nodiscard]] inline q_no_char8_t::QUtf8StringView qToUtf8StringViewIgnoringNull(const QStringLike &s) noexcept
 { return q_no_char8_t::QUtf8StringView(s.data(), s.size()); }
+#endif // Q_QDOC
 
 QT_END_NAMESPACE
 
diff --git a/src/corelib/text/qutf8stringview.qdoc b/src/corelib/text/qutf8stringview.qdoc
index e19e451f99..60ebe954ed 100644
--- a/src/corelib/text/qutf8stringview.qdoc
+++ b/src/corelib/text/qutf8stringview.qdoc
@@ -204,6 +204,11 @@
 */
 
 /*!
+    \fn QUtf8StringView::QUtf8StringView(const storage_type *d, qsizetype n)
+    \internal
+*/
+
+/*!
     \fn QUtf8StringView::QUtf8StringView(std::nullptr_t)
 
     Constructs a null string view.
@@ -655,6 +660,19 @@
 */
 
 /*!
+    \fn int QUtf8StringView::compare(QLatin1StringView str, Qt::CaseSensitivity cs) const
+    \fn int QUtf8StringView::compare(QUtf8StringView str, Qt::CaseSensitivity cs) const
+    \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.
+
+    \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
+*/
+
+
+/*!
     \fn QUtf8StringView::isValidUtf8() const
 
     Returns \c true if this string contains valid UTF-8 encoded data,