polars.Expr.str.replace#

Expr.str.replace( pattern: str | Expr, value: str | Expr, *, literal: bool = False, n: int = 1, ) → Expr[source]#

Replace first matching regex/literal substring with a new string value.

Parameters:

pattern: A valid regular expression pattern, compatible with the regex crate.
value: String that will replace the matched substring.
literal: Treat pattern as a literal string.
n: Number of matches to replace.

See also

replace_all: Replace all matching regex/literal substrings.

Notes

To modify regular expression behaviour (such as case-sensitivity) with flags, use the inline (?iLmsuxU) syntax. For example:

>>> df = pl.DataFrame(
...     {
...         "city": "Philadelphia",
...         "season": ["Spring", "Summer", "Autumn", "Winter"],
...         "weather": ["Rainy", "Sunny", "Cloudy", "Snowy"],
...     }
... )
>>> df.with_columns(
...     # apply case-insensitive string replacement
...     pl.col("weather").str.replace(r"(?i)foggy|rainy|cloudy|snowy", "Sunny")
... )
shape: (4, 3)
┌──────────────┬────────┬─────────┐
│ city         ┆ season ┆ weather │
│ ---          ┆ ---    ┆ ---     │
│ str          ┆ str    ┆ str     │
╞══════════════╪════════╪═════════╡
│ Philadelphia ┆ Spring ┆ Sunny   │
│ Philadelphia ┆ Summer ┆ Sunny   │
│ Philadelphia ┆ Autumn ┆ Sunny   │
│ Philadelphia ┆ Winter ┆ Sunny   │
└──────────────┴────────┴─────────┘

See the regex crate’s section on grouping and flags for additional information about the use of inline expression modifiers.

Examples

>>> df = pl.DataFrame({"id": [1, 2], "text": ["123abc", "abc456"]})
>>> df.with_columns(
...     pl.col("text").str.replace(r"abc\b", "ABC")
... )  
shape: (2, 2)
┌─────┬────────┐
│ id  ┆ text   │
│ --- ┆ ---    │
│ i64 ┆ str    │
╞═════╪════════╡
│ 1   ┆ 123ABC │
│ 2   ┆ abc456 │
└─────┴────────┘