replace

Return a new string in which in which the occurrences of old have been replaced with new. Instead of an old string it is also possible to use a regular expression and the new string may also be a closure which then in turn should return a new string to replace the old part with.

Optionally, the number of replacements can be restricted and may start from either left or right (Unless a regular expression is used, in which case the number of replacements can only be restricted from the left).

This function does not generate an event.

Function

str.replace(old, new, [number])

Arguments

Argument	Type	Description
old	str/regex (required)	The old substring to replace, or a regular expression to search for matches.
new	str/closure (required)	String which will replace the old substring. If a closure is used, the return value of the closure will be used to replace the old substring with (see closure arguments).
number	int (optional)	Maximum number of replacements. If not given, all occurrences of the old substring will be replaced. If negative, replacement starts at the end of the string (a negative replacement is only possible when `old` is of type `str`).

Closure Arguments

This are the arguments which are given when a closure is used for new instead of a plain string:

Argument	Description
groups `0..X`	The first arguments are all the capture groups. (Only when `old` is a regular expression)
full match	After the capture groups, the next argument will be the full match. (Only when `old` is a regular expression)
start position	Start position of the match in the original string.
end position	End position of the match in the original string.
original string	The original string. The full match thus is `original[start:end]`.

Return value

Returns a new string with all occurrences of old have been replaced with new, optionally limited by a maximum number of replacements.

Example

Example using replace():

[
    {
        // Replace all occurrences of `blue` with `black`
        'My favorite color is blue and I have a blue bicycle.'.replace('blue', 'black');
    },
    {
        // Replace the first occurrence of `white` with `black`
        'My favorite color is white and I have a white car.'.replace('white', 'black', 1);
    },
    {
        // Replace the last occurrence of `red` with `black`
        'My favorite color is red and I have a red mountainbike.'.replace('red', 'black', -1);
    }
]

Return value in JSON format

[
    "My favorite color is black and I have a black bicycle.",
    "My favorite color is black and I have a white car.",
    "My favorite color is red and I have a black mountainbike."
]

Example using replace() with a regular expression:

s = 'Iris is 8 years old, has 3 bikes and about 25 books';
s.replace(/\d+/, |m| str(int(m)+1));

Return value in JSON format

"Iris is 9 years old, has 4 bikes and about 26 books"

Example using replace() with a regular expression and capture groups:

s = 'This is an _example_!!';
s.replace(/_(\w*)_/, |a| `<strong>{a}</strong>`);

Return value in JSON format

"This is an <strong>example</strong>!!"