polars-runtime-compat 1.34.0b3__cp39-abi3-win_arm64.whl → 1.34.0b5__cp39-abi3-win_arm64.whl

polars/series/string.py

@@ -1,2367 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-import polars._reexport as pl
-import polars.functions as F
-from polars._utils.deprecation import deprecate_nonkeyword_arguments, deprecated
-from polars._utils.unstable import unstable
-from polars._utils.various import no_default
-from polars._utils.wrap import wrap_s
-from polars.datatypes import Int64
-from polars.datatypes.classes import Datetime
-from polars.datatypes.constants import N_INFER_DEFAULT
-from polars.series.utils import expr_dispatch
-
-if TYPE_CHECKING:
-    import sys
-    from collections.abc import Mapping
-
-    from polars import Expr, Series
-    from polars._plr import PySeries
-    from polars._typing import (
-        Ambiguous,
-        IntoExpr,
-        IntoExprColumn,
-        PolarsDataType,
-        PolarsIntegerType,
-        PolarsTemporalType,
-        TimeUnit,
-        TransferEncoding,
-        UnicodeForm,
-    )
-    from polars._utils.various import NoDefault
-
-    if sys.version_info >= (3, 13):
-        from warnings import deprecated
-    else:
-        from typing_extensions import deprecated  # noqa: TC004
-
-
-@expr_dispatch
-class StringNameSpace:
-    """Series.str namespace."""
-
-    _accessor = "str"
-
-    def __init__(self, series: Series) -> None:
-        self._s: PySeries = series._s
-
-    def to_date(
-        self,
-        format: str | None = None,
-        *,
-        strict: bool = True,
-        exact: bool = True,
-        cache: bool = True,
-    ) -> Series:
-        """
-        Convert a String column into a Date column.
-
-        Parameters
-        ----------
-        format
-            Format to use for conversion. Refer to the `chrono crate documentation
-            <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>`_
-            for the full specification. Example: `"%Y-%m-%d"`.
-            If set to None (default), the format is inferred from the data.
-        strict
-            Raise an error if any conversion fails.
-        exact
-            Require an exact format match. If False, allow the format to match anywhere
-            in the target string.
-
-            .. note::
-                Using `exact=False` introduces a performance penalty - cleaning your
-                data beforehand will almost certainly be more performant.
-        cache
-            Use a cache of unique, converted dates to apply the conversion.
-
-        Examples
-        --------
-        >>> s = pl.Series(["2020/01/01", "2020/02/01", "2020/03/01"])
-        >>> s.str.to_date()
-        shape: (3,)
-        Series: '' [date]
-        [
-                2020-01-01
-                2020-02-01
-                2020-03-01
-        ]
-        """
-
-    def to_datetime(
-        self,
-        format: str | None = None,
-        *,
-        time_unit: TimeUnit | None = None,
-        time_zone: str | None = None,
-        strict: bool = True,
-        exact: bool = True,
-        cache: bool = True,
-        ambiguous: Ambiguous | pl.Series = "raise",
-    ) -> pl.Series:
-        """
-        Convert a String column into a Datetime column.
-
-        Parameters
-        ----------
-        format
-            Format to use for conversion. Refer to the `chrono crate documentation
-            <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>`_
-            for the full specification. Example: `"%Y-%m-%d %H:%M:%S"`.
-            If set to None (default), the format is inferred from the data.
-        time_unit : {None, 'us', 'ns', 'ms'}
-            Unit of time for the resulting Datetime column. If set to None (default),
-            the time unit is inferred from the format string if given, eg:
-            `"%F %T%.3f"` => `Datetime("ms")`. If no fractional second component is
-            found, the default is `"us"`.
-        time_zone
-            Time zone for the resulting Datetime column. Rules are:
-
-            - If inputs are tz-naive and `time_zone` is None, the result time zone is
-              `None`.
-            - If inputs are offset-aware and `time_zone` is None, inputs are converted
-              to `'UTC'` and the result time zone is `'UTC'`.
-            - If inputs are offset-aware and `time_zone` is given, inputs are converted
-              to `time_zone` and the result time zone is `time_zone`.
-            - If inputs are tz-naive and `time_zone` is given, input time zones are
-              replaced with (not converted to!) `time_zone`, and the result time zone
-              is `time_zone`.
-        strict
-            Raise an error if any conversion fails.
-        exact
-            Require an exact format match. If False, allow the format to match anywhere
-            in the target string.
-
-            .. note::
-                Using `exact=False` introduces a performance penalty - cleaning your
-                data beforehand will almost certainly be more performant.
-        cache
-            Use a cache of unique, converted datetimes to apply the conversion.
-        ambiguous
-            Determine how to deal with ambiguous datetimes:
-
-            - `'raise'` (default): raise
-            - `'earliest'`: use the earliest datetime
-            - `'latest'`: use the latest datetime
-            - `'null'`: set to null
-
-        Examples
-        --------
-        >>> s = pl.Series(["2020-01-01 01:00Z", "2020-01-01 02:00Z"])
-        >>> s.str.to_datetime("%Y-%m-%d %H:%M%#z")
-        shape: (2,)
-        Series: '' [datetime[μs, UTC]]
-        [
-                2020-01-01 01:00:00 UTC
-                2020-01-01 02:00:00 UTC
-        ]
-        """
-        if format is None and time_zone is None:
-            if isinstance(ambiguous, str):
-                ambiguous_s = pl.Series([ambiguous])
-            else:
-                ambiguous_s = ambiguous
-
-            return wrap_s(
-                self._s.str_to_datetime_infer(
-                    time_unit,
-                    strict,
-                    exact,
-                    ambiguous_s._s,
-                )
-            )
-        else:
-            ambiguous_expr = F.lit(ambiguous)
-            s = wrap_s(self._s)
-            return (
-                s.to_frame()
-                .select_seq(
-                    F.col(s.name).str.to_datetime(
-                        format,
-                        time_unit=time_unit,
-                        time_zone=time_zone,
-                        strict=strict,
-                        exact=exact,
-                        cache=cache,
-                        ambiguous=ambiguous_expr,
-                    )
-                )
-                .to_series()
-            )
-
-    def to_time(
-        self,
-        format: str | None = None,
-        *,
-        strict: bool = True,
-        cache: bool = True,
-    ) -> Series:
-        """
-        Convert a String column into a Time column.
-
-        Parameters
-        ----------
-        format
-            Format to use for conversion. Refer to the `chrono crate documentation
-            <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>`_
-            for the full specification. Example: `"%H:%M:%S"`.
-            If set to None (default), the format is inferred from the data.
-        strict
-            Raise an error if any conversion fails.
-        cache
-            Use a cache of unique, converted times to apply the conversion.
-
-        Examples
-        --------
-        >>> s = pl.Series(["01:00", "02:00", "03:00"])
-        >>> s.str.to_time("%H:%M")
-        shape: (3,)
-        Series: '' [time]
-        [
-                01:00:00
-                02:00:00
-                03:00:00
-        ]
-        """
-
-    def strptime(
-        self,
-        dtype: PolarsTemporalType,
-        format: str | None = None,
-        *,
-        strict: bool = True,
-        exact: bool = True,
-        cache: bool = True,
-        ambiguous: Ambiguous | Series = "raise",
-    ) -> Series:
-        """
-        Convert a String column into a Date/Datetime/Time column.
-
-        Parameters
-        ----------
-        dtype
-            The data type to convert to. Can be either Date, Datetime, or Time.
-        format
-            Format to use for conversion. Refer to the `chrono crate documentation
-            <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>`_
-            for the full specification. Example: `"%Y-%m-%d %H:%M:%S"`.
-            If set to None (default), the format is inferred from the data.
-        strict
-            Raise an error if any conversion fails.
-        exact
-            Require an exact format match. If False, allow the format to match anywhere
-            in the target string. Conversion to the Time type is always exact.
-
-            .. note::
-                Using `exact=False` introduces a performance penalty - cleaning your
-                data beforehand will almost certainly be more performant.
-        cache
-            Use a cache of unique, converted dates to apply the datetime conversion.
-        ambiguous
-            Determine how to deal with ambiguous datetimes:
-
-            - `'raise'` (default): raise
-            - `'earliest'`: use the earliest datetime
-            - `'latest'`: use the latest datetime
-            - `'null'`: set to null
-
-        Notes
-        -----
-        When converting to a Datetime type, the time unit is inferred from the format
-        string if given, eg: `"%F %T%.3f"` => `Datetime("ms")`. If no fractional
-        second component is found, the default is `"us"`.
-
-        Examples
-        --------
-        Dealing with a consistent format:
-
-        >>> s = pl.Series(["2020-01-01 01:00Z", "2020-01-01 02:00Z"])
-        >>> s.str.strptime(pl.Datetime, "%Y-%m-%d %H:%M%#z")
-        shape: (2,)
-        Series: '' [datetime[μs, UTC]]
-        [
-                2020-01-01 01:00:00 UTC
-                2020-01-01 02:00:00 UTC
-        ]
-
-        Dealing with different formats.
-
-        >>> s = pl.Series(
-        ...     "date",
-        ...     [
-        ...         "2021-04-22",
-        ...         "2022-01-04 00:00:00",
-        ...         "01/31/22",
-        ...         "Sun Jul  8 00:34:60 2001",
-        ...     ],
-        ... )
-        >>> s.to_frame().select(
-        ...     pl.coalesce(
-        ...         pl.col("date").str.strptime(pl.Date, "%F", strict=False),
-        ...         pl.col("date").str.strptime(pl.Date, "%F %T", strict=False),
-        ...         pl.col("date").str.strptime(pl.Date, "%D", strict=False),
-        ...         pl.col("date").str.strptime(pl.Date, "%c", strict=False),
-        ...     )
-        ... ).to_series()
-        shape: (4,)
-        Series: 'date' [date]
-        [
-                2021-04-22
-                2022-01-04
-                2022-01-31
-                2001-07-08
-        ]
-        """
-        if format is None and (
-            dtype is Datetime
-            or (isinstance(dtype, Datetime) and dtype.time_zone is None)
-        ):
-            time_unit = None
-            if isinstance(dtype, Datetime):
-                time_unit = dtype.time_unit
-
-            return self.to_datetime(
-                time_unit=time_unit,
-                strict=strict,
-                exact=exact,
-                cache=cache,
-                ambiguous=ambiguous,
-            )
-        else:
-            ambiguous_expr = F.lit(ambiguous)
-            s = wrap_s(self._s)
-            return (
-                s.to_frame()
-                .select_seq(
-                    F.col(s.name).str.strptime(
-                        dtype,
-                        format,
-                        strict=strict,
-                        exact=exact,
-                        cache=cache,
-                        ambiguous=ambiguous_expr,
-                    )
-                )
-                .to_series()
-            )
-
-    @deprecate_nonkeyword_arguments(allowed_args=["self"], version="1.20.0")
-    def to_decimal(
-        self,
-        inference_length: int = 100,
-        *,
-        scale: int | None = None,
-    ) -> Series:
-        """
-        Convert a String column into a Decimal column.
-
-        This method infers the needed parameters `precision` and `scale` if not
-        given.
-
-        .. versionchanged:: 1.20.0
-            Parameter `inference_length` should now be passed as a keyword argument.
-
-        Parameters
-        ----------
-        inference_length
-            Number of elements to parse to determine the `precision` and `scale`
-        scale
-            Number of digits after the comma to use for the decimals.
-
-        Examples
-        --------
-        >>> s = pl.Series(
-        ...     ["40.12", "3420.13", "120134.19", "3212.98", "12.90", "143.09", "143.9"]
-        ... )
-        >>> s.str.to_decimal()
-        shape: (7,)
-        Series: '' [decimal[8,2]]
-        [
-            40.12
-            3420.13
-            120134.19
-            3212.98
-            12.90
-            143.09
-            143.90
-        ]
-        """
-        if scale is not None:
-            s = wrap_s(self._s)
-            return (
-                s.to_frame()
-                .select_seq(F.col(s.name).str.to_decimal(scale=scale))
-                .to_series()
-            )
-        else:
-            return wrap_s(
-                self._s.str_to_decimal_infer(inference_length=inference_length)
-            )
-
-    def len_bytes(self) -> Series:
-        """
-        Return the length of each string as the number of bytes.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`UInt32`.
-
-        See Also
-        --------
-        len_chars
-
-        Notes
-        -----
-        When working with non-ASCII text, the length in bytes is not the same as the
-        length in characters. You may want to use :func:`len_chars` instead.
-        Note that :func:`len_bytes` is much more performant (_O(1)_) than
-        :func:`len_chars` (_O(n)_).
-
-        Examples
-        --------
-        >>> s = pl.Series(["Café", "345", "東京", None])
-        >>> s.str.len_bytes()
-        shape: (4,)
-        Series: '' [u32]
-        [
-            5
-            3
-            6
-            null
-        ]
-        """
-
-    def len_chars(self) -> Series:
-        """
-        Return the length of each string as the number of characters.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`UInt32`.
-
-        See Also
-        --------
-        len_bytes
-
-        Notes
-        -----
-        When working with ASCII text, use :func:`len_bytes` instead to achieve
-        equivalent output with much better performance:
-        :func:`len_bytes` runs in _O(1)_, while :func:`len_chars` runs in (_O(n)_).
-
-        A character is defined as a `Unicode scalar value`_. A single character is
-        represented by a single byte when working with ASCII text, and a maximum of
-        4 bytes otherwise.
-
-        .. _Unicode scalar value: https://www.unicode.org/glossary/#unicode_scalar_value
-
-        Examples
-        --------
-        >>> s = pl.Series(["Café", "345", "東京", None])
-        >>> s.str.len_chars()
-        shape: (4,)
-        Series: '' [u32]
-        [
-            4
-            3
-            2
-            null
-        ]
-        """
-
-    def contains(
-        self, pattern: str | Expr, *, literal: bool = False, strict: bool = True
-    ) -> Series:
-        """
-        Check if the string contains a substring that matches a pattern.
-
-        Parameters
-        ----------
-        pattern
-            A valid regular expression pattern, compatible with the `regex crate
-            <https://docs.rs/regex/latest/regex/>`_.
-        literal
-            Treat `pattern` as a literal string, not as a regular expression.
-        strict
-            Raise an error if the underlying pattern is not a valid regex,
-            otherwise mask out with a null value.
-
-        Notes
-        -----
-        To modify regular expression behaviour (such as case-sensitivity) with
-        flags, use the inline `(?iLmsuxU)` syntax. For example:
-
-        Default (case-sensitive) match:
-
-        >>> s = pl.Series("s", ["AAA", "aAa", "aaa"])
-        >>> s.str.contains("AA").to_list()
-        [True, False, False]
-
-        Case-insensitive match, using an inline flag:
-
-        >>> s = pl.Series("s", ["AAA", "aAa", "aaa"])
-        >>> s.str.contains("(?i)AA").to_list()
-        [True, True, True]
-
-        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.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`Boolean`.
-
-        Examples
-        --------
-        >>> s = pl.Series(["Crab", "cat and dog", "rab$bit", None])
-        >>> s.str.contains("cat|bit")
-        shape: (4,)
-        Series: '' [bool]
-        [
-            false
-            true
-            true
-            null
-        ]
-        >>> s.str.contains("rab$", literal=True)
-        shape: (4,)
-        Series: '' [bool]
-        [
-            false
-            false
-            true
-            null
-        ]
-        """
-
-    def find(
-        self, pattern: str | Expr, *, literal: bool = False, strict: bool = True
-    ) -> Series:
-        """
-        Return the bytes offset of the first substring matching a pattern.
-
-        If the pattern is not found, returns None.
-
-        Parameters
-        ----------
-        pattern
-            A valid regular expression pattern, compatible with the `regex crate
-            <https://docs.rs/regex/latest/regex/>`_.
-        literal
-            Treat `pattern` as a literal string, not as a regular expression.
-        strict
-            Raise an error if the underlying pattern is not a valid regex,
-            otherwise mask out with a null value.
-
-        Notes
-        -----
-        To modify regular expression behaviour (such as case-sensitivity) with
-        flags, use the inline `(?iLmsuxU)` syntax. For example:
-
-        >>> s = pl.Series("s", ["AAA", "aAa", "aaa"])
-
-        Default (case-sensitive) match:
-
-        >>> s.str.find("Aa").to_list()
-        [None, 1, None]
-
-        Case-insensitive match, using an inline flag:
-
-        >>> s.str.find("(?i)Aa").to_list()
-        [0, 0, 0]
-
-        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
-        --------
-        contains : Check if the string contains a substring that matches a pattern.
-
-        Examples
-        --------
-        >>> s = pl.Series("txt", ["Crab", "Lobster", None, "Crustacean"])
-
-        Find the index of the first substring matching a regex pattern:
-
-        >>> s.str.find("a|e").rename("idx_rx")
-        shape: (4,)
-        Series: 'idx_rx' [u32]
-        [
-            2
-            5
-            null
-            5
-        ]
-
-        Find the index of the first substring matching a literal pattern:
-
-        >>> s.str.find("e", literal=True).rename("idx_lit")
-        shape: (4,)
-        Series: 'idx_lit' [u32]
-        [
-            null
-            5
-            null
-            7
-        ]
-
-        Match against a pattern found in another column or (expression):
-
-        >>> p = pl.Series("pat", ["a[bc]", "b.t", "[aeiuo]", "(?i)A[BC]"])
-        >>> s.str.find(p).rename("idx")
-        shape: (4,)
-        Series: 'idx' [u32]
-        [
-            2
-            2
-            null
-            5
-        ]
-        """
-
-    def ends_with(self, suffix: str | Expr | None) -> Series:
-        """
-        Check if string values end with a substring.
-
-        Parameters
-        ----------
-        suffix
-            Suffix substring.
-
-        See Also
-        --------
-        contains : Check if the string contains a substring that matches a pattern.
-        starts_with : Check if string values start with a substring.
-
-        Examples
-        --------
-        >>> s = pl.Series("fruits", ["apple", "mango", None])
-        >>> s.str.ends_with("go")
-        shape: (3,)
-        Series: 'fruits' [bool]
-        [
-            false
-            true
-            null
-        ]
-        """
-
-    def starts_with(self, prefix: str | Expr) -> Series:
-        """
-        Check if string values start with a substring.
-
-        Parameters
-        ----------
-        prefix
-            Prefix substring.
-
-        See Also
-        --------
-        contains : Check if the string contains a substring that matches a pattern.
-        ends_with : Check if string values end with a substring.
-
-        Examples
-        --------
-        >>> s = pl.Series("fruits", ["apple", "mango", None])
-        >>> s.str.starts_with("app")
-        shape: (3,)
-        Series: 'fruits' [bool]
-        [
-            true
-            false
-            null
-        ]
-        """
-
-    def decode(self, encoding: TransferEncoding, *, strict: bool = True) -> Series:
-        r"""
-        Decode values using the provided encoding.
-
-        Parameters
-        ----------
-        encoding : {'hex', 'base64'}
-            The encoding to use.
-        strict
-            Raise an error if the underlying value cannot be decoded,
-            otherwise mask out with a null value.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`Binary`.
-
-        Examples
-        --------
-        >>> s = pl.Series("color", ["000000", "ffff00", "0000ff"])
-        >>> s.str.decode("hex")
-        shape: (3,)
-        Series: 'color' [binary]
-        [
-                b"\x00\x00\x00"
-                b"\xff\xff\x00"
-                b"\x00\x00\xff"
-        ]
-        """
-
-    def encode(self, encoding: TransferEncoding) -> Series:
-        """
-        Encode a value using the provided encoding.
-
-        Parameters
-        ----------
-        encoding : {'hex', 'base64'}
-            The encoding to use.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`String`.
-
-        Examples
-        --------
-        >>> s = pl.Series(["foo", "bar", None])
-        >>> s.str.encode("hex")
-        shape: (3,)
-        Series: '' [str]
-        [
-            "666f6f"
-            "626172"
-            null
-        ]
-        """
-
-    def json_decode(
-        self,
-        dtype: PolarsDataType | None = None,
-        *,
-        infer_schema_length: int | None = N_INFER_DEFAULT,
-    ) -> Series:
-        """
-        Parse string values as JSON.
-
-        Throws an error if invalid JSON strings are encountered.
-
-        Parameters
-        ----------
-        dtype
-            The dtype to cast the extracted value to. If None, the dtype will be
-            inferred from the JSON value.
-        infer_schema_length
-            The maximum number of rows to scan for schema inference.
-            If set to `None`, the full data may be scanned *(this is slow)*.
-
-        See Also
-        --------
-        json_path_match : Extract the first match of json string with provided JSONPath
-            expression.
-
-        Examples
-        --------
-        >>> s = pl.Series("json", ['{"a":1, "b": true}', None, '{"a":2, "b": false}'])
-        >>> s.str.json_decode()
-        shape: (3,)
-        Series: 'json' [struct[2]]
-        [
-                {1,true}
-                null
-                {2,false}
-        ]
-        """
-        if dtype is not None:
-            s = wrap_s(self._s)
-            return (
-                s.to_frame()
-                .select_seq(F.col(s.name).str.json_decode(dtype))
-                .to_series()
-            )
-
-        return wrap_s(self._s.str_json_decode(infer_schema_length))
-
-    def json_path_match(self, json_path: IntoExprColumn) -> Series:
-        """
-        Extract the first match of JSON string with provided JSONPath expression.
-
-        Throw errors if encounter invalid JSON strings.
-        All return values will be cast to String regardless of the original value.
-
-        Documentation on JSONPath standard can be found
-        `here <https://goessner.net/articles/JsonPath/>`_.
-
-        Parameters
-        ----------
-        json_path
-            A valid JSON path query string.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`String`. Contains null values if the original
-            value is null or the json_path returns nothing.
-
-        Examples
-        --------
-        >>> df = pl.DataFrame(
-        ...     {"json_val": ['{"a":"1"}', None, '{"a":2}', '{"a":2.1}', '{"a":true}']}
-        ... )
-        >>> df.select(pl.col("json_val").str.json_path_match("$.a"))[:, 0]
-        shape: (5,)
-        Series: 'json_val' [str]
-        [
-            "1"
-            null
-            "2"
-            "2.1"
-            "true"
-        ]
-        """
-
-    def extract(self, pattern: IntoExprColumn, group_index: int = 1) -> Series:
-        r"""
-        Extract the target capture group from provided patterns.
-
-        Parameters
-        ----------
-        pattern
-            A valid regular expression pattern containing at least one capture group,
-            compatible with the `regex crate <https://docs.rs/regex/latest/regex/>`_.
-        group_index
-            Index of the targeted capture group.
-            Group 0 means the whole pattern, the first group begins at index 1.
-            Defaults to the first capture group.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`String`. Contains null values if the original
-            value is null or regex captures nothing.
-
-        Notes
-        -----
-        To modify regular expression behaviour (such as multi-line matching)
-        with flags, use the inline `(?iLmsuxU)` syntax. For example:
-
-        >>> s = pl.Series(
-        ...     name="lines",
-        ...     values=[
-        ...         "I Like\nThose\nOdds",
-        ...         "This is\nThe Way",
-        ...     ],
-        ... )
-        >>> s.str.extract(r"(?m)^(T\w+)", 1).alias("matches")
-        shape: (2,)
-        Series: 'matches' [str]
-        [
-            "Those"
-            "This"
-        ]
-
-        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.
-
-        Examples
-        --------
-        >>> s = pl.Series(
-        ...     name="url",
-        ...     values=[
-        ...         "http://vote.com/ballon_dor?ref=polars&candidate=messi",
-        ...         "http://vote.com/ballon_dor?candidate=ronaldo&ref=polars",
-        ...         "http://vote.com/ballon_dor?error=404&ref=unknown",
-        ...     ],
-        ... )
-        >>> s.str.extract(r"candidate=(\w+)", 1).alias("candidate")
-        shape: (3,)
-        Series: 'candidate' [str]
-        [
-            "messi"
-            "ronaldo"
-            null
-        ]
-        """
-
-    def extract_all(self, pattern: str | Series) -> Series:
-        r'''
-        Extract all matches for the given regex pattern.
-
-        Extract each successive non-overlapping regex match in an individual string
-        as a list. If the haystack string is `null`, `null` is returned.
-
-        Parameters
-        ----------
-        pattern
-            A valid regular expression pattern, compatible with the `regex crate
-            <https://docs.rs/regex/latest/regex/>`_.
-
-        Notes
-        -----
-        To modify regular expression behaviour (such as "verbose" mode and/or
-        case-sensitive matching) with flags, use the inline `(?iLmsuxU)` syntax.
-        For example:
-
-        >>> s = pl.Series(
-        ...     name="email",
-        ...     values=[
-        ...         "real.email@spam.com",
-        ...         "some_account@somewhere.net",
-        ...         "abc.def.ghi.jkl@uvw.xyz.co.uk",
-        ...     ],
-        ... )
-        >>> # extract name/domain parts from email, using verbose regex
-        >>> s.str.extract_all(
-        ...     r"""(?xi)   # activate 'verbose' and 'case-insensitive' flags
-        ...       [         # (start character group)
-        ...         A-Z     # letters
-        ...         0-9     # digits
-        ...         ._%+\-  # special chars
-        ...       ]         # (end character group)
-        ...       +         # 'one or more' quantifier
-        ...     """
-        ... ).alias("email_parts")
-        shape: (3,)
-        Series: 'email_parts' [list[str]]
-        [
-            ["real.email", "spam.com"]
-            ["some_account", "somewhere.net"]
-            ["abc.def.ghi.jkl", "uvw.xyz.co.uk"]
-        ]
-
-        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.
-
-        Returns
-        -------
-        Series
-            Series of data type `List(String)`.
-
-        Examples
-        --------
-        >>> s = pl.Series("foo", ["123 bla 45 asd", "xyz 678 910t", "bar", None])
-        >>> s.str.extract_all(r"\d+")
-        shape: (4,)
-        Series: 'foo' [list[str]]
-        [
-            ["123", "45"]
-            ["678", "910"]
-            []
-            null
-        ]
-
-        '''
-
-    def extract_groups(self, pattern: str) -> Series:
-        r"""
-        Extract all capture groups for the given regex pattern.
-
-        Parameters
-        ----------
-        pattern
-            A valid regular expression pattern containing at least one capture group,
-            compatible with the `regex crate <https://docs.rs/regex/latest/regex/>`_.
-
-        Notes
-        -----
-        All group names are **strings**.
-
-        If your pattern contains unnamed groups, their numerical position is converted
-        to a string.
-
-        For example, we can access the first group via the string `"1"`::
-
-            >>> (
-            ...     pl.Series(["foo bar baz"])
-            ...     .str.extract_groups(r"(\w+) (.+) (\w+)")
-            ...     .struct["1"]
-            ... )
-            shape: (1,)
-            Series: '1' [str]
-            [
-                "foo"
-            ]
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`Struct` with fields of data type
-            :class:`String`.
-
-        Examples
-        --------
-        >>> s = pl.Series(
-        ...     name="url",
-        ...     values=[
-        ...         "http://vote.com/ballon_dor?candidate=messi&ref=python",
-        ...         "http://vote.com/ballon_dor?candidate=weghorst&ref=polars",
-        ...         "http://vote.com/ballon_dor?error=404&ref=rust",
-        ...     ],
-        ... )
-        >>> s.str.extract_groups(r"candidate=(?<candidate>\w+)&ref=(?<ref>\w+)")
-        shape: (3,)
-        Series: 'url' [struct[2]]
-        [
-            {"messi","python"}
-            {"weghorst","polars"}
-            {null,null}
-        ]
-        """
-
-    def count_matches(self, pattern: str | Series, *, literal: bool = False) -> Series:
-        r"""
-        Count all successive non-overlapping regex matches.
-
-        Parameters
-        ----------
-        pattern
-            A valid regular expression pattern, compatible with the `regex crate
-            <https://docs.rs/regex/latest/regex/>`_. Can also be a :class:`Series` of
-            regular expressions.
-        literal
-            Treat `pattern` as a literal string, not as a regular expression.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`UInt32`. Returns null if the original
-            value is null.
-
-        Examples
-        --------
-        >>> s = pl.Series("foo", ["123 bla 45 asd", "xyz 678 910t", "bar", None])
-        >>> # count digits
-        >>> s.str.count_matches(r"\d")
-        shape: (4,)
-        Series: 'foo' [u32]
-        [
-            5
-            6
-            0
-            null
-        ]
-
-        >>> s = pl.Series("bar", ["12 dbc 3xy", "cat\\w", "1zy3\\d\\d", None])
-        >>> s.str.count_matches(r"\d", literal=True)
-        shape: (4,)
-        Series: 'bar' [u32]
-        [
-            0
-            0
-            2
-            null
-        ]
-        """
-
-    def split(self, by: IntoExpr, *, inclusive: bool = False) -> Series:
-        """
-        Split the string by a substring.
-
-        Parameters
-        ----------
-        by
-            Substring to split by.
-        inclusive
-            If True, include the split character/string in the results.
-
-        Returns
-        -------
-        Series
-            Series of data type `List(String)`.
-        """
-
-    def split_exact(self, by: IntoExpr, n: int, *, inclusive: bool = False) -> Series:
-        """
-        Split the string by a substring using `n` splits.
-
-        Results in a struct of `n+1` fields.
-
-        If it cannot make `n` splits, the remaining field elements will be null.
-
-        Parameters
-        ----------
-        by
-            Substring to split by.
-        n
-            Number of splits to make.
-        inclusive
-            If True, include the split character/string in the results.
-
-        Examples
-        --------
-        >>> df = pl.DataFrame({"x": ["a_1", None, "c", "d_4"]})
-        >>> df["x"].str.split_exact("_", 1).alias("fields")
-        shape: (4,)
-        Series: 'fields' [struct[2]]
-        [
-                {"a","1"}
-                {null,null}
-                {"c",null}
-                {"d","4"}
-        ]
-
-        Split string values in column x in exactly 2 parts and assign
-        each part to a new column.
-
-        >>> (
-        ...     df["x"]
-        ...     .str.split_exact("_", 1)
-        ...     .struct.rename_fields(["first_part", "second_part"])
-        ...     .alias("fields")
-        ...     .to_frame()
-        ...     .unnest("fields")
-        ... )
-        shape: (4, 2)
-        ┌────────────┬─────────────┐
-        │ first_part ┆ second_part │
-        │ ---        ┆ ---         │
-        │ str        ┆ str         │
-        ╞════════════╪═════════════╡
-        │ a          ┆ 1           │
-        │ null       ┆ null        │
-        │ c          ┆ null        │
-        │ d          ┆ 4           │
-        └────────────┴─────────────┘
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`Struct` with fields of data type
-            :class:`String`.
-        """
-
-    def splitn(self, by: IntoExpr, n: int) -> Series:
-        """
-        Split the string by a substring, restricted to returning at most `n` items.
-
-        If the number of possible splits is less than `n-1`, the remaining field
-        elements will be null. If the number of possible splits is `n-1` or greater,
-        the last (nth) substring will contain the remainder of the string.
-
-        Parameters
-        ----------
-        by
-            Substring to split by.
-        n
-            Max number of items to return.
-
-        Examples
-        --------
-        >>> df = pl.DataFrame({"s": ["foo bar", None, "foo-bar", "foo bar baz"]})
-        >>> df["s"].str.splitn(" ", 2).alias("fields")
-        shape: (4,)
-        Series: 'fields' [struct[2]]
-        [
-                {"foo","bar"}
-                {null,null}
-                {"foo-bar",null}
-                {"foo","bar baz"}
-        ]
-
-        Split string values in column s in exactly 2 parts and assign
-        each part to a new column.
-
-        >>> (
-        ...     df["s"]
-        ...     .str.splitn(" ", 2)
-        ...     .struct.rename_fields(["first_part", "second_part"])
-        ...     .alias("fields")
-        ...     .to_frame()
-        ...     .unnest("fields")
-        ... )
-        shape: (4, 2)
-        ┌────────────┬─────────────┐
-        │ first_part ┆ second_part │
-        │ ---        ┆ ---         │
-        │ str        ┆ str         │
-        ╞════════════╪═════════════╡
-        │ foo        ┆ bar         │
-        │ null       ┆ null        │
-        │ foo-bar    ┆ null        │
-        │ foo        ┆ bar baz     │
-        └────────────┴─────────────┘
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`Struct` with fields of data type
-            :class:`String`.
-        """
-
-    def replace(
-        self, pattern: str, value: str, *, literal: bool = False, n: int = 1
-    ) -> Series:
-        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.
-
-        See Also
-        --------
-        replace_all
-
-        Notes
-        -----
-        * To modify regular expression behaviour (such as case-sensitivity) with flags,
-          use the inline `(?iLmsuxU)` syntax. (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).
-
-        * The dollar sign (`$`) is a special character related to capture groups; if you
-          want to replace some target pattern with characters that include a literal `$`
-          you should escape it by doubling it up as `$$`, or set `literal=True` if you
-          do not need a full regular expression pattern match. Otherwise, you will be
-          referencing a (potentially non-existent) capture group.
-
-          If not escaped, the `$0` in the replacement value (below) represents a capture
-          group:
-
-          .. code-block:: python
-
-              >>> s = pl.Series("cents", ["000.25", "00.50", "0.75"])
-              >>> s.str.replace(r"^(0+)\.", "$0.")
-              shape: (3,)
-              Series: 'cents' [str]
-              [
-                "000..25"
-                "00..50"
-                "0..75"
-              ]
-
-          To have `$` represent a literal value, it should be doubled-up as `$$`
-          (or, for simpler find/replace operations, set `literal=True` if you do
-          not require a full regular expression match):
-
-          .. code-block:: python
-
-              >>> s.str.replace(r"^(0+)\.", "$$0.")
-              shape: (3,)
-              Series: 'cents' [str]
-              [
-                "$0.25"
-                "$0.50"
-                "$0.75"
-              ]
-
-        Examples
-        --------
-        >>> s = pl.Series(["123abc", "abc456"])
-        >>> s.str.replace(r"abc\b", "ABC")
-        shape: (2,)
-        Series: '' [str]
-        [
-            "123ABC"
-            "abc456"
-        ]
-
-        Capture groups are supported. Use `$1` or `${1}` in the `value` string to refer
-        to the first capture group in the `pattern`, `$2` or `${2}` to refer to the
-        second capture group, and so on. You can also use *named* capture groups.
-
-        >>> s = pl.Series(["hat", "hut"])
-        >>> s.str.replace("h(.)t", "b${1}d")
-        shape: (2,)
-        Series: '' [str]
-        [
-            "bad"
-            "bud"
-        ]
-        >>> s.str.replace("h(?<vowel>.)t", "b${vowel}d")
-        shape: (2,)
-        Series: '' [str]
-        [
-            "bad"
-            "bud"
-        ]
-
-        Apply case-insensitive string replacement using the `(?i)` flag.
-
-        >>> s = pl.Series("weather", ["Foggy", "Rainy", "Sunny"])
-        >>> s.str.replace(r"(?i)foggy|rainy", "Sunny")
-        shape: (3,)
-        Series: 'weather' [str]
-        [
-            "Sunny"
-            "Sunny"
-            "Sunny"
-        ]
-        """
-
-    def replace_all(self, pattern: str, value: str, *, literal: bool = False) -> Series:
-        r"""
-        Replace all matching regex/literal substrings 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.
-
-        See Also
-        --------
-        replace
-
-        Notes
-        -----
-        * To modify regular expression behaviour (such as case-sensitivity) with flags,
-          use the inline `(?iLmsuxU)` syntax. (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).
-
-        * The dollar sign (`$`) is a special character related to capture groups; if you
-          want to replace some target pattern with characters that include a literal `$`
-          you should escape it by doubling it up as `$$`, or set `literal=True` if you
-          do not need a full regular expression pattern match. Otherwise, you will be
-          referencing a (potentially non-existent) capture group.
-
-          In the example below we need to double up `$` (to represent a literal dollar
-          sign, and then refer to the capture group using `$n` or `${n}`, hence the
-          three consecutive `$` characters in the replacement value:
-
-          .. code-block:: python
-
-              >>> s = pl.Series("cost", ["#12.34", "#56.78"])
-              >>> s.str.replace_all(r"#(\d+)", "$$${1}").alias("cost_usd")
-              shape: (2,)
-              Series: 'cost_usd' [str]
-              [
-                  "$12.34"
-                  "$56.78"
-              ]
-
-        Examples
-        --------
-        >>> s = pl.Series(["123abc", "abc456"])
-        >>> s.str.replace_all(r"abc\b", "ABC")
-        shape: (2,)
-        Series: '' [str]
-        [
-            "123ABC"
-            "abc456"
-        ]
-
-        Capture groups are supported. Use `$1` or `${1}` in the `value` string to refer
-        to the first capture group in the `pattern`, `$2` or `${2}` to refer to the
-        second capture group, and so on. You can also use *named* capture groups.
-
-        >>> s = pl.Series(["hat", "hut"])
-        >>> s.str.replace_all("h(.)t", "b${1}d")
-        shape: (2,)
-        Series: '' [str]
-        [
-            "bad"
-            "bud"
-        ]
-        >>> s.str.replace_all("h(?<vowel>.)t", "b${vowel}d")
-        shape: (2,)
-        Series: '' [str]
-        [
-            "bad"
-            "bud"
-        ]
-
-        Apply case-insensitive string replacement using the `(?i)` flag.
-
-        >>> s = pl.Series("weather", ["Foggy", "Rainy", "Sunny"])
-        >>> s.str.replace_all(r"(?i)foggy|rainy", "Sunny")
-        shape: (3,)
-        Series: 'weather' [str]
-        [
-            "Sunny"
-            "Sunny"
-            "Sunny"
-        ]
-        """
-
-    def strip_chars(self, characters: IntoExpr = None) -> Series:
-        r"""
-        Remove leading and trailing characters.
-
-        Parameters
-        ----------
-        characters
-            The set of characters to be removed. All combinations of this set of
-            characters will be stripped from the start and end of the string. If set to
-            None (default), all leading and trailing whitespace is removed instead.
-
-        Examples
-        --------
-        >>> s = pl.Series([" hello ", "\tworld"])
-        >>> s.str.strip_chars()
-        shape: (2,)
-        Series: '' [str]
-        [
-                "hello"
-                "world"
-        ]
-
-        Characters can be stripped by passing a string as argument. Note that whitespace
-        will not be stripped automatically when doing so, unless that whitespace is
-        also included in the string.
-
-        >>> s.str.strip_chars("o ")
-        shape: (2,)
-        Series: '' [str]
-        [
-            "hell"
-            "	world"
-        ]
-        """
-
-    def strip_chars_start(self, characters: IntoExpr = None) -> Series:
-        r"""
-        Remove leading characters.
-
-        Parameters
-        ----------
-        characters
-            The set of characters to be removed. All combinations of this set of
-            characters will be stripped from the start of the string. If set to None
-            (default), all leading whitespace is removed instead.
-
-        Examples
-        --------
-        >>> s = pl.Series([" hello ", "\tworld"])
-        >>> s.str.strip_chars_start()
-        shape: (2,)
-        Series: '' [str]
-        [
-                "hello "
-                "world"
-        ]
-
-        Characters can be stripped by passing a string as argument. Note that whitespace
-        will not be stripped automatically when doing so.
-
-        >>> s.str.strip_chars_start("wod\t")
-        shape: (2,)
-        Series: '' [str]
-        [
-                " hello "
-                "rld"
-        ]
-        """
-
-    def strip_chars_end(self, characters: IntoExpr = None) -> Series:
-        r"""
-        Remove trailing characters.
-
-        Parameters
-        ----------
-        characters
-            The set of characters to be removed. All combinations of this set of
-            characters will be stripped from the end of the string. If set to None
-            (default), all trailing whitespace is removed instead.
-
-        Examples
-        --------
-        >>> s = pl.Series([" hello ", "world\t"])
-        >>> s.str.strip_chars_end()
-        shape: (2,)
-        Series: '' [str]
-        [
-                " hello"
-                "world"
-        ]
-
-        Characters can be stripped by passing a string as argument. Note that whitespace
-        will not be stripped automatically when doing so.
-
-        >>> s.str.strip_chars_end("orld\t")
-        shape: (2,)
-        Series: '' [str]
-        [
-            " hello "
-            "w"
-        ]
-        """
-
-    def strip_prefix(self, prefix: IntoExpr) -> Series:
-        """
-        Remove prefix.
-
-        The prefix will be removed from the string exactly once, if found.
-
-        Parameters
-        ----------
-        prefix
-            The prefix to be removed.
-
-        Examples
-        --------
-        >>> s = pl.Series(["foobar", "foofoobar", "foo", "bar"])
-        >>> s.str.strip_prefix("foo")
-        shape: (4,)
-        Series: '' [str]
-        [
-                "bar"
-                "foobar"
-                ""
-                "bar"
-        ]
-        """
-
-    def strip_suffix(self, suffix: IntoExpr) -> Series:
-        """
-        Remove suffix.
-
-        The suffix will be removed from the string exactly once, if found.
-
-        Parameters
-        ----------
-        suffix
-            The suffix to be removed.
-
-        Examples
-        --------
-        >>> s = pl.Series(["foobar", "foobarbar", "foo", "bar"])
-        >>> s.str.strip_suffix("bar")
-        shape: (4,)
-        Series: '' [str]
-        [
-                "foo"
-                "foobar"
-                "foo"
-                ""
-        ]
-        """
-
-    def pad_start(self, length: int | IntoExprColumn, fill_char: str = " ") -> Series:
-        """
-        Pad the start of the string until it reaches the given length.
-
-        Parameters
-        ----------
-        length
-            Pad the string until it reaches this length. Strings with length equal to or
-            greater than this value are returned as-is.
-        fill_char
-            The character to pad the string with.
-
-        See Also
-        --------
-        pad_end
-        zfill
-
-        Examples
-        --------
-        >>> s = pl.Series("a", ["cow", "monkey", "hippopotamus", None])
-        >>> s.str.pad_start(8, "*")
-        shape: (4,)
-        Series: 'a' [str]
-        [
-            "*****cow"
-            "**monkey"
-            "hippopotamus"
-            null
-        ]
-        """
-
-    def pad_end(self, length: int | IntoExprColumn, fill_char: str = " ") -> Series:
-        """
-        Pad the end of the string until it reaches the given length.
-
-        Parameters
-        ----------
-        length
-            Pad the string until it reaches this length. Strings with length equal to or
-            greater than this value are returned as-is.
-        fill_char
-            The character to pad the string with.
-
-        See Also
-        --------
-        pad_start
-
-        Examples
-        --------
-        >>> s = pl.Series(["cow", "monkey", "hippopotamus", None])
-        >>> s.str.pad_end(8, "*")
-        shape: (4,)
-        Series: '' [str]
-        [
-            "cow*****"
-            "monkey**"
-            "hippopotamus"
-            null
-        ]
-        """
-
-    def zfill(self, length: int | IntoExprColumn) -> Series:
-        """
-        Pad the start of the string with zeros until it reaches the given length.
-
-        A sign prefix (`-`) is handled by inserting the padding after the sign character
-        rather than before.
-
-        Parameters
-        ----------
-        length
-            Pad the string until it reaches this length. Strings with length equal to or
-            greater than this value are returned as-is.
-
-        See Also
-        --------
-        pad_start
-
-        Notes
-        -----
-        This method is intended for padding numeric strings. If your data contains
-        non-ASCII characters, use :func:`pad_start` instead.
-
-        Examples
-        --------
-        >>> s = pl.Series([-1, 123, 999999, None])
-        >>> s.cast(pl.String).str.zfill(4)
-        shape: (4,)
-        Series: '' [str]
-        [
-                "-001"
-                "0123"
-                "999999"
-                null
-        ]
-        """
-
-    def to_lowercase(self) -> Series:
-        """
-        Modify strings to their lowercase equivalent.
-
-        Examples
-        --------
-        >>> s = pl.Series("foo", ["CAT", "DOG"])
-        >>> s.str.to_lowercase()
-        shape: (2,)
-        Series: 'foo' [str]
-        [
-            "cat"
-            "dog"
-        ]
-        """
-
-    def to_uppercase(self) -> Series:
-        """
-        Modify strings to their uppercase equivalent.
-
-        Examples
-        --------
-        >>> s = pl.Series("foo", ["cat", "dog"])
-        >>> s.str.to_uppercase()
-        shape: (2,)
-        Series: 'foo' [str]
-        [
-            "CAT"
-            "DOG"
-        ]
-        """
-
-    def to_titlecase(self) -> Series:
-        """
-        Modify strings to their titlecase equivalent.
-
-        Notes
-        -----
-        This is a form of case transform where the first letter of each word is
-        capitalized, with the rest of the word in lowercase. Non-alphanumeric
-        characters define the word boundaries.
-
-        Examples
-        --------
-        >>> s = pl.Series(
-        ...     "quotes",
-        ...     [
-        ...         "'e.t. phone home'",
-        ...         "you talkin' to me?",
-        ...         "to infinity,and BEYOND!",
-        ...     ],
-        ... )
-        >>> s.str.to_titlecase()
-        shape: (3,)
-        Series: 'quotes' [str]
-        [
-            "'E.T. Phone Home'"
-            "You Talkin' To Me?"
-            "To Infinity,And Beyond!"
-        ]
-        """
-
-    def reverse(self) -> Series:
-        """
-        Returns string values in reversed order.
-
-        Examples
-        --------
-        >>> s = pl.Series("text", ["foo", "bar", "man\u0303ana"])
-        >>> s.str.reverse()
-        shape: (3,)
-        Series: 'text' [str]
-        [
-            "oof"
-            "rab"
-            "anañam"
-        ]
-        """
-
-    def slice(
-        self, offset: int | IntoExprColumn, length: int | IntoExprColumn | None = None
-    ) -> Series:
-        """
-        Extract a substring from each string value.
-
-        Parameters
-        ----------
-        offset
-            Start index. Negative indexing is supported.
-        length
-            Length of the slice. If set to `None` (default), the slice is taken to the
-            end of the string.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`String`.
-
-        Notes
-        -----
-        Both the `offset` and `length` inputs are defined in terms of the number
-        of characters in the (UTF8) string. A character is defined as a
-        `Unicode scalar value`_. A single character is represented by a single byte
-        when working with ASCII text, and a maximum of 4 bytes otherwise.
-
-        .. _Unicode scalar value: https://www.unicode.org/glossary/#unicode_scalar_value
-
-        Examples
-        --------
-        >>> s = pl.Series(["pear", None, "papaya", "dragonfruit"])
-        >>> s.str.slice(-3)
-        shape: (4,)
-        Series: '' [str]
-        [
-            "ear"
-            null
-            "aya"
-            "uit"
-        ]
-
-        Using the optional `length` parameter
-
-        >>> s.str.slice(4, length=3)
-        shape: (4,)
-        Series: '' [str]
-        [
-            ""
-            null
-            "ya"
-            "onf"
-        ]
-        """
-
-    def head(self, n: int | IntoExprColumn) -> Series:
-        """
-        Return the first n characters of each string in a String Series.
-
-        Parameters
-        ----------
-        n
-            Length of the slice (integer or expression). Negative indexing is supported;
-            see note (2) below.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`String`.
-
-        Notes
-        -----
-        1) The `n` input is defined in terms of the number of characters in the (UTF8)
-           string. A character is defined as a `Unicode scalar value`_. A single
-           character is represented by a single byte when working with ASCII text, and a
-           maximum of 4 bytes otherwise.
-
-           .. _Unicode scalar value: https://www.unicode.org/glossary/#unicode_scalar_value
-
-        2) When `n` is negative, `head` returns characters up to the `n`th from the end
-           of the string. For example, if `n = -3`, then all characters except the last
-           three are returned.
-
-        3) If the length of the string has fewer than `n` characters, the full string is
-           returned.
-
-        Examples
-        --------
-        Return up to the first 5 characters.
-
-        >>> s = pl.Series(["pear", None, "papaya", "dragonfruit"])
-        >>> s.str.head(5)
-        shape: (4,)
-        Series: '' [str]
-        [
-            "pear"
-            null
-            "papay"
-            "drago"
-        ]
-
-        Return up to the 3rd character from the end.
-
-        >>> s = pl.Series(["pear", None, "papaya", "dragonfruit"])
-        >>> s.str.head(-3)
-        shape: (4,)
-        Series: '' [str]
-        [
-            "p"
-            null
-            "pap"
-            "dragonfr"
-        ]
-        """
-
-    def tail(self, n: int | IntoExprColumn) -> Series:
-        """
-        Return the last n characters of each string in a String Series.
-
-        Parameters
-        ----------
-        n
-            Length of the slice (integer or expression). Negative indexing is supported;
-            see note (2) below.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`String`.
-
-        Notes
-        -----
-        1) The `n` input is defined in terms of the number of characters in the (UTF8)
-           string. A character is defined as a `Unicode scalar value`_. A single
-           character is represented by a single byte when working with ASCII text, and a
-           maximum of 4 bytes otherwise.
-
-           .. _Unicode scalar value: https://www.unicode.org/glossary/#unicode_scalar_value
-
-        2) When `n` is negative, `tail` returns characters starting from the `n`th from
-           the beginning of the string. For example, if `n = -3`, then all characters
-           except the first three are returned.
-
-        3) If the length of the string has fewer than `n` characters, the full string is
-           returned.
-
-        Examples
-        --------
-        Return up to the last 5 characters:
-
-        >>> s = pl.Series(["pear", None, "papaya", "dragonfruit"])
-        >>> s.str.tail(5)
-        shape: (4,)
-        Series: '' [str]
-        [
-            "pear"
-            null
-            "apaya"
-            "fruit"
-        ]
-
-        Return from the 3rd character to the end:
-
-        >>> s = pl.Series(["pear", None, "papaya", "dragonfruit"])
-        >>> s.str.tail(-3)
-        shape: (4,)
-        Series: '' [str]
-        [
-            "r"
-            null
-            "aya"
-            "gonfruit"
-        ]
-        """
-
-    @deprecated(
-        '`Series.str.explode` is deprecated; use `Series.str.split("").explode()` instead. '
-        "Note that empty strings will result in null instead of being preserved. To get "
-        "the exact same behavior, split first and then use a `pl.when...then...otherwise` "
-        "expression to handle the empty list before exploding. "
-    )
-    def explode(self) -> Series:
-        """
-        Returns a column with a separate row for every string character.
-
-        .. deprecated:: 0.20.31
-            Use the `.str.split("").explode()` method instead. Note that empty strings
-            will result in null instead of being preserved. To get the exact same
-            behavior, split first and then use a `pl.when...then...otherwise`
-            expression to handle the empty list before exploding.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`String`.
-
-        Examples
-        --------
-        >>> s = pl.Series("a", ["foo", "bar"])
-        >>> s.str.explode()  # doctest: +SKIP
-        shape: (6,)
-        Series: 'a' [str]
-        [
-                "f"
-                "o"
-                "o"
-                "b"
-                "a"
-                "r"
-        ]
-        """
-
-    def to_integer(
-        self,
-        *,
-        base: int | IntoExprColumn = 10,
-        dtype: PolarsIntegerType = Int64,
-        strict: bool = True,
-    ) -> Series:
-        """
-        Convert an String column into a column of dtype with base radix.
-
-        Parameters
-        ----------
-        base
-            Positive integer or expression which is the base of the string
-            we are parsing.
-            Default: 10.
-        dtype
-            Polars integer type to cast to.
-            Default: :class:`Int64`.
-        strict
-            Bool, Default=True will raise any ParseError or overflow as ComputeError.
-            False silently convert to Null.
-
-        Returns
-        -------
-        Series
-            Series of data.
-
-        Examples
-        --------
-        >>> s = pl.Series("bin", ["110", "101", "010", "invalid"])
-        >>> s.str.to_integer(base=2, dtype=pl.Int32, strict=False)
-        shape: (4,)
-        Series: 'bin' [i32]
-        [
-                6
-                5
-                2
-                null
-        ]
-
-        >>> s = pl.Series("hex", ["fa1e", "ff00", "cafe", None])
-        >>> s.str.to_integer(base=16)
-        shape: (4,)
-        Series: 'hex' [i64]
-        [
-                64030
-                65280
-                51966
-                null
-        ]
-        """
-
-    def contains_any(
-        self, patterns: Series | list[str], *, ascii_case_insensitive: bool = False
-    ) -> Series:
-        """
-        Use the Aho-Corasick algorithm to find matches.
-
-        Determines if any of the patterns are contained in the string.
-
-        Parameters
-        ----------
-        patterns
-            String patterns to search.
-        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.
-
-        Notes
-        -----
-        This method supports matching on string literals only, and does not support
-        regular expression matching.
-
-        Examples
-        --------
-        >>> _ = 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.contains_any(["you", "me"])
-        shape: (3,)
-        Series: 'lyrics' [bool]
-        [
-            false
-            true
-            true
-        ]
-        """
-
-    def replace_many(
-        self,
-        patterns: Series | list[str] | Mapping[str, str],
-        replace_with: Series | list[str] | str | NoDefault = no_default,
-        *,
-        ascii_case_insensitive: bool = False,
-    ) -> Series:
-        """
-        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.
-
-        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"
-        ]
-        """
-
-    @unstable()
-    def extract_many(
-        self,
-        patterns: Series | list[str],
-        *,
-        ascii_case_insensitive: bool = False,
-        overlapping: bool = False,
-    ) -> Series:
-        """
-        Use the Aho-Corasick algorithm to extract many matches.
-
-        Parameters
-        ----------
-        patterns
-            String patterns to search.
-        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.
-        overlapping
-            Whether matches may overlap.
-
-        Notes
-        -----
-        This method supports matching on string literals only, and does not support
-        regular expression matching.
-
-        Examples
-        --------
-        >>> s = pl.Series("values", ["discontent"])
-        >>> patterns = ["winter", "disco", "onte", "discontent"]
-        >>> s.str.extract_many(patterns, overlapping=True)
-        shape: (1,)
-        Series: 'values' [list[str]]
-        [
-            ["disco", "onte", "discontent"]
-        ]
-
-        """
-
-    @unstable()
-    def find_many(
-        self,
-        patterns: IntoExpr,
-        *,
-        ascii_case_insensitive: bool = False,
-        overlapping: bool = False,
-    ) -> Series:
-        """
-        Use the Aho-Corasick algorithm to find all matches.
-
-        The function returns the byte offset of the start of each match.
-        The return type will be `List<UInt32>`
-
-        Parameters
-        ----------
-        patterns
-            String patterns to search.
-        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.
-        overlapping
-            Whether matches may overlap.
-
-        Notes
-        -----
-        This method supports matching on string literals only, and does not support
-        regular expression matching.
-
-        Examples
-        --------
-        >>> _ = pl.Config.set_fmt_str_lengths(100)
-        >>> df = pl.DataFrame({"values": ["discontent"]})
-        >>> patterns = ["winter", "disco", "onte", "discontent"]
-        >>> df.with_columns(
-        ...     pl.col("values")
-        ...     .str.extract_many(patterns, overlapping=False)
-        ...     .alias("matches"),
-        ...     pl.col("values")
-        ...     .str.extract_many(patterns, overlapping=True)
-        ...     .alias("matches_overlapping"),
-        ... )
-        shape: (1, 3)
-        ┌────────────┬───────────┬─────────────────────────────────┐
-        │ values     ┆ matches   ┆ matches_overlapping             │
-        │ ---        ┆ ---       ┆ ---                             │
-        │ str        ┆ list[str] ┆ list[str]                       │
-        ╞════════════╪═══════════╪═════════════════════════════════╡
-        │ discontent ┆ ["disco"] ┆ ["disco", "onte", "discontent"] │
-        └────────────┴───────────┴─────────────────────────────────┘
-        >>> df = pl.DataFrame(
-        ...     {
-        ...         "values": ["discontent", "rhapsody"],
-        ...         "patterns": [
-        ...             ["winter", "disco", "onte", "discontent"],
-        ...             ["rhap", "ody", "coalesce"],
-        ...         ],
-        ...     }
-        ... )
-        >>> df.select(pl.col("values").str.find_many("patterns"))
-        shape: (2, 1)
-        ┌───────────┐
-        │ values    │
-        │ ---       │
-        │ list[u32] │
-        ╞═══════════╡
-        │ [0]       │
-        │ [0, 5]    │
-        └───────────┘
-        """
-
-    def join(self, delimiter: str = "", *, ignore_nulls: bool = True) -> Series:
-        """
-        Vertically concatenate the string values in the column to a single string value.
-
-        Parameters
-        ----------
-        delimiter
-            The delimiter to insert between consecutive string values.
-        ignore_nulls
-            Ignore null values (default).
-            If set to `False`, null values will be propagated. This means that
-            if the column contains any null values, the output is null.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`String`.
-
-        Examples
-        --------
-        >>> s = pl.Series([1, None, 3])
-        >>> s.str.join("-")
-        shape: (1,)
-        Series: '' [str]
-        [
-            "1-3"
-        ]
-        >>> s.str.join(ignore_nulls=False)
-        shape: (1,)
-        Series: '' [str]
-        [
-            null
-        ]
-        """
-
-    @deprecated(
-        "`Series.str.concat` is deprecated; use `Series.str.join` instead. Note also "
-        "that the default `delimiter` for `str.join` is an empty string, not a hyphen."
-    )
-    def concat(
-        self, delimiter: str | None = None, *, ignore_nulls: bool = True
-    ) -> Series:
-        """
-        Vertically concatenate the string values in the column to a single string value.
-
-        .. deprecated:: 1.0.0
-            Use :meth:`join` instead. Note that the default `delimiter` for :meth:`join`
-            is an empty string instead of a hyphen.
-
-        Parameters
-        ----------
-        delimiter
-            The delimiter to insert between consecutive string values.
-        ignore_nulls
-            Ignore null values (default).
-            If set to `False`, null values will be propagated. This means that
-            if the column contains any null values, the output is null.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`String`.
-
-        Examples
-        --------
-        >>> pl.Series([1, None, 2]).str.concat("-")  # doctest: +SKIP
-        shape: (1,)
-        Series: '' [str]
-        [
-            "1-2"
-        ]
-        >>> pl.Series([1, None, 2]).str.concat(ignore_nulls=False)  # doctest: +SKIP
-        shape: (1,)
-        Series: '' [str]
-        [
-            null
-        ]
-        """
-
-    def escape_regex(self) -> Series:
-        r"""
-        Returns string values with all regular expression meta characters escaped.
-
-        Returns
-        -------
-        Series
-            Series of data type :class:`String`.
-
-        Examples
-        --------
-        >>> pl.Series(["abc", "def", None, "abc(\\w+)"]).str.escape_regex()
-        shape: (4,)
-        Series: '' [str]
-        [
-            "abc"
-            "def"
-            null
-            "abc\(\\w\+\)"
-        ]
-        """
-
-    def normalize(self, form: UnicodeForm = "NFC") -> Series:
-        """
-        Returns the Unicode normal form of the string values.
-
-        This uses the forms described in Unicode Standard Annex 15: <https://www.unicode.org/reports/tr15/>.
-
-        Parameters
-        ----------
-        form : {'NFC', 'NFKC', 'NFD', 'NFKD'}
-            Unicode form to use.
-
-        Examples
-        --------
-        >>> s = pl.Series(["01²", "ＫＡＤＯＫＡＷＡ"])
-        >>> s.str.normalize("NFC")
-        shape: (2,)
-        Series: '' [str]
-        [
-                "01²"
-                "ＫＡＤＯＫＡＷＡ"
-        ]
-        >>> s.str.normalize("NFKC")
-        shape: (2,)
-        Series: '' [str]
-        [
-                "012"
-                "KADOKAWA"
-        ]
-        """  # noqa: RUF002