Rename Qt::escape to QString::toHtmlEscaped, add compat method

Merge-request: 56
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@nokia.com>

Change-Id: I46bbb2df10968e88b5eb5ef8dae182a651b622b8
Reviewed-on: http://codereview.qt-project.org/5793
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@nokia.com>

7 files changed, 55 insertions, 42 deletions

diff --git a/dist/changes-5.0.0 b/dist/changes-5.0.0
index 803e16ac46..899c94450f 100644
--- a/dist/changes-5.0.0
+++ b/dist/changes-5.0.0
@@ -30,6 +30,9 @@ information about a particular change.
 
 - QCoreApplication::translate() will no longer return the source text when
   the translation is empty. Use lrelease -removeidentical for optimization.
+  
+- Qt::escape() is deprecated (but can be enabled via
+  QT_DISABLE_DEPRECATED_BEFORE), use QString::toHtmlEscaped() instead.
 
 ****************************************************************************
 *                           General                                        *
diff --git a/doc/src/snippets/code/src_corelib_tools_qstring.cpp b/doc/src/snippets/code/src_corelib_tools_qstring.cpp
index 740ec54af5..4a43ac0f77 100644
--- a/doc/src/snippets/code/src_corelib_tools_qstring.cpp
+++ b/doc/src/snippets/code/src_corelib_tools_qstring.cpp
@@ -89,6 +89,6 @@ QLabel *label = new QLabel(QLatin1String("MOD"), this);
 
 //! [7]
 QString plain = "#include <QtCore>"
-QString html = Qt::escape(plain);
+QString html = plain.toHtmlEscaped();
 // html == "#include &lt;QtCore&gt;"
 //! [7]
diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp
index 37f8554381..c22c8a9edd 100644
--- a/src/corelib/tools/qstring.cpp
+++ b/src/corelib/tools/qstring.cpp
@@ -8788,6 +8788,14 @@ QVector<uint> QStringRef::toUcs4() const
     return v;
 }
 
+
+/*!
+    \obsolete
+    \fn QString Qt::escape(const QString &plain)
+
+    \sa QString::toHtmlEscaped()
+*/
+
 /*!
     Converts the plain text string \a plain to a HTML string with
     HTML metacharacters \c{<}, \c{>}, \c{&}, and \c{"} replaced by HTML
@@ -8795,27 +8803,24 @@ QVector<uint> QStringRef::toUcs4() const
 
     Example:
 
-    \snippet doc/src/snippets/code/src_gui_text_qtextdocument.cpp 0
-
-    This function is defined in the \c <QString> header file.
-
-    \sa convertFromPlainText(), mightBeRichText()
+    \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 7
 */
-QString Qt::escape(const QString &plain)
+QString QString::toHtmlEscaped() const
 {
     QString rich;
-    rich.reserve(int(plain.length() * 1.1));
-    for (int i = 0; i < plain.length(); ++i) {
-        if (plain.at(i) == QLatin1Char('<'))
+    const int len = length();
+    rich.reserve(int(len * 1.1));
+    for (int i = 0; i < len; ++i) {
+        if (at(i) == QLatin1Char('<'))
             rich += QLatin1String("&lt;");
-        else if (plain.at(i) == QLatin1Char('>'))
+        else if (at(i) == QLatin1Char('>'))
             rich += QLatin1String("&gt;");
-        else if (plain.at(i) == QLatin1Char('&'))
+        else if (at(i) == QLatin1Char('&'))
             rich += QLatin1String("&amp;");
-        else if (plain.at(i) == QLatin1Char('"'))
+        else if (at(i) == QLatin1Char('"'))
             rich += QLatin1String("&quot;");
         else
-            rich += plain.at(i);
+            rich += at(i);
     }
     rich.squeeze();
     return rich;
diff --git a/src/corelib/tools/qstring.h b/src/corelib/tools/qstring.h
index adb7e06ce1..b73a34a2a0 100644
--- a/src/corelib/tools/qstring.h
+++ b/src/corelib/tools/qstring.h
@@ -330,6 +330,7 @@ public:
 
     QString trimmed() const Q_REQUIRED_RESULT;
     QString simplified() const Q_REQUIRED_RESULT;
+    QString toHtmlEscaped() const Q_REQUIRED_RESULT;
 
     QString &insert(int i, QChar c);
     QString &insert(int i, const QChar *uc, int len);
@@ -1250,7 +1251,11 @@ inline QBool QStringRef::contains(const QStringRef &s, Qt::CaseSensitivity cs) c
 { return QBool(indexOf(s, 0, cs) != -1); }
 
 namespace Qt {
-    Q_CORE_EXPORT QString escape(const QString &plain);
+#if QT_DEPRECATED_SINCE(5, 0)
+QT_DEPRECATED inline QString escape(const QString &plain) {
+    return plain.toHtmlEscaped();
+}
+#endif
 }
 
 QT_END_NAMESPACE
diff --git a/src/gui/text/qtextdocument.cpp b/src/gui/text/qtextdocument.cpp
index c44e98b77e..8d9a8c405a 100644
--- a/src/gui/text/qtextdocument.cpp
+++ b/src/gui/text/qtextdocument.cpp
@@ -2087,7 +2087,7 @@ void QTextHtmlExporter::emitAttribute(const char *attribute, const QString &valu
     html += QLatin1Char(' ');
     html += QLatin1String(attribute);
     html += QLatin1String("=\"");
-    html += Qt::escape(value);
+    html += value.toHtmlEscaped();
     html += QLatin1Char('"');
 }
 
@@ -2360,7 +2360,7 @@ void QTextHtmlExporter::emitFontFamily(const QString &family)
         quote = QLatin1String("&quot;");
 
     html += quote;
-    html += Qt::escape(family);
+    html += family.toHtmlEscaped();
     html += quote;
     html += QLatin1Char(';');
 }
@@ -2394,13 +2394,13 @@ void QTextHtmlExporter::emitFragment(const QTextFragment &fragment)
         const QString name = format.anchorName();
         if (!name.isEmpty()) {
             html += QLatin1String("<a name=\"");
-            html += Qt::escape(name);
+            html += name.toHtmlEscaped();
             html += QLatin1String("\"></a>");
         }
         const QString href = format.anchorHref();
         if (!href.isEmpty()) {
             html += QLatin1String("<a href=\"");
-            html += Qt::escape(href);
+            html += href.toHtmlEscaped();
             html += QLatin1String("\">");
             closeAnchor = true;
         }
@@ -2449,7 +2449,7 @@ void QTextHtmlExporter::emitFragment(const QTextFragment &fragment)
     } else {
         Q_ASSERT(!txt.contains(QChar::ObjectReplacementCharacter));
 
-        txt = Qt::escape(txt);
+        txt = txt.toHtmlEscaped();
 
         // split for [\n{LineSeparator}]
         QString forcedLineBreakRegExp = QString::fromLatin1("[\\na]");
diff --git a/tests/auto/corelib/tools/qstring/tst_qstring.cpp b/tests/auto/corelib/tools/qstring/tst_qstring.cpp
index 176becb06c..1721f80a8f 100644
--- a/tests/auto/corelib/tools/qstring/tst_qstring.cpp
+++ b/tests/auto/corelib/tools/qstring/tst_qstring.cpp
@@ -226,6 +226,8 @@ private slots:
     void literals();
 
     void reserve();
+    void toHtmlEscaped_data();
+    void toHtmlEscaped();
 };
 
 typedef QList<int> IntList;
@@ -5144,6 +5146,26 @@ void tst_QString::reserve()
     nil2.reserve(0);
 }
 
+void tst_QString::toHtmlEscaped_data()
+{
+    QTest::addColumn<QString>("original");
+    QTest::addColumn<QString>("expected");
+
+    QTest::newRow("1") << "Hello World\n" << "Hello World\n";
+    QTest::newRow("2") << "#include <QtCore>" << "#include &lt;QtCore&gt;";
+    QTest::newRow("3") << "<p class=\"cool\"><a href=\"http://example.com/?foo=bar&amp;bar=foo\">plop --&gt; </a></p>"
+                       << "&lt;p class=&quot;cool&quot;&gt;&lt;a href=&quot;http://example.com/?foo=bar&amp;amp;bar=foo&quot;&gt;plop --&amp;gt; &lt;/a&gt;&lt;/p&gt;";
+    QTest::newRow("4") << QString::fromUtf8("<\320\222\321\201>") << QString::fromUtf8("&lt;\320\222\321\201&gt;");
+}
+
+void tst_QString::toHtmlEscaped()
+{
+    QFETCH(QString, original);
+    QFETCH(QString, expected);
+
+    QCOMPARE(original.toHtmlEscaped(), expected);
+}
+
 QTEST_APPLESS_MAIN(tst_QString)
 
 #include "tst_qstring.moc"
diff --git a/tests/auto/gui/text/qtextdocument/tst_qtextdocument.cpp b/tests/auto/gui/text/qtextdocument/tst_qtextdocument.cpp
index c98a703acc..ea8878e9f1 100644
--- a/tests/auto/gui/text/qtextdocument/tst_qtextdocument.cpp
+++ b/tests/auto/gui/text/qtextdocument/tst_qtextdocument.cpp
@@ -177,8 +177,6 @@ private slots:
     void testUndoBlocks();
 
     void receiveCursorPositionChangedAfterContentsChange();
-    void escape_data();
-    void escape();
 
     void copiedFontSize();
 
@@ -2718,26 +2716,6 @@ void tst_QTextDocument::receiveCursorPositionChangedAfterContentsChange()
     QCOMPARE(rec.first, QString("contentsChanged"));
 }
 
-void tst_QTextDocument::escape_data()
-{
-    QTest::addColumn<QString>("original");
-    QTest::addColumn<QString>("expected");
-
-    QTest::newRow("1") << "Hello World\n" << "Hello World\n";
-    QTest::newRow("2") << "#include <QtCore>" << "#include &lt;QtCore&gt;";
-    QTest::newRow("3") << "<p class=\"cool\"><a href=\"http://example.com/?foo=bar&amp;bar=foo\">plop --&gt; </a></p>"
-                       << "&lt;p class=&quot;cool&quot;&gt;&lt;a href=&quot;http://example.com/?foo=bar&amp;amp;bar=foo&quot;&gt;plop --&amp;gt; &lt;/a&gt;&lt;/p&gt;";
-    QTest::newRow("4") << QString::fromUtf8("<\320\222\321\201>") << QString::fromUtf8("&lt;\320\222\321\201&gt;");
-}
-
-void tst_QTextDocument::escape()
-{
-    QFETCH(QString, original);
-    QFETCH(QString, expected);
-
-    QCOMPARE(Qt::escape(original), expected);
-}
-
 void tst_QTextDocument::copiedFontSize()
 {
     QTextDocument documentInput;