Utility functions for working with strings. More...

#include <qgsstringutils.h>

Static Public Member Functions
static QString	ampersandEncode (const QString &string)
	Makes a raw string safe for inclusion as a HTML/XML string literal.
static QString	capitalize (const QString &string, Qgis::Capitalization capitalization)
	Converts a string by applying capitalization rules to the string.
static bool	containsByWord (const QString &candidate, const QString &words, Qt::CaseSensitivity sensitivity=Qt::CaseInsensitive)
	Given a candidate string, returns `true` if the candidate contains all the individual words from another string, regardless of their order.
static QHash< QString, QString >	createUnaccentMap ()
	Generates the unaccent mapping table (auto-generated by script at build time).
static double	fuzzyScore (const QString &candidate, const QString &search)
	Tests a candidate string to see how likely it is a match for a specified search string.
static int	hammingDistance (const QString &string1, const QString &string2, bool caseSensitive=false)
	Returns the Hamming distance between two strings.
static QString	htmlToMarkdown (const QString &html)
	Convert simple HTML to markdown.
static QString	insertLinks (const QString &string, bool *foundLinks=nullptr)
	Returns a string with any URL (e.g., http(s)/ftp) and mailto: text converted to valid HTML <a ...> links.
static bool	isUrl (const QString &string)
	Returns whether the string is a URL (http,https,ftp,file).
static int	levenshteinDistance (const QString &string1, const QString &string2, bool caseSensitive=false)
	Returns the Levenshtein edit distance between two strings.
static QString	longestCommonSubstring (const QString &string1, const QString &string2, bool caseSensitive=false)
	Returns the longest common substring between two strings.
static QString	qRegExpEscape (const QString &string)
	Returns an escaped string matching the behavior of QRegExp::escape.
static QString	soundex (const QString &string)
	Returns the Soundex representation of a string.
static QString	substituteVerticalCharacters (QString string)
	Returns a string with characters having vertical representation form substituted.
static QString	truncateMiddleOfString (const QString &string, int maxLength)
	Truncates a string to the specified maximum character length.
static QString	unaccent (const QString &input)
	Removes accents and other diacritical marks from a string, replacing accented characters with their unaccented ASCII equivalents.
static QString	wordWrap (const QString &string, int length, bool useMaxLineLength=true, const QString &customDelimiter=QString())
	Automatically wraps a string by inserting new line characters at appropriate locations in the string.

Static Public Attributes
static QHash< QString, QString >	UNACCENT_MAP = QgsStringUtils::createUnaccentMap()
	Lookup table used by unaccent().

Detailed Description

Utility functions for working with strings.

Definition at line 180 of file qgsstringutils.h.

Member Function Documentation

◆ ampersandEncode()

QString QgsStringUtils::ampersandEncode ( const QString & string )

static

Makes a raw string safe for inclusion as a HTML/XML string literal.

This includes replacing '<' with '<', '>' with '>', '&' with '&amp', and any extended unicode characters with the XML style é encoded versions of these characters.

Since: QGIS 3.2

Definition at line 159 of file qgsstringutils.cpp.

◆ capitalize()

QString QgsStringUtils::capitalize	(	const QString &	string,
		Qgis::Capitalization	capitalization )

static

Converts a string by applying capitalization rules to the string.

Parameters

string	input string
capitalization	capitalization type to apply

Returns: capitalized string

Definition at line 69 of file qgsstringutils.cpp.

◆ containsByWord()

bool QgsStringUtils::containsByWord	(	const QString &	candidate,
		const QString &	words,
		Qt::CaseSensitivity	sensitivity = Qt::CaseInsensitive )

static

Given a candidate string, returns true if the candidate contains all the individual words from another string, regardless of their order.

Note: The search does NOT need to match whole words in the candidate string, so eg a candidate string of "Worldmap_Winkel_II" will return true for words "winkle world"

Since: QGIS 3.42

Definition at line 789 of file qgsstringutils.cpp.

◆ createUnaccentMap()

QHash< QString, QString > QgsStringUtils::createUnaccentMap ( )

static

Generates the unaccent mapping table (auto-generated by script at build time).

This function creates a hash map from the unaccent rules file (resources/unaccent.rules), which is derived from PostgreSQL's contrib/unaccent module.

Note: This function is called automatically during static initialization and should not need to be called directly by users.

Since: QGIS 4.0

Definition at line 35 of file qgsunaccentrules.cpp.

◆ fuzzyScore()

double QgsStringUtils::fuzzyScore	(	const QString &	candidate,
		const QString &	search )

static

Tests a candidate string to see how likely it is a match for a specified search string.

Values are normalized between 0 and 1.

Parameters

candidate	candidate string
search	search term string

Returns: Normalized value of how likely is the search to be in the candidate

Note: Use this function only to calculate the fuzzy score between two strings and later compare these values, but do not depend on the actual numbers. They are implementation detail that may change in a future release.

Since: QGIS 3.14

Definition at line 458 of file qgsstringutils.cpp.

◆ hammingDistance()

int QgsStringUtils::hammingDistance	(	const QString &	string1,
		const QString &	string2,
		bool	caseSensitive = false )

static

Returns the Hamming distance between two strings.

This equates to the number of characters at corresponding positions within the input strings where the characters are different. The input strings must be the same length.

Parameters

string1	first string
string2	second string
caseSensitive	set to `true` for case sensitive comparison

Returns: Hamming distance between strings, or -1 if strings are different lengths.

Definition at line 323 of file qgsstringutils.cpp.

◆ htmlToMarkdown()

QString QgsStringUtils::htmlToMarkdown ( const QString & html )

static

Convert simple HTML to markdown.

Only br, b and link are supported.

Parameters

html	HTML to convert to markdown

Returns: String formatted as markdown

Since: QGIS 3.10

Definition at line 614 of file qgsstringutils.cpp.

◆ insertLinks()

QString QgsStringUtils::insertLinks	(	const QString &	string,
		bool *	foundLinks = nullptr )

static

Returns a string with any URL (e.g., http(s)/ftp) and mailto: text converted to valid HTML <a ...> links.

Parameters

string	string to insert links into
foundLinks	if specified, will be set to `true` if any links were inserted into the string

Returns: string with inserted links

Definition at line 562 of file qgsstringutils.cpp.

◆ isUrl()

bool QgsStringUtils::isUrl ( const QString & string )

static

Returns whether the string is a URL (http,https,ftp,file).

Parameters

string the string to check

Returns: whether the string is an URL

Since: QGIS 3.22

Definition at line 608 of file qgsstringutils.cpp.

◆ levenshteinDistance()

int QgsStringUtils::levenshteinDistance	(	const QString &	string1,
		const QString &	string2,
		bool	caseSensitive = false )

static

Returns the Levenshtein edit distance between two strings.

This equates to the minimum number of character edits (insertions, deletions or substitutions) required to change one string to another.

Parameters

string1	first string
string2	second string
caseSensitive	set to `true` for case sensitive comparison

Returns: edit distance. Lower distances indicate more similar strings.

Definition at line 179 of file qgsstringutils.cpp.

◆ longestCommonSubstring()

QString QgsStringUtils::longestCommonSubstring	(	const QString &	string1,
		const QString &	string2,
		bool	caseSensitive = false )

static

Returns the longest common substring between two strings.

This substring is the longest string that is a substring of the two input strings. For example, the longest common substring of "ABABC" and "BABCA" is "ABC".

Parameters

string1	first string
string2	second string
caseSensitive	set to `true` for case sensitive comparison

Returns: longest common substring

Definition at line 260 of file qgsstringutils.cpp.

◆ qRegExpEscape()

QString QgsStringUtils::qRegExpEscape ( const QString & string )

static

Returns an escaped string matching the behavior of QRegExp::escape.

Parameters

string String to escape

Returns: Escaped string

Since: QGIS 3.22

Definition at line 742 of file qgsstringutils.cpp.

◆ soundex()

QString QgsStringUtils::soundex ( const QString & string )

static

Returns the Soundex representation of a string.

Soundex is a phonetic matching algorithm, so strings with similar sounds should be represented by the same Soundex code.

Parameters

string input string

Returns: 4 letter Soundex code

Definition at line 362 of file qgsstringutils.cpp.

◆ substituteVerticalCharacters()

QString QgsStringUtils::substituteVerticalCharacters ( QString string )

static

Returns a string with characters having vertical representation form substituted.

Parameters

string input string

Returns: string with substitution applied

Since: QGIS 3.10

Definition at line 720 of file qgsstringutils.cpp.

◆ truncateMiddleOfString()

QString QgsStringUtils::truncateMiddleOfString	(	const QString &	string,
		int	maxLength )

static

Truncates a string to the specified maximum character length.

If the string exceeds the maximum character length, then the string will be truncated by removing characters from the middle of the string and replacing them with a horizontal ellipsis character.

Since: QGIS 3.22

Definition at line 775 of file qgsstringutils.cpp.

◆ unaccent()

QString QgsStringUtils::unaccent ( const QString & input )

static

Removes accents and other diacritical marks from a string, replacing accented characters with their unaccented ASCII equivalents.

This function uses a comprehensive mapping table derived from PostgreSQL's contrib/unaccent module, ensuring compatibility with PostgreSQL's unaccent() function. The implementation:

Normalizes input to Unicode NFC (Canonical Composition) form
Maps accented characters to their base forms (é→e, ñ→n, etc.)
Handles ligatures (Æ→AE, œ→oe, ß→ss, etc.)
Processes compatibility characters (℃→°C, ½→ 1/2, etc.)
Supports both BMP and non-BMP (surrogate pair) Unicode characters
Preserves characters without mappings unchanged

Common use cases:

Normalizing text for search and comparison operations
Creating ASCII-safe identifiers or filenames from international text
Matching user input regardless of accent usage
Preparing text for systems that don't support Unicode well

Parameters

input string to remove accents from

Returns: string with accents and diacritical marks removed

Example usage:

QgsStringUtils::unaccent("crème brûlée") // returns "creme brulee"

QgsStringUtils::unaccent

static QString unaccent(const QString &input)

Removes accents and other diacritical marks from a string, replacing accented characters with their u...

Definition qgsstringutils.cpp:29

Note: This function is also available as an expression function unaccent() for use in QGIS expressions, field calculator, and labeling.

See also: QgsExpression for using this function in expressions

Since: QGIS 4.0

Definition at line 29 of file qgsstringutils.cpp.

◆ wordWrap()

QString QgsStringUtils::wordWrap	(	const QString &	string,
		int	length,
		bool	useMaxLineLength = true,
		const QString &	customDelimiter = QString() )

static

Automatically wraps a string by inserting new line characters at appropriate locations in the string.

The length argument specifies either the minimum or maximum length of lines desired, depending on whether useMaxLineLength is true. If useMaxLineLength is TRUE, then the string will be wrapped so that each line ideally will not exceed length of characters. If useMaxLineLength is false, then the string will be wrapped so that each line will ideally exceed length of characters.

A custom delimiter can be specified to use instead of space characters.

Since: QGIS 3.4

Definition at line 642 of file qgsstringutils.cpp.

Member Data Documentation

◆ UNACCENT_MAP

QHash< QString, QString > QgsStringUtils::UNACCENT_MAP = QgsStringUtils::createUnaccentMap()

static

Lookup table used by unaccent().

Generated at build time from PostgreSQL's unaccent rules.

This hash map contains mappings from accented/special characters to their ASCII equivalents. The table includes:

Diacritical marks (é→e, ñ→n, ü→u, etc.)
Ligatures (Æ→AE, œ→oe, etc.)
Special letters (ß→ss, ł→l, etc.)
Compatibility characters (℃→°C, ℗→(P), etc.)
Full-width characters (＃→#, etc.)

Definition at line 359 of file qgsstringutils.h.

The documentation for this class was generated from the following files:

/build/qgis-3.99.0+git20260124+a8882ad4560+99sid/src/core/qgsstringutils.h
/build/qgis-3.99.0+git20260124+a8882ad4560+99sid/src/core/qgsstringutils.cpp
/build/qgis-3.99.0+git20260124+a8882ad4560+99sid/src/core/qgsunaccentrules.cpp

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ ampersandEncode()

◆ capitalize()

◆ containsByWord()

◆ createUnaccentMap()

◆ fuzzyScore()

◆ hammingDistance()

◆ htmlToMarkdown()

◆ insertLinks()

◆ isUrl()

◆ levenshteinDistance()

◆ longestCommonSubstring()

◆ qRegExpEscape()

◆ soundex()

◆ substituteVerticalCharacters()

◆ truncateMiddleOfString()

◆ unaccent()

◆ wordWrap()

Member Data Documentation

◆ UNACCENT_MAP