QRegularExpression: add QRegularExpression* set of classes

Added QRegularExpression, QRegularExpressionMatch and
QRegularExpressionMatchIterator as PCRE-enabled, regexp classes.
Documentation is included, as well as a first round of autotests.

Task-number: QTBUG-23489
Change-Id: Id47031b80602c913ccd2fd740070e3024ea06abc
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Lars Knoll <lars.knoll@nokia.com>

dist/changes-5.0.0

@@ -317,6 +317,11 @@ QtCore
 * QIntValidator and QDoubleValidator no longer fall back to using the C locale if
   the requested locale fails to validate the input.
 
+* A new set of classes for doing pattern matching with Perl-compatible regular
+  expressions has been added: QRegularExpression, QRegularExpressionMatch and
+  QRegularExpressionMatchIterator. They aim to replace QRegExp with a more
+  powerful and flexible regular expression engine.
+
 QtGui
 -----
 * Accessibility has been refactored. The hierachy of accessible objects is implemented via

doc/src/network/files-and-resources/datastreamformat.qdoc

@@ -298,6 +298,11 @@
             \li Regular expression syntax (quint8)
             \li Minimal matching (quint8)
             \endlist
+    \row \li QRegularExpression
+         \li \list
+            \li The regular expression pattern (QString)
+            \li The pattern options (quint32)
+            \endlist
     \row \li QRegion
          \li \list
             \li The size of the data, i.e. 8 + 16 * (number of rectangles) (quint32)

doc/src/snippets/code/src_corelib_tools_qregularexpression.cpp

@@ -0,0 +1,289 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Giuseppe D'Angelo <dangelog@gmail.com>.
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+QRegularExpression re("a pattern");
+//! [0]
+
+
+//! [1]
+QRegularExpression re;
+re.setPattern("another pattern");
+//! [1]
+
+
+//! [2]
+// matches two digits followed by a space and a word
+QRegularExpression re("\\d\\d \\w+");
+
+// matches a backslash
+QRegularExpression re2("\\\\");
+//! [2]
+
+
+//! [3]
+QRegularExpression re("a third pattern");
+QString pattern = re.pattern(); // pattern == "a third pattern"
+//! [3]
+
+
+//! [4]
+// matches "Qt rocks", but also "QT rocks", "QT ROCKS", "qT rOcKs", etc.
+QRegularExpression re("Qt rocks", QRegularExpression::CaseInsensitiveOption);
+//! [4]
+
+
+//! [5]
+QRegularExpression re("^\\d+$");
+re.setPatternOptions(QRegularExpression::MultilineOption);
+// re matches any line in the subject string that contains only digits (but at least one)
+//! [5]
+
+
+//! [6]
+QRegularExpression re = QRegularExpression("^two.*words$", QRegularExpression::MultilineOption
+                                                           | QRegularExpression::DotMatchesEverythingOption);
+
+QRegularExpression::PatternOptions options = re.patternOptions();
+// options == QRegularExpression::MultilineOption | QRegularExpression::DotMatchesEverythingOption
+//! [6]
+
+
+//! [7]
+// match two digits followed by a space and a word
+QRegularExpression re("\\d\\d \\w+");
+QRegularExpressionMatch match = re.match("abc123 def");
+bool hasMatch = match.hasMatch(); // true
+//! [7]
+
+
+//! [8]
+QRegularExpression re("\\d\\d \\w+");
+QRegularExpressionMatch match = re.match("abc123 def");
+if (match.hasMatch()) {
+    QString matched = match.captured(0); // matched == "23 def"
+    // ...
+}
+//! [8]
+
+
+//! [9]
+QRegularExpression re("\\d\\d \\w+");
+QRegularExpressionMatch match = re.match("12 abc 45 def", 1);
+if (match.hasMatch()) {
+    QString matched = match.captured(0); // matched == "45 def"
+    // ...
+}
+//! [9]
+
+
+//! [10]
+QRegularExpression re("^(\\d\\d)/(\\d\\d)/(\\d\\d\\d\\d)$");
+QRegularExpressionMatch match = re.match("08/12/1985");
+if (match.hasMatch()) {
+    QString day = re.captured(1); // day == "08"
+    QString month = re.captured(2); // month == "12"
+    QString year = re.captured(3); // year == "1985"
+    // ...
+}
+//! [10]
+
+
+//! [11]
+QRegularExpression re("abc(\\d+)def");
+QRegularExpressionMatch match = re.match("XYZabc123defXYZ");
+if (match.hasMatch()) {
+    int startOffset = re.capturedStart(1); // startOffset == 6
+    int endOffset = re.capturedEnd(1); // endOffset == 9
+    // ...
+}
+//! [11]
+
+
+//! [12]
+QRegularExpression re("^(?<date>\\d\\d)/(?<month>\\d\\d)/(?<year>\\d\\d\\d\\d)$");
+QRegularExpressionMatch match = re.match("08/12/1985");
+if (match.hasMatch()) {
+    QString date = match.captured("date"); // date == "08"
+    QString month = match.captured("month"); // month == "12"
+    QString year = match.captured("year"); // year == 1985
+}
+//! [12]
+
+
+//! [13]
+QRegularExpression re("(\\w+)");
+QRegularExpressionMatchIterator i = re.globalMatch("the quick fox");
+//! [13]
+
+
+//! [14]
+QStringList words;
+while (i.hasNext()) {
+    QRegularExpressionMatch match = i.next();
+    QString word = match.captured(1);
+    words << word;
+}
+// words contains "the", "quick", "fox"
+//! [14]
+
+
+//! [15]
+QString pattern("^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \\d\\d?, \\d\\d\\d\\d$");
+QRegularExpression re(pattern);
+
+QString input("Jan 21,");
+QRegularExpressionMatch match = re.match(input, 0, QRegularExpressionMatch::PartialPreferCompleteMatch);
+bool hasMatch = match.hasMatch(); // false
+bool hasPartialMatch = match.hasPartialMatch(); // true
+//! [15]
+
+
+//! [16]
+QString input("Dec 8, 1985");
+QRegularExpressionMatch match = re.match(input, 0, QRegularExpressionMatch::PartialPreferCompleteMatch);
+bool hasMatch = match.hasMatch(); // true
+bool hasPartialMatch = match.hasPartialMatch(); // false
+//! [16]
+
+
+//! [17]
+QRegularExpression re("abc\\w+X|def");
+QRegularExpressionMatch match = re.match("abcdef", 0, QRegularExpressionMatch::PartialPreferCompleteMatch);
+bool hasMatch = match.hasMatch(); // true
+bool hasPartialMatch = match.hasPartialMatch(); // false
+QString captured = match.captured(0); // captured == "def"
+//! [17]
+
+
+//! [18]
+QRegularExpression re("abc\\w+X|defY");
+QRegularExpressionMatch match = re.match("abcdef", 0, QRegularExpressionMatch::PartialPreferCompleteMatch);
+bool hasMatch = match.hasMatch(); // false
+bool hasPartialMatch = match.hasPartialMatch(); // true
+QString captured = match.captured(0); // captured == "abcdef"
+//! [18]
+
+
+//! [19]
+QRegularExpression re("abc|ab");
+QRegularExpressionMatch match = re.match("ab", 0, QRegularExpressionMatch::PartialPreferFirstMatch);
+bool hasMatch = match.hasMatch(); // false
+bool hasPartialMatch = match.hasPartialMatch(); // true
+//! [19]
+
+
+//! [20]
+QRegularExpression re("abc(def)?");
+QRegularExpressionMatch match = re.match("abc", 0, QRegularExpressionMatch::PartialPreferFirstMatch);
+bool hasMatch = match.hasMatch(); // false
+bool hasPartialMatch = match.hasPartialMatch(); // true
+//! [20]
+
+//! [21]
+QRegularExpression re("(abc)*");
+QRegularExpressionMatch match = re.match("abc", 0, QRegularExpressionMatch::PartialPreferFirstMatch);
+bool hasMatch = match.hasMatch(); // false
+bool hasPartialMatch = match.hasPartialMatch(); // true
+//! [21]
+
+//! [22]
+QRegularExpression invalidRe("(unmatched|parenthesis");
+bool isValid = invalidRe.isValid(); // false
+//! [22]
+
+//! [23]
+QRegularExpression invalidRe("(unmatched|parenthesis");
+if (!invalidRe.isValid()) {
+    QString errorString = invalidRe.errorString(); // errorString == "missing )"
+    int errorOffset = invalidRe.patternErrorOffset(); // errorOffset == 22
+    // ...
+}
+//! [23]
+
+//! [24]
+QRegularExpression re("^this pattern must match exactly$");
+//! [24]
+
+//! [25]
+QString p("a .*|pattern");
+QRegularExpression re("\\A(?:" + p + ")\\z"); // re matches exactly the pattern string p
+//! [25]
+
+//! [26]
+QString escaped = QRegularExpression::escape("a(x) = f(x) + g(x)");
+// escaped == "a\\(x\\)\\ \\=\\ f\\(x\\)\\ \\+\\ g\\(x\\)"
+//! [26]
+
+//! [27]
+QString pattern = "(" + QRegularExpression::escape(name) +
+                  "|" + QRegularExpression::escape(nickname) + ")";
+QRegularExpression re(pattern);
+//! [27]
+
+//! [28]
+QRegularExpressionMatch match = re.match(...);
+for (int i = 0; i <= match.lastCapturedIndex(); ++i) {
+    QString captured = match.captured(i);
+    // ...
+}
+//! [28]
+
+//! [29]
+QRegularExpression("(\d\d) (?<name>\w+)");
+QRegularExpressionMatch match = re.match("23 Jordan");
+if (match.hasMatch()) {
+    QString number = match.captured(1); // first == "23"
+    QString name = match.captured("name"); // name == "Jordan"
+}
+//! [29]
+
+//! [30]
+// extracts the words
+QRegularExpression re("(\w+)");
+QString subject("the quick fox");
+QRegularExpressionMatchIterator i = re.globalMatch(subject);
+while (i.hasNext()) {
+    QRegularExpressionMatch match = i.next();
+    // ...
+}
+//! [30]
+
+

src/corelib/tools/qregularexpression.h

@@ -0,0 +1,245 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Giuseppe D'Angelo <dangelog@gmail.com>.
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the QtCore module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** GNU Lesser General Public License Usage
+** This file may be used under the terms of the GNU Lesser General Public
+** License version 2.1 as published by the Free Software Foundation and
+** appearing in the file LICENSE.LGPL included in the packaging of this
+** file. Please review the following information to ensure the GNU Lesser
+** General Public License version 2.1 requirements will be met:
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms and
+** conditions contained in a signed written agreement between you and Nokia.
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QREGULAREXPRESSION_H
+#define QREGULAREXPRESSION_H
+
+#ifndef QT_NO_REGEXP
+
+#include <QtCore/qstring.h>
+#include <QtCore/qshareddata.h>
+#include <QtCore/qvariant.h>
+
+QT_BEGIN_HEADER
+
+QT_BEGIN_NAMESPACE
+
+class QRegularExpressionMatch;
+class QRegularExpressionMatchIterator;
+struct QRegularExpressionPrivate;
+
+class Q_CORE_EXPORT QRegularExpression
+{
+public:
+    enum PatternOption {
+        NoPatternOption                = 0x0000,
+        CaseInsensitiveOption          = 0x0001,
+        DotMatchesEverythingOption     = 0x0002,
+        MultilineOption                = 0x0004,
+        ExtendedPatternSyntaxOption    = 0x0008,
+        InvertedGreedinessOption       = 0x0010,
+        DontCaptureOption              = 0x0020,
+        UseUnicodePropertiesOption     = 0x0040
+    };
+    Q_DECLARE_FLAGS(PatternOptions, PatternOption)
+
+    PatternOptions patternOptions() const;
+    void setPatternOptions(PatternOptions options);
+
+    QRegularExpression();
+    explicit QRegularExpression(const QString &pattern, PatternOptions options = NoPatternOption);
+    QRegularExpression(const QRegularExpression &re);
+    ~QRegularExpression();
+    QRegularExpression &operator=(const QRegularExpression &re);
+
+#ifdef Q_COMPILER_RVALUE_REFS
+    inline QRegularExpression &operator=(QRegularExpression &&re)
+    { d.swap(re.d); return *this; }
+#endif
+
+    inline void swap(QRegularExpression &re) { d.swap(re.d); }
+
+    QString pattern() const;
+    void setPattern(const QString &pattern);
+
+    bool isValid() const;
+    int patternErrorOffset() const;
+    QString errorString() const;
+
+    enum MatchType {
+        NormalMatch = 0,
+        PartialPreferCompleteMatch,
+        PartialPreferFirstMatch
+    };
+
+    enum MatchOption {
+        NoMatchOption              = 0x0000,
+        AnchoredMatchOption        = 0x0001
+    };
+    Q_DECLARE_FLAGS(MatchOptions, MatchOption)
+
+    QRegularExpressionMatch match(const QString &subject,
+                                  int offset                = 0,
+                                  MatchType matchType       = NormalMatch,
+                                  MatchOptions matchOptions = NoMatchOption) const;
+
+    QRegularExpressionMatchIterator globalMatch(const QString &subject,
+                                                int offset                = 0,
+                                                MatchType matchType       = NormalMatch,
+                                                MatchOptions matchOptions = NoMatchOption) const;
+
+    static QString escape(const QString &str);
+
+    bool operator==(const QRegularExpression &re) const;
+    inline bool operator!=(const QRegularExpression &re) const { return !operator==(re); }
+
+private:
+    friend struct QRegularExpressionPrivate;
+    friend class QRegularExpressionMatch;
+    friend struct QRegularExpressionMatchPrivate;
+    friend class QRegularExpressionMatchIterator;
+
+    QRegularExpression(QRegularExpressionPrivate &dd);
+    QExplicitlySharedDataPointer<QRegularExpressionPrivate> d;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRegularExpression::PatternOptions)
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRegularExpression::MatchOptions)
+Q_DECLARE_TYPEINFO(QRegularExpression, Q_MOVABLE_TYPE);
+
+#ifndef QT_NO_DATASTREAM
+Q_CORE_EXPORT QDataStream &operator<<(QDataStream &out, const QRegularExpression &re);
+Q_CORE_EXPORT QDataStream &operator>>(QDataStream &in, QRegularExpression &re);
+#endif
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_CORE_EXPORT QDebug operator<<(QDebug debug, const QRegularExpression &re);
+#endif
+
+struct QRegularExpressionMatchPrivate;
+
+class Q_CORE_EXPORT QRegularExpressionMatch
+{
+public:
+    ~QRegularExpressionMatch();
+    QRegularExpressionMatch(const QRegularExpressionMatch &match);
+    QRegularExpressionMatch &operator=(const QRegularExpressionMatch &match);
+
+#ifdef Q_COMPILER_RVALUE_REFS
+    inline QRegularExpressionMatch &operator=(QRegularExpressionMatch &&match)
+    { d.swap(match.d); return *this; }
+#endif
+    inline void swap(QRegularExpressionMatch &match) { d.swap(match.d); }
+
+    QRegularExpression regularExpression() const;
+    QRegularExpression::MatchType matchType() const;
+    QRegularExpression::MatchOptions matchOptions() const;
+
+    bool hasMatch() const;
+    bool hasPartialMatch() const;
+
+    bool isValid() const;
+
+    int lastCapturedIndex() const;
+
+    QString captured(int nth = 0) const;
+    QStringRef capturedRef(int nth = 0) const;
+
+    QString captured(const QString &name) const;
+    QStringRef capturedRef(const QString &name) const;
+
+    QStringList capturedTexts() const;
+
+    int capturedStart(int nth = 0) const;
+    int capturedLength(int nth = 0) const;
+    int capturedEnd(int nth = 0) const;
+
+    int capturedStart(const QString &name) const;
+    int capturedLength(const QString &name) const;
+    int capturedEnd(const QString &name) const;
+
+private:
+    friend class QRegularExpression;
+    friend struct QRegularExpressionMatchPrivate;
+    friend class QRegularExpressionMatchIterator;
+
+    QRegularExpressionMatch(QRegularExpressionMatchPrivate &dd);
+    QSharedDataPointer<QRegularExpressionMatchPrivate> d;
+};
+
+Q_DECLARE_TYPEINFO(QRegularExpressionMatch, Q_MOVABLE_TYPE);
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_CORE_EXPORT QDebug operator<<(QDebug debug, const QRegularExpressionMatch &match);
+#endif
+
+struct QRegularExpressionMatchIteratorPrivate;
+
+class Q_CORE_EXPORT QRegularExpressionMatchIterator
+{
+public:
+    ~QRegularExpressionMatchIterator();
+    QRegularExpressionMatchIterator(const QRegularExpressionMatchIterator &iterator);
+    QRegularExpressionMatchIterator &operator=(const QRegularExpressionMatchIterator &iterator);
+#ifdef Q_COMPILER_RVALUE_REFS
+    inline QRegularExpressionMatchIterator &operator=(QRegularExpressionMatchIterator &&iterator)
+    { d.swap(iterator.d); return *this; }
+#endif
+    void swap(QRegularExpressionMatchIterator &iterator) { d.swap(iterator.d); }
+
+    bool isValid() const;
+
+    bool hasNext() const;
+    QRegularExpressionMatch next();
+    QRegularExpressionMatch peekNext() const;
+
+    QRegularExpression regularExpression() const;
+    QRegularExpression::MatchType matchType() const;
+    QRegularExpression::MatchOptions matchOptions() const;
+
+private:
+    friend class QRegularExpression;
+
+    QRegularExpressionMatchIterator(QRegularExpressionMatchIteratorPrivate &dd);
+    QSharedDataPointer<QRegularExpressionMatchIteratorPrivate> d;
+};
+
+Q_DECLARE_TYPEINFO(QRegularExpressionMatchIterator, Q_MOVABLE_TYPE);
+
+QT_END_NAMESPACE
+
+Q_DECLARE_METATYPE(QRegularExpression)
+
+QT_END_HEADER
+
+#endif // QT_NO_REGEXP
+
+#endif // QREGULAREXPRESSION_H

src/corelib/tools/tools.pri

@@ -30,6 +30,7 @@ HEADERS +=  \
         tools/qqueue.h \
         tools/qrect.h \
         tools/qregexp.h \
+        tools/qregularexpression.h \
         tools/qringbuffer_p.h \
         tools/qrefcount.h \
         tools/qscopedpointer.h \
@@ -75,6 +76,7 @@ SOURCES += \
         tools/qcontiguouscache.cpp \
         tools/qrect.cpp \
         tools/qregexp.cpp \
+        tools/qregularexpression.cpp \
         tools/qrefcount.cpp \
         tools/qshareddata.cpp \
         tools/qsharedpointer.cpp \
@@ -105,6 +107,12 @@ contains(QT_CONFIG,icu) {
     DEFINES += QT_USE_ICU
 }
 
+pcre {
+    include($$PWD/../../3rdparty/pcre.pri)
+} else {
+    LIBS_PRIVATE += -lpcre16
+}
+
 DEFINES += HB_EXPORT=Q_CORE_EXPORT
 INCLUDEPATH += ../3rdparty/harfbuzz/src
 HEADERS += ../3rdparty/harfbuzz/src/harfbuzz.h

tests/auto/corelib/tools/qregularexpression/.gitignore

@@ -0,0 +1 @@
+tst_qregularexpression

tests/auto/corelib/tools/qregularexpression/qregularexpression.pro

@@ -0,0 +1,4 @@
+CONFIG += testcase parallel_test
+TARGET = tst_qregularexpression
+QT = core testlib
+SOURCES = tst_qregularexpression.cpp

tests/auto/corelib/tools/tools.pro

@@ -25,6 +25,7 @@ SUBDIRS=\
     qqueue \
     qrect \
     qregexp \
+    qregularexpression \
     qringbuffer \
     qscopedpointer \
     qscopedvaluerollback \