class_docstr: Namespace for string related expressions.
class_docstr_tok: ["Namespace","for","string","related","expressions","."]
docstr: Replace first matching regex/literal substring with a new string value.
  
  Parameters
  ----------
  pattern
      A valid regular expression pattern, compatible with the `regex crate
      <https://docs.rs/regex/latest/regex/>`_.
  value
      String that will replace the matched substring.
  literal
      Treat pattern as a literal string.
  n
      Number of matches to replace.
  
  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
  <https://docs.rs/regex/latest/regex/#grouping-and-flags>`_ for
  additional information about the use of inline expression modifiers.
  
  See Also
  --------
  replace_all : Replace all matching regex/literal substrings.
  
  Examples
  --------
  >>> df = pl.DataFrame({"id": [1, 2], "text": ["123abc", "abc456"]})
  >>> df.with_columns(
  ...     pl.col("text").str.replace(r"abc\b", "ABC")
  ... )  # doctest: +IGNORE_RESULT
  shape: (2, 2)
  ┌─────┬────────┐
  │ id  ┆ text   │
  │ --- ┆ ---    │
  │ i64 ┆ str    │
  ╞═════╪════════╡
  │ 1   ┆ 123ABC │
  │ 2   ┆ abc456 │
  └─────┴────────┘
docstr_tok: ["Replace","first","matching","regex\/literal","substring","with","a","new","string","value",".","Parameters","--","--","--","--","--","pattern","A","valid","regular","expression","pattern",",","compatible","with","the","`","regex","crate","<","https",":","\/\/docs.rs\/regex\/latest\/regex\/",">","`","_",".","value","String","that","will","replace","the","matched","substring",".","literal","Treat","pattern","as","a","literal","string",".","n","Number","of","matches","to","replace",".","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",")","\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510","\u2502","city","\u2506","season","\u2506","weather","\u2502","\u2502","--","-","\u2506","--","-","\u2506","--","-","\u2502","\u2502","str","\u2506","str","\u2506","str","\u2502","\u255e\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561","\u2502","Philadelphia","\u2506","Spring","\u2506","Sunny","\u2502","\u2502","Philadelphia","\u2506","Summer","\u2506","Sunny","\u2502","\u2502","Philadelphia","\u2506","Autumn","\u2506","Sunny","\u2502","\u2502","Philadelphia","\u2506","Winter","\u2506","Sunny","\u2502","\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518","See","the","regex","crate","'s","section","on","`","grouping","and","flags","<","https",":","\/\/docs.rs\/regex\/latest\/regex\/","#","grouping-and-flags",">","`","_","for","additional","information","about","the","use","of","inline","expression","modifiers",".","See","Also","--","--","--","--","replace_all",":","Replace","all","matching","regex\/literal","substrings",".","Examples","--","--","--","--",">",">",">","df","=","pl.DataFrame","(","{","``","id","''",":","[","1",",","2","]",",","``","text","''",":","[","``","123abc","''",",","``","abc456","''","]","}",")",">",">",">","df.with_columns","(","...","pl.col","(","``","text","''",")",".str.replace","(","r","''","abc\\b","''",",","``","ABC","''",")","...",")","#","doctest",":","+IGNORE_RESULT","shape",":","(","2",",","2",")","\u250c\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510","\u2502","id","\u2506","text","\u2502","\u2502","--","-","\u2506","--","-","\u2502","\u2502","i64","\u2506","str","\u2502","\u255e\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561","\u2502","1","\u2506","123ABC","\u2502","\u2502","2","\u2506","abc456","\u2502","\u2514\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518"]
code: def replace(
      self,
      pattern: str | Expr,
      value: str | Expr,
      *,
      literal: bool = False,
      n: int = 1,
  ) -> Expr:
      r"""
      Replace first matching regex/literal substring with a new string value.
  
      Parameters
      ----------
      pattern
          A valid regular expression pattern, compatible with the `regex crate
          <https://docs.rs/regex/latest/regex/>`_.
      value
          String that will replace the matched substring.
      literal
          Treat pattern as a literal string.
      n
          Number of matches to replace.
  
      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
      <https://docs.rs/regex/latest/regex/#grouping-and-flags>`_ for
      additional information about the use of inline expression modifiers.
  
      See Also
      --------
      replace_all : Replace all matching regex/literal substrings.
  
      Examples
      --------
      >>> df = pl.DataFrame({"id": [1, 2], "text": ["123abc", "abc456"]})
      >>> df.with_columns(
      ...     pl.col("text").str.replace(r"abc\b", "ABC")
      ... )  # doctest: +IGNORE_RESULT
      shape: (2, 2)
      ┌─────┬────────┐
      │ id  ┆ text   │
      │ --- ┆ ---    │
      │ i64 ┆ str    │
      ╞═════╪════════╡
      │ 1   ┆ 123ABC │
      │ 2   ┆ abc456 │
      └─────┴────────┘
  
      """
      pattern = parse_as_expression(pattern, str_as_lit=True)
      value = parse_as_expression(value, str_as_lit=True)
      return wrap_expr(
          self._pyexpr.str_replace_n(pattern, value, literal, n)
      )
  
imports: from __future__ import annotations
  import warnings
  from typing import TYPE_CHECKING
  import polars._reexport
  from polars import functions
  from polars.datatypes import Date, Datetime, Int32, Time, py_type_to_dtype
  from polars.exceptions import ChronoFormatWarning
  from polars.utils._parse_expr_input import parse_as_expression
  from polars.utils._wrap import wrap_expr
  from polars.utils.deprecation import deprecate_renamed_function, deprecate_renamed_parameter, rename_use_earliest_to_ambiguous
  from polars.utils.various import find_stacklevel
label_desc: Use image node_id 35 for calling the ExprStringNameSpace obj's underlying member method code with example usage: obj.replace(pattern, value) and returns: wrap_expr