QRegularExpression: improve docs about porting from QRegExp

Change-Id: Ie5d737188977b0e4dc1070c2d7329d0ecb6a9308
Reviewed-by: David Faure <david.faure@kdab.com>

1 files changed, 32 insertions, 0 deletions

diff --git a/src/corelib/text/qregularexpression.cpp b/src/corelib/text/qregularexpression.cpp
index 8d2187eb28..a02d471134 100644
--- a/src/corelib/text/qregularexpression.cpp
+++ b/src/corelib/text/qregularexpression.cpp
@@ -443,6 +443,38 @@ QT_BEGIN_NAMESPACE
 
     Other differences are outlined below.
 
+    \section2 Different pattern syntax
+
+    Porting a regular expression from QRegExp to QRegularExpression may require
+    changes to the pattern itself.
+
+    In certain scenarios, QRegExp was too lenient and accepted patterns that
+    are simply invalid when using QRegularExpression. These are somehow easy
+    to detect, because the QRegularExpression objects built with these patterns
+    are not valid (cf. isValid()).
+
+    In other cases, a pattern ported from QRegExp to QRegularExpression may
+    silently change semantics. Therefore, it is necessary to review the
+    patterns used. The most notable cases of silent incompatibility are:
+
+    \list
+
+    \li Curly braces are needed in order to use a hexadecimal escape like
+    \c{\xHHHH} with more than 2 digits. A pattern like \c{\x2022} neeeds to
+    be ported to \c{\x{2022}}, or it will match a space (\c{0x20}) followed
+    by the string \c{"22"}. In general, it is highly recommended to always use
+    curly braces with the \c{\\x} escape, no matter the amount of digits
+    specified.
+
+    \li A 0-to-n quantification like \c{{,n}} needs to be ported to c{{0,n}} to
+    preserve semantics. Otherwise, a pattern such as \c{\d{,3}} would
+    actually match a digit followed by the exact string \c{"{,3}"}.
+
+    \li QRegExp by default does Unicode-aware matching, while
+    QRegularExpression requires a separate option; see below for more details.
+
+    \endlist
+
     \section2 Porting from QRegExp::exactMatch()
 
     QRegExp::exactMatch() in Qt 4 served two purposes: it exactly matched