class_docstr: Namespace for string related expressions.
class_docstr_tok: ["Namespace","for","string","related","expressions","."]
docstr: Extract all capture groups for the given regex pattern.
  
  Parameters
  ----------
  pattern
      A valid regular expression pattern, 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, here we access groups 2 and 3 via the names `"2"` and `"3"`::
  
      >>> df = pl.DataFrame({"col": ["foo bar baz"]})
      >>> (
      ...     df.with_columns(
      ...         pl.col("col").str.extract_groups(r"(\S+) (\S+) (.+)")
      ...     ).select(pl.col("col").struct["2"], pl.col("col").struct["3"])
      ... )
      shape: (1, 2)
      ┌─────┬─────┐
      │ 2   ┆ 3   │
      │ --- ┆ --- │
      │ str ┆ str │
      ╞═════╪═════╡
      │ bar ┆ baz │
      └─────┴─────┘
  
  Returns
  -------
  Expr
      Expression of data type :class:`Struct` with fields of data type
      :class:`String`.
  
  Examples
  --------
  >>> df = pl.DataFrame(
  ...     data={
  ...         "url": [
  ...             "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",
  ...         ]
  ...     }
  ... )
  >>> pattern = r"candidate=(?<candidate>\w+)&ref=(?<ref>\w+)"
  >>> df.select(captures=pl.col("url").str.extract_groups(pattern)).unnest(
  ...     "captures"
  ... )
  shape: (3, 2)
  ┌───────────┬────────┐
  │ candidate ┆ ref    │
  │ ---       ┆ ---    │
  │ str       ┆ str    │
  ╞═══════════╪════════╡
  │ messi     ┆ python │
  │ weghorst  ┆ polars │
  │ null      ┆ null   │
  └───────────┴────────┘
  
  Unnamed groups have their numerical position converted to a string:
  
  >>> pattern = r"candidate=(\w+)&ref=(\w+)"
  >>> (
  ...     df.with_columns(
  ...         captures=pl.col("url").str.extract_groups(pattern)
  ...     ).with_columns(name=pl.col("captures").struct["1"].str.to_uppercase())
  ... )
  shape: (3, 3)
  ┌───────────────────────────────────┬───────────────────────┬──────────┐
  │ url                               ┆ captures              ┆ name     │
  │ ---                               ┆ ---                   ┆ ---      │
  │ str                               ┆ struct[2]             ┆ str      │
  ╞═══════════════════════════════════╪═══════════════════════╪══════════╡
  │ http://vote.com/ballon_dor?candi… ┆ {"messi","python"}    ┆ MESSI    │
  │ http://vote.com/ballon_dor?candi… ┆ {"weghorst","polars"} ┆ WEGHORST │
  │ http://vote.com/ballon_dor?error… ┆ {null,null}           ┆ null     │
  └───────────────────────────────────┴───────────────────────┴──────────┘
docstr_tok: ["Extract","all","capture","groups","for","the","given","regex","pattern",".","Parameters","--","--","--","--","--","pattern","A","valid","regular","expression","pattern",",","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",",","here","we","access","groups","2","and","3","via","the","names","`","``","2","''","`","and","`","``","3","''","`",":",":",">",">",">","df","=","pl.DataFrame","(","{","``","col","''",":","[","``","foo","bar","baz","''","]","}",")",">",">",">","(","...","df.with_columns","(","...","pl.col","(","``","col","''",")",".str.extract_groups","(","r","''","(","\\S+",")","(","\\S+",")","(",".+",")","''",")","...",")",".select","(","pl.col","(","``","col","''",")",".struct","[","``","2","''","]",",","pl.col","(","``","col","''",")",".struct","[","``","3","''","]",")","...",")","shape",":","(","1",",","2",")","\u250c\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2510","\u2502","2","\u2506","3","\u2502","\u2502","--","-","\u2506","--","-","\u2502","\u2502","str","\u2506","str","\u2502","\u255e\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2561","\u2502","bar","\u2506","baz","\u2502","\u2514\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2518","Returns","--","--","--","-","Expr","Expression","of","data","type",":","class",":","`","Struct","`","with","fields","of","data","type",":","class",":","`","String","`",".","Examples","--","--","--","--",">",">",">","df","=","pl.DataFrame","(","...","data=","{","...","``","url","''",":","[","...","``","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","''",",","...","]","...","}","...",")",">",">",">","pattern","=","r","''","candidate=","(","?","<","candidate",">","\\w+",")","&","ref=","(","?","<","ref",">","\\w+",")","''",">",">",">","df.select","(","captures=pl.col","(","``","url","''",")",".str.extract_groups","(","pattern",")",")",".unnest","(","...","``","captures","''","...",")","shape",":","(","3",",","2",")","\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510","\u2502","candidate","\u2506","ref","\u2502","\u2502","--","-","\u2506","--","-","\u2502","\u2502","str","\u2506","str","\u2502","\u255e\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561","\u2502","messi","\u2506","python","\u2502","\u2502","weghorst","\u2506","polars","\u2502","\u2502","null","\u2506","null","\u2502","\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518","Unnamed","groups","have","their","numerical","position","converted","to","a","string",":",">",">",">","pattern","=","r","''","candidate=","(","\\w+",")","&","ref=","(","\\w+",")","''",">",">",">","(","...","df.with_columns","(","...","captures=pl.col","(","``","url","''",")",".str.extract_groups","(","pattern",")","...",")",".with_columns","(","name=pl.col","(","``","captures","''",")",".struct","[","``","1","''","]",".str.to_uppercase","(",")",")","...",")","shape",":","(","3",",","3",")","\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510","\u2502","url","\u2506","captures","\u2506","name","\u2502","\u2502","--","-","\u2506","--","-","\u2506","--","-","\u2502","\u2502","str","\u2506","struct","[","2","]","\u2506","str","\u2502","\u255e\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561","\u2502","http",":","\/\/vote.com\/ballon_dor","?","candi\u2026","\u2506","{","``","messi","''",",","''","python","''","}","\u2506","MESSI","\u2502","\u2502","http",":","\/\/vote.com\/ballon_dor","?","candi\u2026","\u2506","{","``","weghorst","''",",","''","polars","''","}","\u2506","WEGHORST","\u2502","\u2502","http",":","\/\/vote.com\/ballon_dor","?","error\u2026","\u2506","{","null",",","null","}","\u2506","null","\u2502","\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518"]
code: def extract_groups(self, pattern: str) -> Expr:
      r"""
      Extract all capture groups for the given regex pattern.
  
      Parameters
      ----------
      pattern
          A valid regular expression pattern, 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, here we access groups 2 and 3 via the names `"2"` and `"3"`::
  
          >>> df = pl.DataFrame({"col": ["foo bar baz"]})
          >>> (
          ...     df.with_columns(
          ...         pl.col("col").str.extract_groups(r"(\S+) (\S+) (.+)")
          ...     ).select(pl.col("col").struct["2"], pl.col("col").struct["3"])
          ... )
          shape: (1, 2)
          ┌─────┬─────┐
          │ 2   ┆ 3   │
          │ --- ┆ --- │
          │ str ┆ str │
          ╞═════╪═════╡
          │ bar ┆ baz │
          └─────┴─────┘
  
      Returns
      -------
      Expr
          Expression of data type :class:`Struct` with fields of data type
          :class:`String`.
  
      Examples
      --------
      >>> df = pl.DataFrame(
      ...     data={
      ...         "url": [
      ...             "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",
      ...         ]
      ...     }
      ... )
      >>> pattern = r"candidate=(?<candidate>\w+)&ref=(?<ref>\w+)"
      >>> df.select(captures=pl.col("url").str.extract_groups(pattern)).unnest(
      ...     "captures"
      ... )
      shape: (3, 2)
      ┌───────────┬────────┐
      │ candidate ┆ ref    │
      │ ---       ┆ ---    │
      │ str       ┆ str    │
      ╞═══════════╪════════╡
      │ messi     ┆ python │
      │ weghorst  ┆ polars │
      │ null      ┆ null   │
      └───────────┴────────┘
  
      Unnamed groups have their numerical position converted to a string:
  
      >>> pattern = r"candidate=(\w+)&ref=(\w+)"
      >>> (
      ...     df.with_columns(
      ...         captures=pl.col("url").str.extract_groups(pattern)
      ...     ).with_columns(name=pl.col("captures").struct["1"].str.to_uppercase())
      ... )
      shape: (3, 3)
      ┌───────────────────────────────────┬───────────────────────┬──────────┐
      │ url                               ┆ captures              ┆ name     │
      │ ---                               ┆ ---                   ┆ ---      │
      │ str                               ┆ struct[2]             ┆ str      │
      ╞═══════════════════════════════════╪═══════════════════════╪══════════╡
      │ http://vote.com/ballon_dor?candi… ┆ {"messi","python"}    ┆ MESSI    │
      │ http://vote.com/ballon_dor?candi… ┆ {"weghorst","polars"} ┆ WEGHORST │
      │ http://vote.com/ballon_dor?error… ┆ {null,null}           ┆ null     │
      └───────────────────────────────────┴───────────────────────┴──────────┘
  
      """
      return wrap_expr(self._pyexpr.str_extract_groups(pattern))
  
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 30 for calling the ExprStringNameSpace obj's underlying member method code with example usage: obj.extract_groups(pattern) and returns: wrap_expr