Add str.replace() method

docs/markdown/Reference-manual.md

@@ -2134,6 +2134,9 @@ are immutable, all operations return their results as a new string.
 - `join(list_of_strings)`: the opposite of split, for example
   `'.'.join(['a', 'b', 'c']` yields `'a.b.c'`.
 
+- `replace('old_substr', 'new_str')`: replaces instances of `old_substr` in the
+  string with `new_str` and returns a new string
+
 - `split(split_character)`: splits the string at the specified
   character (or whitespace if not set) and returns the parts in an
   array.

docs/markdown/Syntax.md

@@ -186,6 +186,17 @@ As can be seen, the formatting works by replacing placeholders of type
 Strings also support a number of other methods that return transformed
 copies.
 
+#### .replace()
+
+Since 0.58.0, you can replace a substring from a string.
+
+```meson
+# Replaces all instances of one substring with another
+s = 'semicolons;as;separators'
+s = s.replace('as', 'are')
+# 's' now has the value of 'semicolons;are;separators'
+```
+
 #### .strip()
 
 ```meson

docs/markdown/snippets/string_replace.md

@@ -0,0 +1,10 @@
+## String `.replace()`
+
+String objects now have a method called replace for replacing all instances of a
+substring in a string with another.
+
+```meson
+s = 'aaabbb'
+s = s.replace('aaa', 'bbb')
+# 's' is now 'bbbbbb'
+```

mesonbuild/interpreterbase.py

@@ -1192,6 +1192,13 @@ The result of this is undefined and will become a hard error in a future Meson r
                     raise InterpreterException('substring() argument must be an int')
                 end = posargs[1]
             return obj[start:end]
+        elif method_name == 'replace':
+            FeatureNew.single_use('str.replace', '0.58.0', self.subproject)
+            if len(posargs) != 2:
+                raise InterpreterException('replace() takes exactly two arguments.')
+            if not isinstance(posargs[0], str) or not isinstance(posargs[1], str):
+                raise InterpreterException('replace() requires that both arguments be strings')
+            return obj.replace(posargs[0], posargs[1])
         raise InterpreterException('Unknown method "%s" for a string.' % method_name)
 
     def format_string(self, templ: str, args: T.List[TYPE_nvar]) -> str:

test cases/common/36 string operations/meson.build

@@ -19,6 +19,10 @@ long = 'abcde'
 prefix = 'abc'
 suffix = 'cde'
 
+assert(long.replace('b', 'd') == 'adcde')
+assert(long.replace('z', 'x') == long)
+assert(long.replace(prefix, suffix) == 'cdede')
+
 assert(long.startswith(prefix), 'Prefix.')
 
 assert(not long.startswith(suffix), 'Not prefix.')