§
    q-Phîn  ã                  ó€   — d dl mZ d dlmZ d dlmZmZ d dlmZ d dl	m
Z
 erd dlmZ d dlmZmZ  G d„ d	¦  «        Zd
S )é    )Úannotations)ÚSequence)ÚTYPE_CHECKINGÚCallable)Úparse_into_expression)Ú	wrap_expr)ÚExpr)ÚIntoExprÚIntoExprColumnc                  ó  — e Zd ZdZdZd=d„Zd>d„Zd>d	„Zd>d
„Zd>d„Z	d?d@d„Z
d?d@d„Zd>d„ZddœdAd„Zd>d„Zd>d„Zd>d„Zd>d„ZdddœdBd„Zd>d„Zd>d „Zd>d!„Zdd"œdCd&„Zd>d'„Zd>d(„Zd)d*œdDd.„Zd>d/„Zd)d0œdEd4„ZdFd6„Z	 dGdHd:„Zd?dId<„Zd7S )JÚExprArrayNameSpacez(Namespace for array related expressions.ÚarrÚexprr	   ÚreturnÚNonec                ó   — |j         | _         d S ©N)Ú_pyexpr)Úselfr   s     úQ/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/polars/expr/array.pyÚ__init__zExprArrayNameSpace.__init__   s   € Ø”|ˆŒˆˆó    c                óN   — t          | j                             ¦   «         ¦  «        S )uò  
        Return the number of elements in each array.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={"a": [[1, 2], [4, 3]]},
        ...     schema={"a": pl.Array(pl.Int64, 2)},
        ... )
        >>> df.select(pl.col("a").arr.len())
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”
        â”‚ a   â”‚
        â”‚ --- â”‚
        â”‚ u32 â”‚
        â•žâ•â•â•â•â•â•¡
        â”‚ 2   â”‚
        â”‚ 2   â”‚
        â””â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_len©r   s    r   ÚlenzExprArrayNameSpace.len   ó    € õ* ˜œ×-Ò-Ñ/Ô/Ñ0Ô0Ð0r   c                óN   — t          | j                             ¦   «         ¦  «        S )uï  
        Compute the min values of the sub-arrays.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={"a": [[1, 2], [4, 3]]},
        ...     schema={"a": pl.Array(pl.Int64, 2)},
        ... )
        >>> df.select(pl.col("a").arr.min())
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”
        â”‚ a   â”‚
        â”‚ --- â”‚
        â”‚ i64 â”‚
        â•žâ•â•â•â•â•â•¡
        â”‚ 1   â”‚
        â”‚ 3   â”‚
        â””â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_minr   s    r   ÚminzExprArrayNameSpace.min-   r   r   c                óN   — t          | j                             ¦   «         ¦  «        S )uï  
        Compute the max values of the sub-arrays.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={"a": [[1, 2], [4, 3]]},
        ...     schema={"a": pl.Array(pl.Int64, 2)},
        ... )
        >>> df.select(pl.col("a").arr.max())
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”
        â”‚ a   â”‚
        â”‚ --- â”‚
        â”‚ i64 â”‚
        â•žâ•â•â•â•â•â•¡
        â”‚ 2   â”‚
        â”‚ 4   â”‚
        â””â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_maxr   s    r   ÚmaxzExprArrayNameSpace.maxD   r   r   c                óN   — t          | j                             ¦   «         ¦  «        S )uï  
        Compute the sum values of the sub-arrays.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={"a": [[1, 2], [4, 3]]},
        ...     schema={"a": pl.Array(pl.Int64, 2)},
        ... )
        >>> df.select(pl.col("a").arr.sum())
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”
        â”‚ a   â”‚
        â”‚ --- â”‚
        â”‚ i64 â”‚
        â•žâ•â•â•â•â•â•¡
        â”‚ 3   â”‚
        â”‚ 7   â”‚
        â””â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_sumr   s    r   ÚsumzExprArrayNameSpace.sum[   r   r   é   ÚddofÚintc                óP   — t          | j                             |¦  «        ¦  «        S )u<  
        Compute the std of the values of the sub-arrays.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={"a": [[1, 2], [4, 3]]},
        ...     schema={"a": pl.Array(pl.Int64, 2)},
        ... )
        >>> df.select(pl.col("a").arr.std())
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a        â”‚
        â”‚ ---      â”‚
        â”‚ f64      â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ 0.707107 â”‚
        â”‚ 0.707107 â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_std©r   r(   s     r   ÚstdzExprArrayNameSpace.stdr   ó"   € õ* ˜œ×-Ò-¨dÑ3Ô3Ñ4Ô4Ð4r   c                óP   — t          | j                             |¦  «        ¦  «        S )uö  
        Compute the var of the values of the sub-arrays.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={"a": [[1, 2], [4, 3]]},
        ...     schema={"a": pl.Array(pl.Int64, 2)},
        ... )
        >>> df.select(pl.col("a").arr.var())
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”
        â”‚ a   â”‚
        â”‚ --- â”‚
        â”‚ f64 â”‚
        â•žâ•â•â•â•â•â•¡
        â”‚ 0.5 â”‚
        â”‚ 0.5 â”‚
        â””â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_varr,   s     r   ÚvarzExprArrayNameSpace.var‰   r.   r   c                óN   — t          | j                             ¦   «         ¦  «        S )uü  
        Compute the median of the values of the sub-arrays.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={"a": [[1, 2], [4, 3]]},
        ...     schema={"a": pl.Array(pl.Int64, 2)},
        ... )
        >>> df.select(pl.col("a").arr.median())
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”
        â”‚ a   â”‚
        â”‚ --- â”‚
        â”‚ f64 â”‚
        â•žâ•â•â•â•â•â•¡
        â”‚ 1.5 â”‚
        â”‚ 3.5 â”‚
        â””â”€â”€â”€â”€â”€â”˜
        )r   r   Ú
arr_medianr   s    r   ÚmedianzExprArrayNameSpace.median    s    € õ* ˜œ×0Ò0Ñ2Ô2Ñ3Ô3Ð3r   F)Úmaintain_orderr5   Úboolc               óP   — t          | j                             |¦  «        ¦  «        S )uÇ  
        Get the unique/distinct values in the array.

        Parameters
        ----------
        maintain_order
            Maintain order of data. This requires more work.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {
        ...         "a": [[1, 1, 2]],
        ...     },
        ...     schema={"a": pl.Array(pl.Int64, 3)},
        ... )
        >>> df.select(pl.col("a").arr.unique())
        shape: (1, 1)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a         â”‚
        â”‚ ---       â”‚
        â”‚ list[i64] â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ [1, 2]    â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Ú
arr_unique)r   r5   s     r   ÚuniquezExprArrayNameSpace.unique·   s"   € õ6 ˜œ×0Ò0°Ñ@Ô@ÑAÔAÐAr   c                óN   — t          | j                             ¦   «         ¦  «        S )uh  
        Count the number of unique values in every sub-arrays.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {
        ...         "a": [[1, 1, 2], [2, 3, 4]],
        ...     },
        ...     schema={"a": pl.Array(pl.Int64, 3)},
        ... )
        >>> df.with_columns(n_unique=pl.col("a").arr.n_unique())
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† n_unique â”‚
        â”‚ ---           â”† ---      â”‚
        â”‚ array[i64, 3] â”† u32      â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ [1, 1, 2]     â”† 2        â”‚
        â”‚ [2, 3, 4]     â”† 3        â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_n_uniquer   s    r   Ún_uniquezExprArrayNameSpace.n_uniqueÔ   s    € õ. ˜œ×2Ò2Ñ4Ô4Ñ5Ô5Ð5r   c                óN   — t          | j                             ¦   «         ¦  «        S )u¹  
        Convert an Array column into a List column with the same inner data type.

        Returns
        -------
        Expr
            Expression of data type :class:`List`.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={"a": [[1, 2], [3, 4]]},
        ...     schema={"a": pl.Array(pl.Int8, 2)},
        ... )
        >>> df.select(pl.col("a").arr.to_list())
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a        â”‚
        â”‚ ---      â”‚
        â”‚ list[i8] â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ [1, 2]   â”‚
        â”‚ [3, 4]   â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_to_listr   s    r   Úto_listzExprArrayNameSpace.to_listí   s    € õ4 ˜œ×1Ò1Ñ3Ô3Ñ4Ô4Ð4r   c                óN   — t          | j                             ¦   «         ¦  «        S )u…  
        Evaluate whether any boolean value is true for every subarray.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={
        ...         "a": [
        ...             [True, True],
        ...             [False, True],
        ...             [False, False],
        ...             [None, None],
        ...             None,
        ...         ]
        ...     },
        ...     schema={"a": pl.Array(pl.Boolean, 2)},
        ... )
        >>> df.with_columns(any=pl.col("a").arr.any())
        shape: (5, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a              â”† any   â”‚
        â”‚ ---            â”† ---   â”‚
        â”‚ array[bool, 2] â”† bool  â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡
        â”‚ [true, true]   â”† true  â”‚
        â”‚ [false, true]  â”† true  â”‚
        â”‚ [false, false] â”† false â”‚
        â”‚ [null, null]   â”† false â”‚
        â”‚ null           â”† null  â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_anyr   s    r   ÚanyzExprArrayNameSpace.any	  ó!   € õ@ ˜œ×-Ò-Ñ/Ô/Ñ0Ô0Ð0r   c                óN   — t          | j                             ¦   «         ¦  «        S )u‡  
        Evaluate whether all boolean values are true for every subarray.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={
        ...         "a": [
        ...             [True, True],
        ...             [False, True],
        ...             [False, False],
        ...             [None, None],
        ...             None,
        ...         ]
        ...     },
        ...     schema={"a": pl.Array(pl.Boolean, 2)},
        ... )
        >>> df.with_columns(all=pl.col("a").arr.all())
        shape: (5, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a              â”† all   â”‚
        â”‚ ---            â”† ---   â”‚
        â”‚ array[bool, 2] â”† bool  â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡
        â”‚ [true, true]   â”† true  â”‚
        â”‚ [false, true]  â”† false â”‚
        â”‚ [false, false] â”† false â”‚
        â”‚ [null, null]   â”† true  â”‚
        â”‚ null           â”† null  â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_allr   s    r   ÚallzExprArrayNameSpace.all+  rC   r   )Ú
descendingÚ
nulls_lastrG   rH   c               óR   — t          | j                             ||¦  «        ¦  «        S )u¸  
        Sort the arrays in this column.

        Parameters
        ----------
        descending
            Sort in descending order.
        nulls_last
            Place null values last.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {
        ...         "a": [[3, 2, 1], [9, 1, 2]],
        ...     },
        ...     schema={"a": pl.Array(pl.Int64, 3)},
        ... )
        >>> df.with_columns(sort=pl.col("a").arr.sort())
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† sort          â”‚
        â”‚ ---           â”† ---           â”‚
        â”‚ array[i64, 3] â”† array[i64, 3] â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ [3, 2, 1]     â”† [1, 2, 3]     â”‚
        â”‚ [9, 1, 2]     â”† [1, 2, 9]     â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        >>> df.with_columns(sort=pl.col("a").arr.sort(descending=True))
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† sort          â”‚
        â”‚ ---           â”† ---           â”‚
        â”‚ array[i64, 3] â”† array[i64, 3] â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ [3, 2, 1]     â”† [3, 2, 1]     â”‚
        â”‚ [9, 1, 2]     â”† [9, 2, 1]     â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_sort)r   rG   rH   s      r   ÚsortzExprArrayNameSpace.sortM  s%   € õP ˜œ×.Ò.¨z¸:ÑFÔFÑGÔGÐGr   c                óN   — t          | j                             ¦   «         ¦  «        S )u˜  
        Reverse the arrays in this column.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {
        ...         "a": [[3, 2, 1], [9, 1, 2]],
        ...     },
        ...     schema={"a": pl.Array(pl.Int64, 3)},
        ... )
        >>> df.with_columns(reverse=pl.col("a").arr.reverse())
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† reverse       â”‚
        â”‚ ---           â”† ---           â”‚
        â”‚ array[i64, 3] â”† array[i64, 3] â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ [3, 2, 1]     â”† [1, 2, 3]     â”‚
        â”‚ [9, 1, 2]     â”† [2, 1, 9]     â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_reverser   s    r   ÚreversezExprArrayNameSpace.reversew  s    € õ. ˜œ×1Ò1Ñ3Ô3Ñ4Ô4Ð4r   c                óN   — t          | j                             ¦   «         ¦  «        S )uô  
        Retrieve the index of the minimal value in every sub-array.

        Returns
        -------
        Expr
            Expression of data type :class:`UInt32` or :class:`UInt64`
            (depending on compilation).

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {
        ...         "a": [[1, 2], [2, 1]],
        ...     },
        ...     schema={"a": pl.Array(pl.Int64, 2)},
        ... )
        >>> df.with_columns(arg_min=pl.col("a").arr.arg_min())
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† arg_min â”‚
        â”‚ ---           â”† ---     â”‚
        â”‚ array[i64, 2] â”† u32     â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•¡
        â”‚ [1, 2]        â”† 0       â”‚
        â”‚ [2, 1]        â”† 1       â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_arg_minr   s    r   Úarg_minzExprArrayNameSpace.arg_min  ó    € õ: ˜œ×1Ò1Ñ3Ô3Ñ4Ô4Ð4r   c                óN   — t          | j                             ¦   «         ¦  «        S )uô  
        Retrieve the index of the maximum value in every sub-array.

        Returns
        -------
        Expr
            Expression of data type :class:`UInt32` or :class:`UInt64`
            (depending on compilation).

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {
        ...         "a": [[1, 2], [2, 1]],
        ...     },
        ...     schema={"a": pl.Array(pl.Int64, 2)},
        ... )
        >>> df.with_columns(arg_max=pl.col("a").arr.arg_max())
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† arg_max â”‚
        â”‚ ---           â”† ---     â”‚
        â”‚ array[i64, 2] â”† u32     â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•¡
        â”‚ [1, 2]        â”† 1       â”‚
        â”‚ [2, 1]        â”† 0       â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_arg_maxr   s    r   Úarg_maxzExprArrayNameSpace.arg_max¯  rR   r   ©Únull_on_oobÚindexúint | IntoExprColumnrW   c               óp   — t          |¦  «        }t          | j                             ||¦  «        ¦  «        S )uk  
        Get the value by index in the sub-arrays.

        So index `0` would return the first item of every sublist
        and index `-1` would return the last item of every sublist
        if an index is out of bounds, it will return a `None`.

        Parameters
        ----------
        index
            Index to return per sub-array
        null_on_oob
            Behavior if an index is out of bounds:
            True -> set as null
            False -> raise an error

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {"arr": [[1, 2, 3], [4, 5, 6], [7, 8, 9]], "idx": [1, -2, 0]},
        ...     schema={"arr": pl.Array(pl.Int32, 3), "idx": pl.Int32},
        ... )
        >>> df.with_columns(get=pl.col("arr").arr.get("idx", null_on_oob=True))
        shape: (3, 3)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”
        â”‚ arr           â”† idx â”† get â”‚
        â”‚ ---           â”† --- â”† --- â”‚
        â”‚ array[i32, 3] â”† i32 â”† i32 â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡
        â”‚ [1, 2, 3]     â”† 1   â”† 2   â”‚
        â”‚ [4, 5, 6]     â”† -2  â”† 5   â”‚
        â”‚ [7, 8, 9]     â”† 0   â”† 7   â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”˜
        )r   r   r   Úarr_get)r   rX   rW   s      r   ÚgetzExprArrayNameSpace.getÎ  s2   € õF & eÑ,Ô,ˆÝ˜œ×-Ò-¨e°[ÑAÔAÑBÔBÐBr   c                ó0   — |                       dd¬¦  «        S )u4  
        Get the first value of the sub-arrays.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {"a": [[1, 2, 3], [4, 5, 6], [7, 8, 9]]},
        ...     schema={"a": pl.Array(pl.Int32, 3)},
        ... )
        >>> df.with_columns(first=pl.col("a").arr.first())
        shape: (3, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† first â”‚
        â”‚ ---           â”† ---   â”‚
        â”‚ array[i32, 3] â”† i32   â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡
        â”‚ [1, 2, 3]     â”† 1     â”‚
        â”‚ [4, 5, 6]     â”† 4     â”‚
        â”‚ [7, 8, 9]     â”† 7     â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”˜
        r   TrV   ©r\   r   s    r   ÚfirstzExprArrayNameSpace.firstô  s   € ð, xŠx˜ tˆxÑ,Ô,Ð,r   c                ó0   — |                       dd¬¦  «        S )u"  
        Get the last value of the sub-arrays.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {"a": [[1, 2, 3], [4, 5, 6], [7, 9, 8]]},
        ...     schema={"a": pl.Array(pl.Int32, 3)},
        ... )
        >>> df.with_columns(last=pl.col("a").arr.last())
        shape: (3, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† last â”‚
        â”‚ ---           â”† ---  â”‚
        â”‚ array[i32, 3] â”† i32  â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡
        â”‚ [1, 2, 3]     â”† 3    â”‚
        â”‚ [4, 5, 6]     â”† 6    â”‚
        â”‚ [7, 9, 8]     â”† 8    â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”˜
        éÿÿÿÿTrV   r^   r   s    r   ÚlastzExprArrayNameSpace.last  s   € ð, xŠx˜¨ˆxÑ-Ô-Ð-r   T)Úignore_nullsÚ	separatorr   rc   c               ót   — t          |d¬¦  «        }t          | j                             ||¦  «        ¦  «        S )u  
        Join all string items in a sub-array and place a separator between them.

        This errors if inner type of array `!= String`.

        Parameters
        ----------
        separator
            string to separate the items with
        ignore_nulls
            Ignore null values (default).

            If set to ``False``, null values will be propagated.
            If the sub-list contains any null values, the output is ``None``.

        Returns
        -------
        Expr
            Expression of data type :class:`String`.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {"s": [["a", "b"], ["x", "y"]], "separator": ["*", "_"]},
        ...     schema={
        ...         "s": pl.Array(pl.String, 2),
        ...         "separator": pl.String,
        ...     },
        ... )
        >>> df.with_columns(join=pl.col("s").arr.join(pl.col("separator")))
        shape: (2, 3)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”
        â”‚ s             â”† separator â”† join â”‚
        â”‚ ---           â”† ---       â”† ---  â”‚
        â”‚ array[str, 2] â”† str       â”† str  â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡
        â”‚ ["a", "b"]    â”† *         â”† a*b  â”‚
        â”‚ ["x", "y"]    â”† _         â”† x_y  â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”˜
        T©Ú
str_as_lit)r   r   r   Úarr_join)r   rd   rc   s      r   ÚjoinzExprArrayNameSpace.join$  s7   € õR *¨)ÀÐEÑEÔEˆ	Ý˜œ×.Ò.¨y¸,ÑGÔGÑHÔHÐHr   c                óN   — t          | j                             ¦   «         ¦  «        S )u¶  
        Returns a column with a separate row for every array element.

        Returns
        -------
        Expr
            Expression with the data type of the array elements.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {"a": [[1, 2, 3], [4, 5, 6]]}, schema={"a": pl.Array(pl.Int64, 3)}
        ... )
        >>> df.select(pl.col("a").arr.explode())
        shape: (6, 1)
        â”Œâ”€â”€â”€â”€â”€â”
        â”‚ a   â”‚
        â”‚ --- â”‚
        â”‚ i64 â”‚
        â•žâ•â•â•â•â•â•¡
        â”‚ 1   â”‚
        â”‚ 2   â”‚
        â”‚ 3   â”‚
        â”‚ 4   â”‚
        â”‚ 5   â”‚
        â”‚ 6   â”‚
        â””â”€â”€â”€â”€â”€â”˜
        )r   r   Úarr_exploder   s    r   ÚexplodezExprArrayNameSpace.explodeP  rR   r   )Únulls_equalÚitemr
   rm   c               ót   — t          |d¬¦  «        }t          | j                             ||¦  «        ¦  «        S )u¾  
        Check if sub-arrays contain the given item.

        Parameters
        ----------
        item
            Item that will be checked for membership
        nulls_equal : bool, default True
            If True, treat null as a distinct value. Null values will not propagate.

        Returns
        -------
        Expr
            Expression of data type :class:`Boolean`.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {"a": [["a", "b"], ["x", "y"], ["a", "c"]]},
        ...     schema={"a": pl.Array(pl.String, 2)},
        ... )
        >>> df.with_columns(contains=pl.col("a").arr.contains("a"))
        shape: (3, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† contains â”‚
        â”‚ ---           â”† ---      â”‚
        â”‚ array[str, 2] â”† bool     â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ ["a", "b"]    â”† true     â”‚
        â”‚ ["x", "y"]    â”† false    â”‚
        â”‚ ["a", "c"]    â”† true     â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        Trf   )r   r   r   Úarr_contains)r   rn   rm   s      r   ÚcontainszExprArrayNameSpace.containso  s7   € õD % T°dÐ;Ñ;Ô;ˆÝ˜œ×2Ò2°4¸ÑEÔEÑFÔFÐFr   Úelementc                ór   — t          |d¬¦  «        }t          | j                             |¦  «        ¦  «        S )u2  
        Count how often the value produced by `element` occurs.

        Parameters
        ----------
        element
            An expression that produces a single value

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {"a": [[1, 2], [1, 1], [2, 2]]}, schema={"a": pl.Array(pl.Int64, 2)}
        ... )
        >>> df.with_columns(number_of_twos=pl.col("a").arr.count_matches(2))
        shape: (3, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† number_of_twos â”‚
        â”‚ ---           â”† ---            â”‚
        â”‚ array[i64, 2] â”† u32            â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ [1, 2]        â”† 1              â”‚
        â”‚ [1, 1]        â”† 0              â”‚
        â”‚ [2, 2]        â”† 2              â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        Trf   )r   r   r   Úarr_count_matches)r   rr   s     r   Úcount_matchesz ExprArrayNameSpace.count_matches”  s4   € õ4 (¨¸DÐAÑAÔAˆÝ˜œ×7Ò7¸Ñ@Ô@ÑAÔAÐAr   NÚfieldsú+Sequence[str] | Callable[[int], str] | Nonec                ó  — t          |t          ¦  «        rPt          |¦  «        }| j                             d¦  «        }t          |¦  «        j                             |¦  «        S | j                             |¦  «        }t          |¦  «        S )uÆ  
        Convert the Series of type `Array` to a Series of type `Struct`.

        Parameters
        ----------
        fields
            If the name and number of the desired fields is known in advance
            a list of field names can be given, which will be assigned by index.
            Otherwise, to dynamically assign field names, a custom function can be
            used; if neither are set, fields will be `field_0, field_1 .. field_n`.

        Examples
        --------
        Convert array to struct with default field name assignment:

        >>> df = pl.DataFrame(
        ...     {"n": [[0, 1, 2], [3, 4, 5]]}, schema={"n": pl.Array(pl.Int8, 3)}
        ... )
        >>> df.with_columns(struct=pl.col("n").arr.to_struct())
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ n            â”† struct    â”‚
        â”‚ ---          â”† ---       â”‚
        â”‚ array[i8, 3] â”† struct[3] â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ [0, 1, 2]    â”† {0,1,2}   â”‚
        â”‚ [3, 4, 5]    â”† {3,4,5}   â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜

        Convert array to struct with field name assignment by function/index:

        >>> df = pl.DataFrame(
        ...     {"n": [[0, 1, 2], [3, 4, 5]]}, schema={"n": pl.Array(pl.Int8, 3)}
        ... )
        >>> df.select(pl.col("n").arr.to_struct(fields=lambda idx: f"n{idx}")).rows(
        ...     named=True
        ... )
        [{'n': {'n0': 0, 'n1': 1, 'n2': 2}}, {'n': {'n0': 3, 'n1': 4, 'n2': 5}}]

        Convert array to struct with field name assignment by
        index from a list of names:

        >>> df.select(pl.col("n").arr.to_struct(fields=["c1", "c2", "c3"])).rows(
        ...     named=True
        ... )
        [{'n': {'c1': 0, 'c2': 1, 'c3': 2}}, {'n': {'c1': 3, 'c2': 4, 'c3': 5}}]
        N)Ú
isinstancer   Úlistr   Úarr_to_structr   ÚstructÚrename_fields)r   rv   Úfield_namesÚpyexprs       r   Ú	to_structzExprArrayNameSpace.to_struct±  sy   € õd fhÑ'Ô'ð 	%Ý˜v™,œ,ˆKØ”\×/Ò/°Ñ5Ô5ˆFÝ˜VÑ$Ô$Ô+×9Ò9¸+ÑFÔFÐFà”\×/Ò/°Ñ7Ô7ˆFÝ˜VÑ$Ô$Ð$r   Únc                ón   — t          |¦  «        }t          | j                             |¦  «        ¦  «        S )u  
        Shift array values by the given number of indices.

        Parameters
        ----------
        n
            Number of indices to shift forward. If a negative value is passed, values
            are shifted in the opposite direction instead.

        Notes
        -----
        This method is similar to the `LAG` operation in SQL when the value for `n`
        is positive. With a negative value for `n`, it is similar to `LEAD`.

        Examples
        --------
        By default, array values are shifted forward by one index.

        >>> df = pl.DataFrame(
        ...     {"a": [[1, 2, 3], [4, 5, 6]]}, schema={"a": pl.Array(pl.Int64, 3)}
        ... )
        >>> df.with_columns(shift=pl.col("a").arr.shift())
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† shift         â”‚
        â”‚ ---           â”† ---           â”‚
        â”‚ array[i64, 3] â”† array[i64, 3] â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ [1, 2, 3]     â”† [null, 1, 2]  â”‚
        â”‚ [4, 5, 6]     â”† [null, 4, 5]  â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜

        Pass a negative value to shift in the opposite direction instead.

        >>> df.with_columns(shift=pl.col("a").arr.shift(-2))
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a             â”† shift           â”‚
        â”‚ ---           â”† ---             â”‚
        â”‚ array[i64, 3] â”† array[i64, 3]   â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ [1, 2, 3]     â”† [3, null, null] â”‚
        â”‚ [4, 5, 6]     â”† [6, null, null] â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   r   Ú	arr_shift)r   r   s     r   ÚshiftzExprArrayNameSpace.shiftë  s0   € õ\ " !Ñ$Ô$ˆÝ˜œ×/Ò/°Ñ2Ô2Ñ3Ô3Ð3r   )r   r	   r   r   )r   r	   )r'   )r(   r)   r   r	   )r5   r6   r   r	   )rG   r6   rH   r6   r   r	   )rX   rY   rW   r6   r   r	   )rd   r   rc   r6   r   r	   )rn   r
   rm   r6   r   r	   )rr   r
   r   r	   r   )rv   rw   r   r	   )r   rY   r   r	   )Ú__name__Ú
__module__Ú__qualname__Ú__doc__Ú	_accessorr   r   r    r#   r&   r-   r1   r4   r9   r<   r?   rB   rF   rK   rN   rQ   rU   r\   r_   rb   ri   rl   rq   ru   r€   r„   © r   r   r   r      s½  € € € € € Ø2Ð2à€Ið$ð $ð $ð $ð1ð 1ð 1ð 1ð.1ð 1ð 1ð 1ð.1ð 1ð 1ð 1ð.1ð 1ð 1ð 1ð.5ð 5ð 5ð 5ð 5ð.5ð 5ð 5ð 5ð 5ð.4ð 4ð 4ð 4ð. 05ð Bð Bð Bð Bð Bð Bð:6ð 6ð 6ð 6ð25ð 5ð 5ð 5ð8 1ð  1ð  1ð  1ðD 1ð  1ð  1ð  1ðD */À5ð (Hð (Hð (Hð (Hð (Hð (HðT5ð 5ð 5ð 5ð25ð 5ð 5ð 5ð>5ð 5ð 5ð 5ð> GLð $Cð $Cð $Cð $Cð $Cð $CðL-ð -ð -ð -ð0.ð .ð .ð .ð0 GKð *Ið *Ið *Ið *Ið *Ið *IðX5ð 5ð 5ð 5ð> ?Cð #Gð #Gð #Gð #Gð #Gð #GðJBð Bð Bð Bð< EIð8%ð 8%ð 8%ð 8%ð 8%ðt/4ð /4ð /4ð /4ð /4ð /4ð /4r   r   N)Ú
__future__r   Úcollections.abcr   Útypingr   r   Úpolars._utils.parser   Úpolars._utils.wrapr   Úpolarsr	   Úpolars._typingr
   r   r   rŠ   r   r   ú<module>r’      sÓ   ðØ "Ð "Ð "Ð "Ð "Ð "à $Ð $Ð $Ð $Ð $Ð $Ø *Ð *Ð *Ð *Ð *Ð *Ð *Ð *à 5Ð 5Ð 5Ð 5Ð 5Ð 5Ø (Ð (Ð (Ð (Ð (Ð (àð 8ØÐÐÐÐÐØ7Ð7Ð7Ð7Ð7Ð7Ð7Ð7ðL4ð L4ð L4ð L4ð L4ñ L4ô L4ð L4ð L4ð L4r   