textutils.cpp

Go to the documentation of this file.

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
 
#include "textutils.h"
 
#include <QtCore/qcryptographichash.h>
 
QT_BEGIN_NAMESPACE
 
/*!
    \namespace TextUtils
    \internal
    \brief Pure string helpers with no dependencies on QDoc driver types.
 
    TextUtils groups text-manipulation helpers that the IR builders, the
    template generator, and the legacy generators all need, but that do
    not touch Node, Tree, Config, or Generator. Keeping them here lets
    QDocLib components call them without dragging in the rest of QDoc.
 */
namespace TextUtils {
 
/*!
    \internal
    Returns the punctuation character for the word at \a wordPosition in a
    list of \a numberOfWords length. For the last position, returns "."
    (full stop). For any other word, delegates to comma().
 
    \sa comma()
 */
QString separator(qsizetype wordPosition, qsizetype numberOfWords)
{
    static QString terminator = QStringLiteral(".");
    if (wordPosition == numberOfWords - 1)
        return terminator;
    else
        return comma(wordPosition, numberOfWords);
}
 
/*!
    \internal
    Returns the inter-item punctuation for a list of \a numberOfWords words
    at \a wordPosition.
 
    For a list of length one, returns an empty QString. For a list of length
    two, returns " and ". For longer lists, returns ", " for early items and
    ", and " for the item before the last. The last position returns an
    empty QString; its punctuation is the period returned by separator().
 
    \sa separator()
 */
QString comma(qsizetype wordPosition, qsizetype numberOfWords)
{
    if (wordPosition == numberOfWords - 1)
        return QString();
    if (numberOfWords == 2)
        return QStringLiteral(" and ");
    if (wordPosition == 0 || wordPosition < numberOfWords - 2)
        return QStringLiteral(", ");
    return QStringLiteral(", and ");
}
 
/*!
    \brief Returns an ASCII-printable representation of \a str, preserving
    alphanumeric (alnum) characters ([a-zA-Z0-9]) and hyphens, but replacing
    all other characters with hyphens unless this would result in multiple
    adjacent hyphens. Upper case characters are converted to lower case.
 
    The string that is returned is normalized for use where ASCII-printable
    strings are required, such as in file names or fragment identifiers in URLs.
 
    We distinguish between hyphens in \a str and hyphens used as placeholders
    for non-alphanumeric characters.
 
    Placeholder hyphens are removed from the start and end of the output string,
    such that the resulting string does not start or end with a hyphen unless
    the original string included them. Placeholder hyphens are only generated
    to separate spans of alphanumeric characters.
 
    If any character in \a str is non-latin, or latin and not found in the
    aforementioned subset (e.g. 'ß', 'å', or 'ö'), a hash of \a str is appended
    to the final string.
 
    \b{Implementation note}
 
    Previously, an optimized implementation was used that was equivalent to
    this code for the basic translation to an ASCII-printable representation:
 
    \code
      name.replace(QRegularExpression("[^A-Za-z0-9]+"), " ");
      name = name.simplified();
      name.replace(QLatin1Char(' '), QLatin1Char('-'));
      name = name.toLower();
    \endcode
 
    Although it was measured to be approximately four times faster than this
    simple sequence of transformations, it could not distinguish between
    hyphens that were intentionally part of the input string and those that
    were generated by the implementation.
*/
QString asAsciiPrintable(const QString &str)
{
    auto legal_ascii = [](const uint value) {
        const uint start_ascii_subset{ 32 };
        const uint end_ascii_subset{ 126 };
 
        return value >= start_ascii_subset && value <= end_ascii_subset;
    };
 
    QString result;
    bool inAlphaNum{false};
    bool has_non_alnum_content{ false };
 
    // Replace all non-alphanumeric characters and non-hyphens with spaces.
    // Remove spaces that are adjacent to hyphens to prevent multiple,
    // unintentional hyphens. This generates an intermediate string.
    for (const auto &c : str) {
        char16_t u = c.unicode();
        if (!legal_ascii(u))
            has_non_alnum_content = true;
        if (u >= 'A' && u <= 'Z')
            u += 'a' - 'A';
        if ((u >= 'a' && u <= 'z') || (u >= '0' && u <= '9')) {
            result += QLatin1Char(u);
            inAlphaNum = true;
        } else if (u == '-') {
            // Remove any existing trailing space.
            if (result.endsWith(' '))
                result.chop(1);
 
            result += QLatin1Char(u);
            inAlphaNum = false;
        } else if (inAlphaNum || (!result.endsWith(' ') && !result.endsWith('-'))) {
            // Only append spaces to alphanumeric, non-space and non-hyphen characters.
            // This prevents multiple spaces in the intermediate string.
            result += QLatin1Char(' ');
            inAlphaNum = false;
        }
        // Any other character outside a span of alphanumeric characters
        // is ignored if it follows a space or a hyphen.
    }
 
    // Remove leading and trailing spaces before finally replacing spaces with hyphens.
    result = result.trimmed();
    result.replace(QLatin1Char(' '), QLatin1Char('-'));
 
    if (has_non_alnum_content) {
        auto title_hash = QString::fromLocal8Bit(
                QCryptographicHash::hash(str.toUtf8(), QCryptographicHash::Md5).toHex());
        title_hash.truncate(8);
        if (!result.isEmpty())
            result.append(QLatin1Char('-'));
        result.append(title_hash);
    }
 
    return result;
}
 
/*!
    \internal
    HTML-escapes the ampersand, less-than, greater-than, and double-quote
    characters in \a str, leaving other characters untouched.
 */
QString protect(const QString &str)
{
    qsizetype n = str.size();
    QString marked;
    marked.reserve(n * 2 + 30);
    const QChar *data = str.constData();
    for (int i = 0; i != n; ++i) {
        switch (data[i].unicode()) {
        case '&':
            marked += samp;
            break;
        case '<':
            marked += slt;
            break;
        case '>':
            marked += sgt;
            break;
        case '"':
            marked += squot;
            break;
        default:
            marked += data[i];
        }
    }
    return marked;
}
 
} // namespace TextUtils
 
QT_END_NAMESPACE