QString/View: add tokenize() member functions

[ChangeLog][QtCore][QString, QStringView, QLatin1String] Added tokenize().

Change-Id: I5fbeab0ac1809ff2974e565129b61a6bdfb398bc
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

3 files changed, 74 insertions, 1 deletions

diff --git a/src/corelib/text/qstring.h b/src/corelib/text/qstring.h
index b06afccc74..54aacfb298 100644
--- a/src/corelib/text/qstring.h
+++ b/src/corelib/text/qstring.h
@@ -3,6 +3,7 @@
 ** Copyright (C) 2016 The Qt Company Ltd.
 ** Copyright (C) 2019 Intel Corporation.
 ** Copyright (C) 2019 Mail.ru Group.
+** Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com>
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtCore module of the Qt Toolkit.
@@ -196,6 +197,12 @@ public:
 
     Q_REQUIRED_RESULT QLatin1String trimmed() const noexcept { return QtPrivate::trimmed(*this); }
 
+    template <typename Needle, typename...Flags>
+    Q_REQUIRED_RESULT inline constexpr auto tokenize(Needle &&needle, Flags...flags) const
+        noexcept(noexcept(qTokenize(std::declval<const QLatin1String &>(), std::forward<Needle>(needle), flags...)))
+            -> decltype(qTokenize(*this, std::forward<Needle>(needle), flags...))
+    { return qTokenize(*this, std::forward<Needle>(needle), flags...); }
+
     inline bool operator==(const QString &s) const noexcept;
     inline bool operator!=(const QString &s) const noexcept;
     inline bool operator>(const QString &s) const noexcept;
@@ -634,6 +641,24 @@ public:
                                  Qt::SplitBehavior behavior = Qt::KeepEmptyParts) const;
 #endif
 
+    template <typename Needle, typename...Flags>
+    Q_REQUIRED_RESULT inline auto tokenize(Needle &&needle, Flags...flags) const &
+        noexcept(noexcept(qTokenize(std::declval<const QString &>(), std::forward<Needle>(needle), flags...)))
+            -> decltype(qTokenize(*this, std::forward<Needle>(needle), flags...))
+    { return qTokenize(qToStringViewIgnoringNull(*this), std::forward<Needle>(needle), flags...); }
+
+    template <typename Needle, typename...Flags>
+    Q_REQUIRED_RESULT inline auto tokenize(Needle &&needle, Flags...flags) const &&
+        noexcept(noexcept(qTokenize(std::declval<const QString>(), std::forward<Needle>(needle), flags...)))
+            -> decltype(qTokenize(std::move(*this), std::forward<Needle>(needle), flags...))
+    { return qTokenize(std::move(*this), std::forward<Needle>(needle), flags...); }
+
+    template <typename Needle, typename...Flags>
+    Q_REQUIRED_RESULT inline auto tokenize(Needle &&needle, Flags...flags) &&
+        noexcept(noexcept(qTokenize(std::declval<QString>(), std::forward<Needle>(needle), flags...)))
+            -> decltype(qTokenize(std::move(*this), std::forward<Needle>(needle), flags...))
+    { return qTokenize(std::move(*this), std::forward<Needle>(needle), flags...); }
+
 
     enum NormalizationForm {
         NormalizationForm_D,
diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp
index bf8b80ee5d..667d9306af 100644
--- a/src/corelib/text/qstringview.cpp
+++ b/src/corelib/text/qstringview.cpp
@@ -1172,4 +1172,46 @@ QT_BEGIN_NAMESPACE
     \since 6.0
 */
 
+
+/*!
+    \fn QStringView::tokenize(Needle &&sep, Flags...flags) const
+    \fn QLatin1String::tokenize(Needle &&sep, Flags...flags) const
+    \fn QString::tokenize(Needle &&sep, Flags...flags) const &
+    \fn QString::tokenize(Needle &&sep, Flags...flags) const &&
+    \fn QString::tokenize(Needle &&sep, Flags...flags) &&
+
+    Splits the string into substring views wherever \a sep occurs, and
+    returns a lazy sequence of those strings.
+
+    Equivalent to
+
+    \code
+    return QStringTokenizer{std::forward<Needle>(sep), flags...};
+    \endcode
+
+    except it works without C++17 Class Template Argument Deduction (CTAD)
+    enabled in the compiler.
+
+    See QStringTokenizer for how \a sep and \a flags interact to form
+    the result.
+
+    \note While this function returns QStringTokenizer, you should never,
+    ever, name its template arguments explicitly. If you can use C++17 Class
+    Template Argument Deduction (CTAD), you may write
+    \code
+    QStringTokenizer result = sv.tokenize(sep);
+    \endcode
+    (without template arguments). If you can't use C++17 CTAD, you must store
+    the return value only in \c{auto} variables:
+    \code
+    auto result = sv.tokenize(sep);
+    \endcode
+    This is because the template arguments of QStringTokenizer have a very
+    subtle dependency on the specific tokenize() overload from which they are
+    returned, and they don't usually correspond to the type used for the separator.
+
+    \since 6.0
+    \sa QStringTokenizer, qTokenize()
+*/
+
 QT_END_NAMESPACE
diff --git a/src/corelib/text/qstringview.h b/src/corelib/text/qstringview.h
index 4e780628cc..028bf3a544 100644
--- a/src/corelib/text/qstringview.h
+++ b/src/corelib/text/qstringview.h
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com>
+** Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com>
 ** Copyright (C) 2019 Mail.ru Group.
 ** Contact: http://www.qt.io/licensing/
 **
@@ -275,6 +275,12 @@ public:
 
     Q_REQUIRED_RESULT QStringView trimmed() const noexcept { return QtPrivate::trimmed(*this); }
 
+    template <typename Needle, typename...Flags>
+    Q_REQUIRED_RESULT constexpr inline auto tokenize(Needle &&needle, Flags...flags) const
+        noexcept(noexcept(qTokenize(std::declval<const QStringView&>(), std::forward<Needle>(needle), flags...)))
+            -> decltype(qTokenize(*this, std::forward<Needle>(needle), flags...))
+    { return qTokenize(*this, std::forward<Needle>(needle), flags...); }
+
     Q_REQUIRED_RESULT int compare(QStringView other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept
     { return QtPrivate::compareStrings(*this, other, cs); }
     Q_REQUIRED_RESULT inline int compare(QLatin1String other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const noexcept;