5 files changed, 36 insertions, 1 deletions
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 83eba89..47e1afd 100644
--- a/docs/markdown/Reference-manual.md
+++ b/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.
diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md
index 30682bd..5579855 100644
--- a/docs/markdown/Syntax.md
+++ b/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
diff --git a/docs/markdown/snippets/string_replace.md b/docs/markdown/snippets/string_replace.md
new file mode 100644
index 0000000..e88179d
--- /dev/null
+++ b/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'
+```
diff --git a/mesonbuild/interpreterbase.py b/mesonbuild/interpreterbase.py
index aba9ed4..026eaf2 100644
--- a/mesonbuild/interpreterbase.py
+++ b/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:
diff --git a/test cases/common/36 string operations/meson.build b/test cases/common/36 string operations/meson.build
index 8a06a82..ca0342d 100644
--- a/test cases/common/36 string operations/meson.build
+++ b/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.')
@@ -71,7 +75,7 @@ assert(version_number.version_compare('<2.0'), 'Version_compare major less broke
 assert(version_number.version_compare('>0.9'), 'Version_compare major greater broken')
 
 assert(' spaces	tabs	'.strip() == 'spaces	tabs', 'Spaces and tabs badly stripped')
-assert(''' 
+assert('''
 multiline string	'''.strip() == '''multiline string''', 'Newlines badly stripped')
 assert('"1.1.20"'.strip('"') == '1.1.20', '" badly stripped')
 assert('"1.1.20"'.strip('".') == '1.1.20', '". badly stripped')