String.replace

Perform a substitution.

$find can be a Regex pattern r'...' or a String.

$replace can be a string, or callback function.

If $replace is string, it can substitute capture groups with $1, $2, etc.

If given a callback function, it will be called for every match and receive a List as its first argument. The first item in the list is the entire match. Subsequent items contain submatches captured in parens. The function should return the transformed string replacement.

// literal strings
'abc 123'.replace('123', 'xyz');
//= 'abc xyz'

// regex find
'abc 123'.replace(r'(\d+)', 'xyz');
//= 'abc xyz'

// with limit
'abcdef'.replace(r'\w', 'X', 4);
//= 'XXXXef'

// with capture group substitution
'abc 123'.replace(r'(\w+) (\d+)', '$1 | $2');
//= 'abc | 123'

// with callback
$cb = F ($m) {
    return $m[1].toUpperCase() ~ ' | ' ~ $m[2];
};
'abc 123'.replace(r'(\w+) (\d+)', $cb);
//= 'ABC | 123'