Class: QgsStringUtils¶

Utility functions for working with strings.

Enums

Capitalization

String capitalization options.

Static Methods

`ampersandEncode`	Makes a raw string safe for inclusion as a HTML/XML string literal.
`capitalize`	Converts a string by applying capitalization rules to the string.
`containsByWord`	Given a candidate string, returns `True` if the candidate contains all the individual words from another string, regardless of their order.
`fuzzyScore`	Tests a candidate string to see how likely it is a match for a specified search string.
`hammingDistance`	Returns the Hamming distance between two strings.
`htmlToMarkdown`	Convert simple HTML to markdown.
`insertLinks`	Returns a string with any URL (e.g., http(s)/ftp) and mailto: text converted to valid HTML <a ...> links.
`isUrl`	Returns whether the string is a URL (http,https,ftp,file)
`levenshteinDistance`	Returns the Levenshtein edit distance between two strings.
`longestCommonSubstring`	Returns the longest common substring between two strings.
`qRegExpEscape`	Returns an escaped string matching the behavior of QRegExp.escape.
`soundex`	Returns the Soundex representation of a string.
`substituteVerticalCharacters`	Returns a string with characters having vertical representation form substituted.
`truncateMiddleOfString`	Truncates a string to the specified maximum character length.
`wordWrap`	Automatically wraps a string by inserting new line characters at appropriate locations in the string.

class qgis.core.QgsStringUtils[source]¶

Bases: object

class Capitalization(*values)¶

Bases: IntEnum

String capitalization options.

Note

Prior to QGIS 3.24 this was available as QgsStringUtils.Capitalization

Added in version 3.24.

MixedCase: Mixed case, ie no change
AllUppercase: Convert all characters to uppercase
AllLowercase: Convert all characters to lowercase
ForceFirstLetterToCapital: Convert just the first letter of each word to uppercase, leave the rest untouched
SmallCaps: Mixed case small caps

Added in version 3.24.
TitleCase: Simple title case conversion - does not fully grammatically parse the text and uses simple rules only. Note that this method does not convert any characters to lowercase, it only uppercases required letters. Callers must ensure that input strings are already lowercased.
UpperCamelCase: Convert the string to upper camel case. Note that this method does not unaccent characters.
AllSmallCaps: Force all characters to small caps

Added in version 3.24.

static ampersandEncode(string: str | None) → str[source]¶

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.

Added in version 3.2.

Parameters:: string (Optional[str])
Return type:: str

static capitalize(string: str | None, capitalization: Qgis.Capitalization) → str[source]¶

Converts a string by applying capitalization rules to the string.

Parameters:

string (Optional[str]) – input string
capitalization (Qgis.Capitalization) – capitalization type to apply

Return type:

str

Returns:

capitalized string

static containsByWord(candidate: str | None, words: str | None, sensitivity: Qt.CaseSensitivity = Qt.CaseInsensitive) → bool[source]¶

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”

Added in version 3.42.

Parameters:

candidate (Optional[str])
words (Optional[str])
sensitivity (Qt.CaseSensitivity = Qt.CaseInsensitive)

Return type:

bool

static fuzzyScore(candidate: str | None, search: str | None) → float[source]¶

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 (Optional[str]) – candidate string
search (Optional[str]) – search term string

Return type:

float

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.

Added in version 3.14.

static hammingDistance(string1: str | None, string2: str | None, caseSensitive: bool = False) → int[source]¶

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 (Optional[str]) – first string
string2 (Optional[str]) – second string
caseSensitive (bool = False) – set to True for case sensitive comparison

Return type:

int

Returns:

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

static htmlToMarkdown(html: str | None) → str[source]¶

Convert simple HTML to markdown. Only br, b and link are supported.

Parameters:: html (Optional[str]) – HTML to convert to markdown
Return type:: str
Returns:: String formatted as markdown

Added in version 3.10.

static insertLinks(string: str | None)[source]¶

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

Parameters:

string (Optional[str]) -> (str) – 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

static isUrl(string: str | None) → bool[source]¶

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

Parameters:: string (Optional[str]) – the string to check
Return type:: bool
Returns:: whether the string is an URL

Added in version 3.22.

static levenshteinDistance(string1: str | None, string2: str | None, caseSensitive: bool = False) → int[source]¶

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 (Optional[str]) – first string
string2 (Optional[str]) – second string
caseSensitive (bool = False) – set to True for case sensitive comparison

Return type:

int

Returns:

edit distance. Lower distances indicate more similar strings.

static longestCommonSubstring(string1: str | None, string2: str | None, caseSensitive: bool = False) → str[source]¶

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 (Optional[str]) – first string
string2 (Optional[str]) – second string
caseSensitive (bool = False) – set to True for case sensitive comparison

Return type:

str

Returns:

longest common substring

static qRegExpEscape(string: str | None) → str[source]¶

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

Parameters:: string (Optional[str]) – String to escape
Return type:: str
Returns:: Escaped string

Added in version 3.22.

static soundex(string: str | None) → str[source]¶

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 (Optional[str]) – input string
Return type:: str
Returns:: 4 letter Soundex code

static substituteVerticalCharacters(string: str | None) → str[source]¶

Returns a string with characters having vertical representation form substituted.

Parameters:: string (Optional[str]) – input string
Return type:: str
Returns:: string with substitution applied

Added in version 3.10.

static truncateMiddleOfString(string: str | None, maxLength: int) → str[source]¶

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.

Added in version 3.22.

Parameters:

string (Optional[str])
maxLength (int)

Return type:

str

static wordWrap(string: str | None, length: int, useMaxLineLength: bool = True, customDelimiter: str | None = '') → str[source]¶

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.

Added in version 3.4.

Parameters:

string (Optional[str])
length (int)
useMaxLineLength (bool = True)
customDelimiter (Optional[str] = '')

Return type:

str