Add str.replace() method

3 files changed, 24 insertions, 0 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'
+```