1 files changed, 78 insertions, 5 deletions

diff --git a/src/corelib/text/qanystringview.qdoc b/src/corelib/text/qanystringview.qdoc
index b70f7b028b..796202e2e1 100644
--- a/src/corelib/text/qanystringview.qdoc
+++ b/src/corelib/text/qanystringview.qdoc
@@ -17,9 +17,11 @@
 
     Unlike QStringView and QUtf8StringView, QAnyStringView can hold
     strings of any of the following encodings: UTF-8, UTF-16, and
-    Latin-1. The latter is supported to keep old source working
-    efficiently. It is expected that by Qt 7, the Latin-1 support will
-    be removed.
+    Latin-1. The latter is supported because Latin-1, unlike UTF-8,
+    can be efficiently compared to UTF-16 data: a length mismatch
+    already means the strings cannot be equal. This is not true for
+    UTF-8/UTF-16 comparisons, because UTF-8 is a variable-length
+    encoding.
 
     The string may be represented as an array (or an array-compatible
     data-structure such as QString, std::basic_string, etc.) of \c
@@ -36,7 +38,7 @@
     When used as an interface type, QAnyStringView allows a single
     function to accept a wide variety of string data sources. One
     function accepting QAnyStringView thus replaces five function
-    overloads (taking QString, \c{(const QChar*, int)},
+    overloads (taking QString, \c{(const QChar*, qsizetype)},
     QUtf8StringView, QLatin1StringView (but see above), and QChar), while
     at the same time enabling even more string data sources to be
     passed to the function, such as \c{u8"Hello World"}, a \c char8_t
@@ -45,6 +47,11 @@
     Like elsewhere in Qt, QAnyStringView assumes \c char data is encoded
     in UTF-8, unless it is presented as a QLatin1StringView.
 
+    Since Qt 6.4, however, UTF-8 string literals that are pure US-ASCII are
+    automatically stored as Latin-1. This is a compile-time check with no
+    runtime overhead. The feature requires compiling in C++20, or with a recent
+    GCC.
+
     QAnyStringViews should be passed by value, not by reference-to-const:
     \snippet code/src_corelib_text_qanystringview.cpp 0
 
@@ -297,7 +304,7 @@
 */
 
 /*!
-    \fn int QAnyStringView::length() const
+    \fn QAnyStringView::length() const
 
     Same as size().
 
@@ -332,6 +339,72 @@
     \sa front(), {Sizes and Sub-Strings}
 */
 
+/*! \fn template <typename Visitor> decltype(auto) QAnyStringView::visit(Visitor &&v) const
+
+    Calls \a v with either a QUtf8StringView, QLatin1String, or QStringView, depending
+    on the encoding of the string data this string-view references.
+
+    This is how most functions taking QAnyStringView fork off into per-encoding
+    functions:
+
+    \code
+    void processImpl(QLatin1String s) { ~~~ }
+    void processImpl(QUtf8StringView s) { ~~~ }
+    void processImpl(QStringView s) { ~~~ }
+
+    void process(QAnyStringView s)
+    {
+        s.visit([](auto s) { processImpl(s); });
+    }
+    \endcode
+
+    Here, we're reusing the same name, \c s, for both the QAnyStringView
+    object, as well as the lambda's parameter. This is idiomatic code and helps
+    track the identity of the objects through visit() calls, for example in more
+    complex situations such as
+
+    \code
+    bool equal(QAnyStringView lhs, QAnyStringView rhs)
+    {
+        // assuming operator==(QAnyStringView, QAnyStringView) didn't, yet, exist:
+        return lhs.visit([rhs](auto lhs) {
+            rhs.visit([lhs](auto rhs) {
+                return lhs == rhs;
+            });
+        });
+    }
+    \endcode
+
+    visit() requires that all lambda instantiations have the same return type.
+    If they differ, you get a compile error, even if there is a common type. To
+    fix, you can use explicit return types on the lambda, or cast in the return
+    statements:
+
+    \code
+    // wrong:
+    QAnyStringView firstHalf(QAnyStringView input)
+    {
+        return input.visit([](auto input) {   // ERROR: lambdas return different types
+            return input.sliced(0, input.size() / 2);
+        });
+    }
+    // correct:
+    QAnyStringView firstHalf(QAnyStringView input)
+    {
+        return input.visit([](auto input) -> QAnyStringView { // OK, explicit return type
+            return input.sliced(0, input.size() / 2);
+        });
+    }
+    // also correct:
+    QAnyStringView firstHalf(QAnyStringView input)
+    {
+        return input.visit([](auto input) {
+            return QAnyStringView(input.sliced(0, input.size() / 2)); // OK, cast to common type
+        });
+    }
+    \endcode
+*/
+
 /*!
     \fn QAnyStringView::compare(QAnyStringView lhs, QAnyStringView rhs, Qt::CaseSensitivity cs)