Pandas Series: - str.replace() function

Last update on September 15 2022 12:54:57 (UTC/GMT +8 hours)

Series-str.replace() function

The str.replace() function is used to replace occurrences of pattern/regex in the Series/Index with some other string.

Syntax:

Series.str.replace(self, pat, repl, n=-1, case=None, flags=0, regex=True)

Parameters:

Name	Description	Type/Default Value	Required / Optional
pat	String can be a character sequence or regular expression. New in version 0.20.0: pat also accepts a compiled regex.	str or compiled regex	Required
repl	Replacement string or a callable. The callable is passed the regex match object and must return a replacement string to be used. New in version 0.20.0: repl also accepts a callable.	str or callable	Required
n	Number of replacements to make from start.	bool Default Value: -1 (all)	Required
case	If True, case sensitive (the default if pat is a string) Set to False for case insensitive Cannot be set if pat is a compiled regex	int Default Value: None	Required
flags	re module flags, e.g. re.IGNORECASE Cannot be set if pat is a compiled regex	int Default Value: 0 (no flags)	Required
regex	If True, assumes the passed-in pattern is a regular expression. If False, treacts the pattern as a literal string Cannot be set to False if pat is a compiled regex or repl is a callable.	bool Default Value: True	Required

Returns: Series or Index of object
A copy of the object with all matching occurrences of pat replaced by repl.

Raises: ValueError

if regex is False and repl is a callable or pat is a compiled regex
if pat is a compiled regex and case or flags is set

Notes:
When pat is a compiled regex, all flags should be included in the compiled regex. Use of case, flags, or regex=False with a compiled regex will raise an error.

Example - When pat is a string and regex is True (the default), the given pat is compiled as a regex. When repl is a string, it replaces matching regex patterns as with re.sub(). NaN value(s) in the Series are left as is:

Python-Pandas Code:

import numpy as np
import pandas as pd
pd.Series(['full', 'fog', np.nan]).str.replace('f.', 'bu', regex=True)

Output:

0    bull
1     bug
2     NaN
dtype: object

Example - When pat is a string and regex is False, every pat is replaced with repl as with str.replace():

Python-Pandas Code:

import numpy as np
import pandas as pd
pd.Series(['f.n', 'fog', np.nan]).str.replace('f.', 'bu', regex=False)

Output:

0    bun
1    fog
2    NaN
dtype: object

Example - When repl is a callable, it is called on every pat using re.sub(). The callable should expect one positional argument (a regex object) and return a string:

To get the idea:

Python-Pandas Code:

import numpy as np
import pandas as pd
pd.Series(['full', 'fog', np.nan]).str.replace('f', repr)

Output:

0    <re.Match object; span=(0, 1), match='f'>ull
1     <re.Match object; span=(0, 1), match='f'>og
2                                             NaN
dtype: object

Example - Reverse every lowercase alphabetic word:

Python-Pandas Code:

import numpy as np
import pandas as pd
repl = lambda m: m.group(0)[::-1]
pd.Series(['full 234', 'brr bzz', np.nan]).str.replace(r'[a-z]+', repl)

Output:

0    lluf 234
1     rrb zzb
2         NaN
dtype: object

Example - Using regex groups (extract second group and swap case):

Python-Pandas Code:

import numpy as np
import pandas as pd
pat = r"(?P<one>\w+) (?P<two>\w+) (?P<three>\w+)"
repl = lambda m: m.group('two').swapcase()
pd.Series(['One Two Three', 'Full Brr Bzz']).str.replace(pat, repl)

Output:

0    tWO
1    bRR
dtype: object

Example - Using regex groups (extract second group and swap case):

Python-Pandas Code:

import numpy as np
import pandas as pd
import re
regex_pat = re.compile(r'FOG', flags=re.IGNORECASE)
pd.Series(['full', 'fog', np.nan]).str.replace(regex_pat, 'brr')

Output:

0    full
1     brr
2     NaN
dtype: object

Previous: Series-str.repeat() function
Next: Series-str.rpartition() function