Update str replace docs (#3582)

py-polars/polars/internals/expr.py

@@ -4647,6 +4647,10 @@ def replace(self, pattern: str, value: str) -> Expr:
         value
             Replacement string.
 
+        See Also
+        --------
+        replace_all : Replace substring on all regex pattern matches.
+
         Examples
         --------
 
@@ -4676,6 +4680,25 @@ def replace_all(self, pattern: str, value: str) -> Expr:
             Regex pattern.
         value
             Replacement string.
+
+        See Also
+        --------
+        replace : Replace first regex match with a string value.
+
+        Examples
+        --------
+        >>> df = pl.DataFrame({"id": [1, 2], "text": ["abcabc", "123a123"]})
+        >>> df.with_column(pl.col("text").str.replace_all("a", "-"))
+        shape: (2, 2)
+        ┌─────┬─────────┐
+        │ id  ┆ text    │
+        │ --- ┆ ---     │
+        │ i64 ┆ str     │
+        ╞═════╪═════════╡
+        │ 1   ┆ -bc-bc  │
+        ├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
+        │ 2   ┆ 123-123 │
+        └─────┴─────────┘
         """
         return wrap_expr(self._pyexpr.str_replace_all(pattern, value))
 

py-polars/polars/internals/series.py

@@ -4234,6 +4234,10 @@ def replace(self, pattern: str, value: str) -> Series:
         value
             Substring to replace.
 
+        See Also
+        --------
+        replace_all : Replace all regex matches with a string value.
+
         Examples
         --------
 
@@ -4259,6 +4263,21 @@ def replace_all(self, pattern: str, value: str) -> Series:
             A valid regex pattern.
         value
             Substring to replace.
+
+        See Also
+        --------
+        replace : Replace first regex match with a string value.
+
+        Examples
+        --------
+        >>> df = pl.Series(["abcabc", "123a123"])
+        >>> df.str.replace_all("a", "-")
+        shape: (2,)
+        Series: '' [str]
+        [
+            "-bc-bc"
+            "123-123"
+        ]
         """
         return wrap_s(self._s.str_replace_all(pattern, value))