polars.Series.str.replace_many#

Series.str.replace_many(patterns: Series | list[str] | Mapping[str, str], replace_with: Series | list[str] | str | NoDefault = <no_default>, *, ascii_case_insensitive: bool = False, leftmost: bool = False) → Series[source]#

Use the Aho-Corasick algorithm to replace many matches.

Parameters:
patterns

String patterns to search and replace. Also accepts a mapping of patterns to their replacement as syntactic sugar for replace_many(pl.Series(mapping.keys()), pl.Series(mapping.values())).

replace_with

Strings to replace where a pattern was a match. Length must match the length of patterns or have length 1. This can be broadcasted, so it supports many:one and many:many.

ascii_case_insensitive

Enable ASCII-aware case-insensitive matching. When this option is enabled, searching will be performed without respect to case for ASCII letters (a-z and A-Z) only.

leftmost

Guarantees in case there are overlapping matches that the leftmost match is used. In case there are multiple candidates for the leftmost match the pattern which comes first in patterns is used.

Notes

This method supports matching on string literals only, and does not support regular expression matching.

Examples

Replace many patterns by passing lists of equal length to the patterns and replace_with parameters.

>>> _ = pl.Config.set_fmt_str_lengths(100)
>>> s = pl.Series(
...     "lyrics",
...     [
...         "Everybody wants to rule the world",
...         "Tell me what you want, what you really really want",
...         "Can you feel the love tonight",
...     ],
... )
>>> s.str.replace_many(["you", "me"], ["me", "you"])
shape: (3,)
Series: 'lyrics' [str]
[
    "Everybody wants to rule the world"
    "Tell you what me want, what me really really want"
    "Can me feel the love tonight"
]

Broadcast a replacement for many patterns by passing a sequence of length 1 to the replace_with parameter.

>>> _ = pl.Config.set_fmt_str_lengths(100)
>>> s = pl.Series(
...     "lyrics",
...     [
...         "Everybody wants to rule the world",
...         "Tell me what you want, what you really really want",
...         "Can you feel the love tonight",
...     ],
... )
>>> s.str.replace_many(["me", "you", "they"], [""])
shape: (3,)
Series: 'lyrics' [str]
[
    "Everybody wants to rule the world"
    "Tell  what  want, what  really really want"
    "Can  feel the love tonight"
]

Passing a mapping with patterns and replacements is also supported as syntactic sugar.

>>> _ = pl.Config.set_fmt_str_lengths(100)
>>> s = pl.Series(
...     "lyrics",
...     [
...         "Everybody wants to rule the world",
...         "Tell me what you want, what you really really want",
...         "Can you feel the love tonight",
...     ],
... )
>>> mapping = {"me": "you", "you": "me", "want": "need"}
>>> s.str.replace_many(mapping)
shape: (3,)
Series: 'lyrics' [str]
[
    "Everybody needs to rule the world"
    "Tell you what me need, what me really really need"
    "Can me feel the love tonight"
]

Using leftmost and changing order of tokens in patterns, you can get fine control over replacement logic, while default behavior does not provide guarantees in case of overlapping patterns:

>>> s = pl.Series("haystack", ["abcd"])
>>> patterns = {"b": "x", "abc": "y", "abcd": "z"}
>>> s.str.replace_many(patterns)
shape: (1,)
Series: 'haystack' [str]
[
    "axcd"
]

Note that here replaced can be any of axcd, yd or z.

Adding leftmost=True matches pattern with leftmost start index first:

>>> s = pl.Series("haystack", ["abcd"])
>>> patterns = {"b": "x", "abc": "y", "abcd": "z"}
>>> s.str.replace_many(patterns, leftmost=True)
shape: (1,)
Series: 'haystack' [str]
[
    "yd"
]

Changing order inside patterns to match ‘abcd’ first:

>>> s = pl.Series("haystack", ["abcd"])
>>> patterns = {"abcd": "z", "abc": "y", "b": "x"}
>>> s.str.replace_many(patterns, leftmost=True)
shape: (1,)
Series: 'haystack' [str]
[
    "z"
]