parameters: (
          self,
          pat: str | re.Pattern,
          repl: str | Callable,
          n: int = -1,
          case: bool | None = None,
          flags: int = 0,
          regex: bool | None = None,
      )
return_statement: return self._wrap_result(result)
docstring: r"""
          Replace each occurrence of pattern/regex in the Series/Index.
  
          Equivalent to :meth:`str.replace` or :func:`re.sub`, depending on
          the regex value.
  
          Parameters
          ----------
          pat : str or compiled regex
              String can be a character sequence or regular expression.
          repl : str or callable
              Replacement string or a callable. The callable is passed the regex
              match object and must return a replacement string to be used.
              See :func:`re.sub`.
          n : int, default -1 (all)
              Number of replacements to make from start.
          case : bool, default None
              Determines if replace is case sensitive:
  
              - 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.
  
          flags : int, default 0 (no flags)
              Regex module flags, e.g. re.IGNORECASE. Cannot be set if `pat` is a compiled
              regex.
          regex : bool, default True
              Determines if the passed-in pattern is a regular expression:
  
              - If True, assumes the passed-in pattern is a regular expression.
              - If False, treats the pattern as a literal string
              - Cannot be set to False if `pat` is a compiled regex or `repl` is
                a callable.
  
              .. versionadded:: 0.23.0
  
          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.
  
          Examples
          --------
          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 :meth:`re.sub`. NaN value(s) in the Series are
          left as is:
  
          >>> pd.Series(['foo', 'fuz', np.nan]).str.replace('f.', 'ba', regex=True)
          0    bao
          1    baz
          2    NaN
          dtype: object
  
          When `pat` is a string and `regex` is False, every `pat` is replaced with
          `repl` as with :meth:`str.replace`:
  
          >>> pd.Series(['f.o', 'fuz', np.nan]).str.replace('f.', 'ba', regex=False)
          0    bao
          1    fuz
          2    NaN
          dtype: object
  
          When `repl` is a callable, it is called on every `pat` using
          :func:`re.sub`. The callable should expect one positional argument
          (a regex object) and return a string.
  
          To get the idea:
  
          >>> pd.Series(['foo', 'fuz', np.nan]).str.replace('f', repr, regex=True)
          0    <re.Match object; span=(0, 1), match='f'>oo
          1    <re.Match object; span=(0, 1), match='f'>uz
          2                                            NaN
          dtype: object
  
          Reverse every lowercase alphabetic word:
  
          >>> repl = lambda m: m.group(0)[::-1]
          >>> ser = pd.Series(['foo 123', 'bar baz', np.nan])
          >>> ser.str.replace(r'[a-z]+', repl, regex=True)
          0    oof 123
          1    rab zab
          2        NaN
          dtype: object
  
          Using regex groups (extract second group and swap case):
  
          >>> pat = r"(?P<one>\w+) (?P<two>\w+) (?P<three>\w+)"
          >>> repl = lambda m: m.group('two').swapcase()
          >>> ser = pd.Series(['One Two Three', 'Foo Bar Baz'])
          >>> ser.str.replace(pat, repl, regex=True)
          0    tWO
          1    bAR
          dtype: object
  
          Using a compiled regex with flags
  
          >>> import re
          >>> regex_pat = re.compile(r'FUZ', flags=re.IGNORECASE)
          >>> pd.Series(['foo', 'fuz', np.nan]).str.replace(regex_pat, 'bar', regex=True)
          0    foo
          1    bar
          2    NaN
          dtype: object
docstring_summary: r"""
          Replace each occurrence of pattern/regex in the Series/Index.
docstring_tokens: r Replace each occurrence of pattern / regex in the Series / Index .
function: def replace(
          self,
          pat: str | re.Pattern,
          repl: str | Callable,
          n: int = -1,
          case: bool | None = None,
          flags: int = 0,
          regex: bool | None = None,
      ):
          r"""
          Replace each occurrence of pattern/regex in the Series/Index.
  
          Equivalent to :meth:`str.replace` or :func:`re.sub`, depending on
          the regex value.
  
          Parameters
          ----------
          pat : str or compiled regex
              String can be a character sequence or regular expression.
          repl : str or callable
              Replacement string or a callable. The callable is passed the regex
              match object and must return a replacement string to be used.
              See :func:`re.sub`.
          n : int, default -1 (all)
              Number of replacements to make from start.
          case : bool, default None
              Determines if replace is case sensitive:
  
              - 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.
  
          flags : int, default 0 (no flags)
              Regex module flags, e.g. re.IGNORECASE. Cannot be set if `pat` is a compiled
              regex.
          regex : bool, default True
              Determines if the passed-in pattern is a regular expression:
  
              - If True, assumes the passed-in pattern is a regular expression.
              - If False, treats the pattern as a literal string
              - Cannot be set to False if `pat` is a compiled regex or `repl` is
                a callable.
  
              .. versionadded:: 0.23.0
  
          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.
  
          Examples
          --------
          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 :meth:`re.sub`. NaN value(s) in the Series are
          left as is:
  
          >>> pd.Series(['foo', 'fuz', np.nan]).str.replace('f.', 'ba', regex=True)
          0    bao
          1    baz
          2    NaN
          dtype: object
  
          When `pat` is a string and `regex` is False, every `pat` is replaced with
          `repl` as with :meth:`str.replace`:
  
          >>> pd.Series(['f.o', 'fuz', np.nan]).str.replace('f.', 'ba', regex=False)
          0    bao
          1    fuz
          2    NaN
          dtype: object
  
          When `repl` is a callable, it is called on every `pat` using
          :func:`re.sub`. The callable should expect one positional argument
          (a regex object) and return a string.
  
          To get the idea:
  
          >>> pd.Series(['foo', 'fuz', np.nan]).str.replace('f', repr, regex=True)
          0    <re.Match object; span=(0, 1), match='f'>oo
          1    <re.Match object; span=(0, 1), match='f'>uz
          2                                            NaN
          dtype: object
  
          Reverse every lowercase alphabetic word:
  
          >>> repl = lambda m: m.group(0)[::-1]
          >>> ser = pd.Series(['foo 123', 'bar baz', np.nan])
          >>> ser.str.replace(r'[a-z]+', repl, regex=True)
          0    oof 123
          1    rab zab
          2        NaN
          dtype: object
  
          Using regex groups (extract second group and swap case):
  
          >>> pat = r"(?P<one>\w+) (?P<two>\w+) (?P<three>\w+)"
          >>> repl = lambda m: m.group('two').swapcase()
          >>> ser = pd.Series(['One Two Three', 'Foo Bar Baz'])
          >>> ser.str.replace(pat, repl, regex=True)
          0    tWO
          1    bAR
          dtype: object
  
          Using a compiled regex with flags
  
          >>> import re
          >>> regex_pat = re.compile(r'FUZ', flags=re.IGNORECASE)
          >>> pd.Series(['foo', 'fuz', np.nan]).str.replace(regex_pat, 'bar', regex=True)
          0    foo
          1    bar
          2    NaN
          dtype: object
          """
          if regex is None:
              if isinstance(pat, str) and any(c in pat for c in ".+*|^$?[](){}\\"):
                  # warn only in cases where regex behavior would differ from literal
                  msg = (
                      "The default value of regex will change from True to False "
                      "in a future version."
                  )
                  if len(pat) == 1:
                      msg += (
                          " In addition, single character regular expressions will "
                          "*not* be treated as literal strings when regex=True."
                      )
                  warnings.warn(msg, FutureWarning, stacklevel=3)
  
          # Check whether repl is valid (GH 13438, GH 15055)
          if not (isinstance(repl, str) or callable(repl)):
              raise TypeError("repl must be a string or callable")
  
          is_compiled_re = is_re(pat)
          if regex or regex is None:
              if is_compiled_re and (case is not None or flags != 0):
                  raise ValueError(
                      "case and flags cannot be set when pat is a compiled regex"
                  )
  
          elif is_compiled_re:
              raise ValueError(
                  "Cannot use a compiled regex as replacement pattern with regex=False"
              )
          elif callable(repl):
              raise ValueError("Cannot use a callable replacement when regex=False")
  
          # The current behavior is to treat single character patterns as literal strings,
          # even when ``regex`` is set to ``True``.
          if isinstance(pat, str) and len(pat) == 1:
              regex = False
  
          if regex is None:
              regex = True
  
          if case is None:
              case = True
  
          result = self._data.array._str_replace(
              pat, repl, n=n, case=case, flags=flags, regex=regex
          )
          return self._wrap_result(result)
function_tokens: def replace ( self , pat : str | re . Pattern , repl : str | Callable , n : int = - 1 , case : bool | None = None , flags : int = 0 , regex : bool | None = None , ) : if regex is None : if isinstance ( pat , str ) and any ( c in pat for c in ".+*|^$?[](){}\\" ) : # warn only in cases where regex behavior would differ from literal msg = ( "The default value of regex will change from True to False " "in a future version." ) if len ( pat ) == 1 : msg += ( " In addition, single character regular expressions will " "*not* be treated as literal strings when regex=True." ) warnings . warn ( msg , FutureWarning , stacklevel = 3 ) # Check whether repl is valid (GH 13438, GH 15055) if not ( isinstance ( repl , str ) or callable ( repl ) ) : raise TypeError ( "repl must be a string or callable" ) is_compiled_re = is_re ( pat ) if regex or regex is None : if is_compiled_re and ( case is not None or flags != 0 ) : raise ValueError ( "case and flags cannot be set when pat is a compiled regex" ) elif is_compiled_re : raise ValueError ( "Cannot use a compiled regex as replacement pattern with regex=False" ) elif callable ( repl ) : raise ValueError ( "Cannot use a callable replacement when regex=False" ) # The current behavior is to treat single character patterns as literal strings, # even when ``regex`` is set to ``True``. if isinstance ( pat , str ) and len ( pat ) == 1 : regex = False if regex is None : regex = True if case is None : case = True result = self . _data . array . _str_replace ( pat , repl , n = n , case = case , flags = flags , regex = regex ) return self . _wrap_result ( result )