public string replace (string str, ssize_t string_len, int start_position, string replacement, RegexMatchFlags match_options = 0) throws RegexError

Replaces all occurrences of the pattern in this with the replacement text.

Backreferences of the form '\number' or '\g<number>' in the replacement text are interpolated by the number-th captured subexpression of the match, '\g<name>' refers to the captured subexpression with the given name. '\0' refers to the complete match, but '\0' followed by a number is the octal representation of a character. To include a literal '\' in the replacement, write '\\\\'.

There are also escapes that changes the case of the following text:

  • \l: Convert to lower case the next character
  • \u: Convert to upper case the next character
  • \L: Convert to lower case till \E
  • \U: Convert to upper case till \E
  • \E: End case modification

If you do not need to use backreferences use replace_literal.

The replacement string must be UTF-8 encoded even if g_regex_raw was passed to Regex. If you want to use not UTF-8 encoded strings you can use replace_literal.

Setting start_position differs from just passing over a shortened string and setting g_regex_match_notbol in the case of a pattern that begins with any kind of lookbehind assertion, such as "\b".

Example: Regex, replace:

public int main (string[] args){
try {
string quote = "This is a simple sample.";
Regex regex = new Regex ("s[ai]mple");

// Output: ``Result: This is a XXX XXX.``
string result = regex.replace (quote, quote.length, 0, "XXX");
print ("Result: %s\n", result);
} catch (RegexError e) {
print ("Error: %s\n", e.message);
return 0;

valac --pkg glib-2.0 GLib.Regex.replace.vala



a Regex structure


the length of string, in bytes, or -1 if string is nul-terminated


starting index of the string to match, in bytes


text to replace each match with


options for the match


the string to perform matches against


a newly allocated string containing the replacements