regexpReplace()

The function "regexReplace()" provides a regex-based text replacement.

Synopsis

int regexpReplace(string searchRegExp, string &subject, string replace[, mapping|string options])

Parameter Description
searchRegExp

The regular expression to search for.
subject The subject, which is searched for the regular expression. The contents will be changed.
replace The replacement term with which searchRegExp should be replaced. It may contain $1 to $9 for groups or $0 for whole match.
options

The options applied to the replacement.

If string is used:
A string of options can be used with perl modifiers. See Qt - Regular Expression - Pattern Options for details. The default is a case sensitive search.
If mapping is used:

The default is a case insensitive search and only the first term is searched and replaced.

The following keys can be used to adjust this:

  • caseSensitive: Set Case Sensitive matching. The default is false(bool).
  • minimal: The default is false (bool). If this is set totrue the greediness of the quantifiers is inverted: *, +, ?, {m,n}, etc. become lazy, while their lazy versions (*?, +?, ??, {m,n}?, etc.) become greedy. Identical to the modifier ? below.
  • global: The default falsesearches and replaces only the first occurrence. Setting this to true will let the function search and replace all terms.

Return value

  • The function returns >=0 (Position of the match) when a match was successfully found and replaced.
  • The function returns -1 if no match was found.
  • The function returns -2 when the regular expression contains an error. Errors can be retrieved by using the function getLastError().
  • The function returns -3 when the function contains wrong arguments.

Errors

See Return values -2 and -3 above.

Details

The function "regexpReplace()" searches a string for occurrences of a given search expression and replaces the occurence with a given replacement term. The resulting string overwrites the existing string.

Possible options or modifiers for the mapping:

  • i - Instruction to ignore the case.
  • s - Use a dot (.) to match anything (can be especially relevant for newline).
  • g - Used to search and replace all. Identical to the global option above; if this is not set only the first occurrence is found and replaced.
  • m - The caret (^) and the dollar ($) metacharacters in the pattern string are allowed to match, respectively, immediately after and immediately before any newline in the subject string, as well as at the very beginning and at the very end of the subject string.
  • x - Any whitespace in the pattern string which is not escaped and outside a character class is ignored. Moreover, an unescaped sharp (#) outside a character class causes all the following characters, until the first newline (which is included), to be ignored. This can be used to increase the readability of a pattern string as well as put comments inside regular expressions; this is particularly useful if the pattern string is loaded from a file or written by the user, since in C++ code it is always possible to use the rules for string literals to put comments outside the pattern string.
  • u - The meaning of the \w, \d, etc., character classes, as well as the meaning of their counterparts (\W, \D, etc.), is changed from matching ASCII characters only to matching any character with the corresponding Unicode property. For instance, \d is changed to match any character with the Unicode Nd (decimal digit) property; \w to match any character with either the Unicode L (letter) or N (digit) property, plus underscore, and so on.
  • ? - The greediness of the quantifiers is inverted: *, +, ?, {m,n}, etc. become lazy, while their lazy versions (*?, +?, ??, {m,n}?, etc.) become greedy. Identical to the minimal option in the mapping options above.

Refer to the Qt - Regular Expression Class and perl regular expressions for further details on regular expressions, groups and modifiers.

The following examples replace "l" with "X" and show the use of mapping modifiers.

No modifier:

string subject = "hello world"; regexpReplace("[l]+", subject, "X", "");  // "heXo world"

Global modifier "g"

string subject = "hello world"; regexpReplace("[l]+", subject, "X", "g"); // "heXo worXd"

Ignore case modifier "i"

string subject = "HELLO WORlD"; regexpReplace("[l]+", subject, "x", "i"); // "HExO WORlD"

Global modifier "g" combined with ignore case modifier "i"

string subject = "HELLO WORlD"; regexpReplace("[l]+", subject, "x", "ig");// "HExO WORxD"

Inverted greediness modifier "?"

string subject = "hello world"; regexpReplace("[l]+", subject, "X", "?"); // "heXlo world"

Assignment

Regular expressions