Utilities Namespace Reference

This namespace holds QDoc-internal utility methods. More...

Enumerations
enum class	ExampleFileKind { File , Image }

Functions
void	startDebugging (const QString &message)
void	stopDebugging (const QString &message)
bool	debugging ()
const INode *	nodeForString (const QString &string)
	Converts a string representation of a pointer address to an INode pointer.
QString	stringForNode (const INode *node)
	Converts an INode pointer address to its string representation.
QString	uniqueIdentifier (const Location &loc, const QString &prefix)
	Returns a unique identifier based on location loc, with a given prefix.
QString	separator (qsizetype wordPosition, qsizetype numberOfWords)
QString	comma (qsizetype wordPosition, qsizetype numberOfWords)
QString	asAsciiPrintable (const QString &str)
	Returns an ascii-printable representation of str.
QString	protect (const QString &string)
QStringList	getInternalIncludePaths (const QString &compiler)
bool	isGeneratedFile (const QString &path)
QStringList	pathAndFragment (const QString &linkText)
	Returns a string list containing the path and fragment components of the given linkText.
QString	linkForExampleFile (const QString &path, const QString &project, const QString &fileExt)
	Constructs an href link from an example file name.
QString	exampleFileTitle (const QString &fileName, ExampleFileKind kind)
	Constructs a title for a file or image page in an example.
QString	exampleFileTitle (const QStringList &files, const QStringList &images, const QString &fileName)
	Constructs a title for a file or image page in an example.
static void	setDebugEnabled (bool value)
static bool	runProcess (const QString &program, const QStringList &arguments, QByteArray *stdOutIn, QByteArray *stdErrIn)
static QByteArray	frameworkSuffix ()

Variables
static constexpr QLatin1StringView	samp = "&"_L1
static constexpr QLatin1StringView	slt = "<"_L1
static constexpr QLatin1StringView	sgt = ">"_L1
static constexpr QLatin1StringView	squot = """_L1

Detailed Description

This namespace holds QDoc-internal utility methods.

Enumeration Type Documentation

ExampleFileKind

enum class Utilities::ExampleFileKind

strong

Enumerator
File
Image

Definition at line 38 of file utilities.h.

Function Documentation

asAsciiPrintable()

QString Utilities::asAsciiPrintable

(

const QString &

str

)

Returns an ascii-printable representation of str.

Replace non-ascii-printable characters in str from a subset of such characters. The subset includes alphanumeric (alnum) characters ([a-zA-Z0-9]), space, punctuation characters, and common symbols. Non-alnum characters in this subset are replaced by a single hyphen. Leading, trailing, and consecutive hyphens are removed, such that the resulting string does not start or end with a hyphen. All characters are converted to lowercase.

If any character in str is non-latin, or latin and not found in the aforementioned subset (e.g. 'ß', 'å', or 'ö'), a hash of str is appended to the final string.

Returns a string that is normalized for use where ascii-printable strings are required, such as file names or fragment identifiers in URLs.

The implementation is equivalent to:

name.replace(QRegularExpression("[^A-Za-z0-9]+"), " ");
name = name.simplified();
name.replace(QLatin1Char(' '), QLatin1Char('-'));
name = name.toLower();

However, it has been measured to be approximately four times faster.

Definition at line 157 of file utilities.cpp.

comma()

QString Utilities::comma	(	qsizetype	wordPosition,
		qsizetype	numberOfWords )

Convenience method that's used to get the correct punctuation character for the words at wordPosition in a list of numberOfWords length.

For a list of length one, returns an empty QString. For a list of length two, returns the string " and ". For any length beyond two, returns the string ", " until the last element, which returns ", and ".

See also

comma()

Definition at line 117 of file utilities.cpp.

debugging()

bool Utilities::debugging

(

)

Definition at line 42 of file utilities.cpp.

Referenced by processQdocconfFile().

Here is the caller graph for this function:

exampleFileTitle() [1/2]

QString Utilities::exampleFileTitle ( const QString & fileName, ExampleFileKind kind )

nodiscard

Constructs a title for a file or image page in an example.

Returns the base name of fileName with the appropriate suffix based on kind: " Example File" for ExampleFileKind::File, " Image File" for ExampleFileKind::Image.

Use this overload when you already know whether the file is an example file or image (e.g., when iterating separate file/image lists).

Definition at line 390 of file utilities.cpp.

exampleFileTitle() [2/2]

QString Utilities::exampleFileTitle ( const QStringList & files, const QStringList & images, const QString & fileName )

nodiscard

Constructs a title for a file or image page in an example.

If fileName is found in files, returns the base name with " Example File" suffix. If found in images, returns the base name with " Image File" suffix. If not found in either list, returns an empty string.

Matching uses exact string equality, not basename comparison.

Note

This overload performs O(n) membership checks. When iterating known file or image lists, prefer the overload taking ExampleFileKind.

Definition at line 417 of file utilities.cpp.

frameworkSuffix()

QByteArray Utilities::frameworkSuffix ( )

static

Definition at line 270 of file utilities.cpp.

getInternalIncludePaths()

QStringList Utilities::getInternalIncludePaths

(

const QString &

compiler

)

Determine the compiler's internal include paths from the output of

\badcode [clang++|g++] -E -x c++ - -v </dev/null

Output looks like:

\badcode #include <...> search starts here: /usr/local/include /System/Library/Frameworks (framework directory) End of search list.

Definition at line 291 of file utilities.cpp.

isGeneratedFile()

bool Utilities::isGeneratedFile

(

const QString &

path

)

Definition at line 324 of file utilities.cpp.

linkForExampleFile()

QString Utilities::linkForExampleFile ( const QString & path, const QString & project, const QString & fileExt )

nodiscard

Constructs an href link from an example file name.

The path is the path to the example file. The project is the module name (used as prefix). The fileExt is the file extension for the generated link.

Definition at line 374 of file utilities.cpp.

nodeForString()

const INode * Utilities::nodeForString

(

const QString &

string

)

Converts a string representation of a pointer address to an INode pointer.

This function takes a string, assumed to contain the numerical representation of an INode pointer's address (as generated by stringForNode()), and casts it back to an INode pointer.

See also

stringForNode()

Definition at line 56 of file utilities.cpp.

pathAndFragment()

QStringList Utilities::pathAndFragment

(

const QString &

linkText

)

Returns a string list containing the path and fragment components of the given linkText.

Fragments begin with a "#" character, following HTML conventions.

Links with only a path or only a fragment will result in lists of one element. A link with both path and fragment will result in a list of two elements. Additional fragments are discarded.

Escaped "#" characters ("\\#") are interpreted differently to regular "#" characters. These can be used to represent "#" characters in titles, but not in fragments.

Definition at line 345 of file utilities.cpp.

protect()

QString Utilities::protect

(

const QString &

string

)

Definition at line 199 of file utilities.cpp.

runProcess()

bool Utilities::runProcess ( const QString & program, const QStringList & arguments, QByteArray * stdOutIn, QByteArray * stdErrIn )

static

Definition at line 229 of file utilities.cpp.

separator()

QString Utilities::separator	(	qsizetype	wordPosition,
		qsizetype	numberOfWords )

Convenience method that's used to get the correct punctuation character for the words at wordPosition in a list of numberOfWords length. For the last position in the list, returns "." (full stop). For any other word, this method calls comma().

See also

comma()

Definition at line 97 of file utilities.cpp.

setDebugEnabled()

void Utilities::setDebugEnabled ( bool value )

inlinestatic

Definition at line 24 of file utilities.cpp.

Referenced by startDebugging(), and stopDebugging().

Here is the caller graph for this function:

startDebugging()

void Utilities::startDebugging

(

const QString &

message

)

Definition at line 30 of file utilities.cpp.

References setDebugEnabled().

Here is the call graph for this function:

stopDebugging()

void Utilities::stopDebugging

(

const QString &

message

)

Definition at line 36 of file utilities.cpp.

References setDebugEnabled().

Here is the call graph for this function:

stringForNode()

QString Utilities::stringForNode

(

const INode *

node

)

Converts an INode pointer address to its string representation.

This function takes a node pointer and returns a string that contains the numerical value of its memory address. This is used for serialization or passing node references where a direct pointer cannot be used.

Note

The returned string is only valid within the same process. It does {not} persist across runs.

Definition at line 70 of file utilities.cpp.

uniqueIdentifier()

QString Utilities::uniqueIdentifier	(	const Location &	loc,
		const QString &	prefix )

Returns a unique identifier based on location loc, with a given prefix.

Definition at line 79 of file utilities.cpp.

Variable Documentation

samp

QLatin1StringView Utilities::samp = "&"_L1

staticconstexpr

Definition at line 42 of file utilities.h.

sgt

QLatin1StringView Utilities::sgt = ">"_L1

staticconstexpr

Definition at line 44 of file utilities.h.

slt

QLatin1StringView Utilities::slt = "<"_L1

staticconstexpr

Definition at line 43 of file utilities.h.

squot

QLatin1StringView Utilities::squot = """_L1

staticconstexpr

Definition at line 45 of file utilities.h.