qdoc: Rename transmogrify() and move it under Utilities namespace

The transmogrify() function was used by the Generator to produce
clean output file names by replacing all non-alphanum characters
with hyphens. This function is useful elsewhere as well,
especially in HTMLGenerator, as it produces valid strings for use
as HTML attribute values.

Rename the function to a more descriptive canonicalizeFileName(),
move it to the Utilities namespace, improve its documentation and
touch up the implementation a bit; make it return a QString
instead of modifying a string passed as an argument.

Pick-to: 6.5
Change-Id: I6088f4603802b86f96c4a5b668668ef229b302f3
Reviewed-by: Luca Di Sera <luca.disera@qt.io>

3 files changed, 48 insertions, 41 deletions

diff --git a/src/qdoc/qdoc/generator.cpp b/src/qdoc/qdoc/generator.cpp
index c4f6ff233..f5df13087 100644
--- a/src/qdoc/qdoc/generator.cpp
+++ b/src/qdoc/qdoc/generator.cpp
@@ -240,37 +240,6 @@ void Generator::endSubPage()
     delete outStreamStack.pop();
 }
 
-/*
-  the code below is effectively equivalent to:
-  input.replace(QRegularExpression("[^A-Za-z0-9]+"), " ");
-  input = input.trimmed();
-  input.replace(QLatin1Char(' '), QLatin1Char('-'));
-  input = input.toLower();
-  as this function accounted for ~8% of total running time
-  we optimize a bit...
-*/
-static void transmogrify(QString &input, QString &output)
-{
-    // +5 prevents realloc in fileName() below
-    output.reserve(input.size() + 5);
-    bool begun = false;
-    for (int i = 0; i != input.size(); ++i) {
-        QChar c = input.at(i);
-        uint u = c.unicode();
-        if (u >= 'A' && u <= 'Z')
-            u += 'a' - 'A';
-        if ((u >= 'a' && u <= 'z') || (u >= '0' && u <= '9')) {
-            output += QLatin1Char(u);
-            begun = true;
-        } else if (begun) {
-            output += QLatin1Char('-');
-            begun = false;
-        }
-    }
-    while (output.endsWith(QLatin1Char('-')))
-        output.chop(1);
-}
-
 QString Generator::fileBase(const Node *node) const
 {
     if (!node->isPageNode() && !node->isCollectionNode())
@@ -337,11 +306,10 @@ QString Generator::fileBase(const Node *node) const
         }
     }
 
-    QString res;
-    transmogrify(base, res);
+    QString canonicalName{Utilities::canonicalizeFileName(base)};
     Node *n = const_cast<Node *>(node);
-    n->setFileNameBase(res);
-    return res;
+    n->setFileNameBase(canonicalName);
+    return canonicalName;
 }
 
 /*!
@@ -352,14 +320,13 @@ QString Generator::fileBase(const Node *node) const
  */
 QString Generator::linkForExampleFile(const QString &path, const QString &fileExt)
 {
-    QString link = path;
+    QString link{path};
     link.prepend(s_project.toLower() + QLatin1Char('-'));
 
-    QString res;
-    transmogrify(link, res);
-    res.append(QLatin1Char('.'));
-    res.append(fileExt.isEmpty() ? fileExtension() : fileExt);
-    return res;
+    QString canonicalName{Utilities::canonicalizeFileName(link)};
+    canonicalName.append(QLatin1Char('.'));
+    canonicalName.append(fileExt.isEmpty() ? fileExtension() : fileExt);
+    return canonicalName;
 }
 
 /*!
diff --git a/src/qdoc/qdoc/utilities.cpp b/src/qdoc/qdoc/utilities.cpp
index d12820d1f..d0f18338b 100644
--- a/src/qdoc/qdoc/utilities.cpp
+++ b/src/qdoc/qdoc/utilities.cpp
@@ -79,6 +79,45 @@ QString comma(qsizetype wordPosition, qsizetype numberOfWords)
 }
 
 /*!
+  \internal
+  Replace non-alphanum characters in \a str with hyphens
+  and convert all characters to lowercase. Returns the
+  result of the conversion with leading, trailing, and
+  consecutive hyphens removed.
+
+  The implementation is equivalent to:
+
+  \code
+      name.replace(QRegularExpression("[^A-Za-z0-9]+"), " ");
+      name = name.simplified();
+      name.replace(QLatin1Char(' '), QLatin1Char('-'));
+      name = name.toLower();
+  \endcode
+*/
+QString canonicalizeFileName(const QString &name)
+{
+    QString result;
+    bool begun = false;
+    const auto *data{name.constData()};
+    for (qsizetype i = 0; i < name.size(); ++i) {
+        char16_t u{data[i].unicode()};
+        if (u >= 'A' && u <= 'Z')
+            u += 'a' - 'A';
+        if ((u >= 'a' && u <= 'z') || (u >= '0' && u <= '9')) {
+            result += QLatin1Char(u);
+            begun = true;
+        } else if (begun) {
+            result += QLatin1Char('-');
+            begun = false;
+        }
+    }
+    if (result.endsWith(QLatin1Char('-')))
+        result.chop(1);
+
+    return result;
+}
+
+/*!
     \internal
 */
 static bool runProcess(const QString &program, const QStringList &arguments,
diff --git a/src/qdoc/qdoc/utilities.h b/src/qdoc/qdoc/utilities.h
index d249bcd38..998da48d3 100644
--- a/src/qdoc/qdoc/utilities.h
+++ b/src/qdoc/qdoc/utilities.h
@@ -19,6 +19,7 @@ bool debugging();
 
 QString separator(qsizetype wordPosition, qsizetype numberOfWords);
 QString comma(qsizetype wordPosition, qsizetype numberOfWords);
+QString canonicalizeFileName(const QString &name);
 QStringList getInternalIncludePaths(const QString &compiler);
 }