σ
    ΞοhιF  γ                  σx    S SK Jr  S SKJr  S SKJr  S SKJr  \(       a  S SKJr  \" SSS9r " S	 S
\\   5      r	g)ι    )Ϊannotations)ΪTYPE_CHECKING)ΪGeneric)ΪTypeVar)ΪExprΪExprTr   )Ϊboundc                  σκ    \ rS rSrSS jrSS jrSSS.         SS jjrSS.SS	 jjrSSS jjrSS jr	SS jr
SS.SS jjrSS S jjrS!S jrS"S#S jjrS"S#S jjrSS$S jjrSS jrSS jrSrg
)%ΪExprStringNamespaceι   c                σ    Xl         g ©N©Ϊ_expr)ΪselfΪexprs     ΪC/var/www/html/env/lib/python3.13/site-packages/narwhals/expr_str.pyΪ__init__ΪExprStringNamespace.__init__   s    Ψ
σ    c                σl   ^  T R                   R                  U 4S jT R                   R                  5      $ )uΥ  Return the length of each string as the number of characters.

Returns:
    A new expression.

Examples:
    >>> import polars as pl
    >>> import narwhals as nw
    >>> df_native = pl.DataFrame({"words": ["foo", "345", None]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(words_len=nw.col("words").str.len_chars())
    βββββββββββββββββββββββ
    | Narwhals DataFrame  |
    |---------------------|
    |shape: (3, 2)        |
    |βββββββββ¬ββββββββββββ|
    |β words β words_len β|
    |β ---   β ---       β|
    |β str   β u32       β|
    |βββββββββͺββββββββββββ‘|
    |β foo   β 3         β|
    |β 345   β 3         β|
    |β null  β null      β|
    |βββββββββ΄ββββββββββββ|
    βββββββββββββββββββββββ
c                σj   > TR                   R                  U 5      R                  R                  5       $ r   )r   Ϊ_to_compliant_exprΪstrΪ	len_chars©Ϊplxr   s    r   Ϊ<lambda>Ϊ/ExprStringNamespace.len_chars.<locals>.<lambda>-   s#   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧHΡHΤJr   ©r   Ϊ	__class__Ϊ	_metadata©r   s   `r   r   ΪExprStringNamespace.len_chars   s,   ψ π6 zzΧ#Ρ#άJΨJJΧ Ρ σ
π 	
r   Fι   ©ΪliteralΪnc               σ|   ^ ^^^^ T R                   R                  UUUU U4S jT R                   R                  5      $ )uY  Replace first matching regex/literal substring with a new string value.

Arguments:
    pattern: A valid regular expression pattern.
    value: String that will replace the matched substring.
    literal: Treat `pattern` as a literal string.
    n: Number of matches to replace.

Returns:
    A new expression.

Examples:
    >>> import pandas as pd
    >>> import narwhals as nw
    >>> df_native = pd.DataFrame({"foo": ["123abc", "abc abc123"]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(replaced=nw.col("foo").str.replace("abc", ""))
    ββββββββββββββββββββββββ
    |  Narwhals DataFrame  |
    |----------------------|
    |          foo replaced|
    |0      123abc      123|
    |1  abc abc123   abc123|
    ββββββββββββββββββββββββ
c                σn   > TR                   R                  U 5      R                  R                  TTTTS9$ )Nr&   )r   r   r   Ϊreplace)r   r'   r(   Ϊpatternr   Ϊvalues    r   r   Ϊ-ExprStringNamespace.replace.<locals>.<lambda>N   s4   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧFΡFΨ¨°1π Gρ r   r    )r   r,   r-   r'   r(   s   `````r   r+   ΪExprStringNamespace.replace1   s5   ό π8 zzΧ#Ρ#χπ π JJΧ Ρ σ	
π 	
r   ©r'   c               σx   ^ ^^^ T R                   R                  UUU U4S jT R                   R                  5      $ )u6  Replace all matching regex/literal substring with a new string value.

Arguments:
    pattern: A valid regular expression pattern.
    value: String that will replace the matched substring.
    literal: Treat `pattern` as a literal string.

Returns:
    A new expression.

Examples:
    >>> import pandas as pd
    >>> import narwhals as nw
    >>> df_native = pd.DataFrame({"foo": ["123abc", "abc abc123"]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(replaced=nw.col("foo").str.replace_all("abc", ""))
    ββββββββββββββββββββββββ
    |  Narwhals DataFrame  |
    |----------------------|
    |          foo replaced|
    |0      123abc      123|
    |1  abc abc123      123|
    ββββββββββββββββββββββββ
c                σl   > TR                   R                  U 5      R                  R                  TTTS9$ ©Nr0   )r   r   r   Ϊreplace_all)r   r'   r,   r   r-   s    r   r   Ϊ1ExprStringNamespace.replace_all.<locals>.<lambda>n   s2   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧJΡJΨ¨π Kρ r   r    )r   r,   r-   r'   s   ````r   r4   ΪExprStringNamespace.replace_allT   s0   ϋ π2 zzΧ#Ρ#χπ JJΧ Ρ σ	
π 	
r   Nc                σp   ^ ^ T R                   R                  UU 4S jT R                   R                  5      $ )a½  Remove leading and trailing characters.

Arguments:
    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.

Returns:
    A new expression.

Examples:
    >>> import polars as pl
    >>> import narwhals as nw
    >>> df_native = pl.DataFrame({"fruits": ["apple", "\nmango"]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(stripped=nw.col("fruits").str.strip_chars()).to_dict(
    ...     as_series=False
    ... )
    {'fruits': ['apple', '\nmango'], 'stripped': ['apple', 'mango']}
c                σl   > TR                   R                  U 5      R                  R                  T5      $ r   )r   r   r   Ϊstrip_chars)r   Ϊ
charactersr   s    r   r   Ϊ1ExprStringNamespace.strip_chars.<locals>.<lambda>   s%   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧJΡJΘ:ΤVr   r    )r   r:   s   ``r   r9   ΪExprStringNamespace.strip_charst   s,   ω π, zzΧ#Ρ#έVΨJJΧ Ρ σ
π 	
r   c                σp   ^ ^ T R                   R                  UU 4S jT R                   R                  5      $ )u  Check if string values start with a substring.

Arguments:
    prefix: prefix substring

Returns:
    A new expression.

Examples:
    >>> import pandas as pd
    >>> import narwhals as nw
    >>> df_native = pd.DataFrame({"fruits": ["apple", "mango", None]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(has_prefix=nw.col("fruits").str.starts_with("app"))
    βββββββββββββββββββββ
    |Narwhals DataFrame |
    |-------------------|
    |  fruits has_prefix|
    |0  apple       True|
    |1  mango      False|
    |2   None       None|
    βββββββββββββββββββββ
c                σl   > TR                   R                  U 5      R                  R                  T5      $ r   )r   r   r   Ϊstarts_with)r   Ϊprefixr   s    r   r   Ϊ1ExprStringNamespace.starts_with.<locals>.<lambda>¨   s%   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧJΡJΘ6ΤRr   r    )r   r@   s   ``r   r?   ΪExprStringNamespace.starts_with   s,   ω π0 zzΧ#Ρ#έRΨJJΧ Ρ σ
π 	
r   c                σp   ^ ^ T R                   R                  U U4S jT R                   R                  5      $ )u  Check if string values end with a substring.

Arguments:
    suffix: suffix substring

Returns:
    A new expression.

Examples:
    >>> import pandas as pd
    >>> import narwhals as nw
    >>> df_native = pd.DataFrame({"fruits": ["apple", "mango", None]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(has_suffix=nw.col("fruits").str.ends_with("ngo"))
    βββββββββββββββββββββ
    |Narwhals DataFrame |
    |-------------------|
    |  fruits has_suffix|
    |0  apple      False|
    |1  mango       True|
    |2   None       None|
    βββββββββββββββββββββ
c                σl   > TR                   R                  U 5      R                  R                  T5      $ r   )r   r   r   Ϊ	ends_with)r   r   Ϊsuffixs    r   r   Ϊ/ExprStringNamespace.ends_with.<locals>.<lambda>Ε   s%   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧHΡHΘΤPr   r    )r   rF   s   ``r   rE   ΪExprStringNamespace.ends_with¬   s,   ω π0 zzΧ#Ρ#έPΨJJΧ Ρ σ
π 	
r   c               σt   ^ ^^ T R                   R                  UUU 4S jT R                   R                  5      $ )a  Check if string contains a substring that matches a pattern.

Arguments:
    pattern: A Character sequence or valid regular expression pattern.
    literal: If True, treats the pattern as a literal string.
             If False, assumes the pattern is a regular expression.

Returns:
    A new expression.

Examples:
    >>> import pyarrow as pa
    >>> import narwhals as nw
    >>> df_native = pa.table({"pets": ["cat", "dog", "rabbit and parrot"]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(
    ...     default_match=nw.col("pets").str.contains("cat|parrot"),
    ...     case_insensitive_match=nw.col("pets").str.contains("cat|(?i)parrot"),
    ... ).to_native()
    pyarrow.Table
    pets: string
    default_match: bool
    case_insensitive_match: bool
    ----
    pets: [["cat","dog","rabbit and parrot"]]
    default_match: [[true,false,true]]
    case_insensitive_match: [[true,false,true]]
c                σj   > TR                   R                  U 5      R                  R                  TTS9$ r3   )r   r   r   Ϊcontains)r   r'   r,   r   s    r   r   Ϊ.ExprStringNamespace.contains.<locals>.<lambda>η   s0   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧGΡGΨ π Hρ r   r    )r   r,   r'   s   ```r   rK   ΪExprStringNamespace.containsΙ   s0   ϊ π: zzΧ#Ρ#φπ JJΧ Ρ σ	
π 	
r   c                σt   ^ ^^ T R                   R                  UUU 4S jT R                   R                  5      $ )u  Create subslices of the string values of an expression.

Arguments:
    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:
    A new expression.

Examples:
    >>> import pandas as pd
    >>> import narwhals as nw
    >>> df_native = pd.DataFrame({"s": ["pear", None, "papaya"]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(s_sliced=nw.col("s").str.slice(4, length=3))
    ββββββββββββββββββββ
    |Narwhals DataFrame|
    |------------------|
    |        s s_sliced|
    |0    pear         |
    |1    None     None|
    |2  papaya       ya|
    ββββββββββββββββββββ
c                σj   > TR                   R                  U 5      R                  R                  TTS9$ ©N)ΪoffsetΪlength©r   r   r   Ϊslice)r   rR   rQ   r   s    r   r   Ϊ+ExprStringNamespace.slice.<locals>.<lambda>  s0   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧDΡDΨ fπ Eρ r   r    )r   rQ   rR   s   ```r   rT   ΪExprStringNamespace.sliceν   s0   ϊ π4 zzΧ#Ρ#φπ JJΧ Ρ σ	
π 	
r   c                σp   ^ ^ T R                   R                  UU 4S jT R                   R                  5      $ )uz  Split the string values of an expression by a substring.

Arguments:
    by: Substring to split by.

Returns:
    A new expression.

Examples:
    >>> import polars as pl
    >>> import narwhals as nw
    >>> df_native = pl.DataFrame({"s": ["foo bar", "foo_bar"]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(nw.col("s").str.split("_").alias("s_split"))
    ββββββββββββββββββββββββββββββ
    |     Narwhals DataFrame     |
    |----------------------------|
    |shape: (2, 2)               |
    |βββββββββββ¬βββββββββββββββββ|
    |β s       β s_split        β|
    |β ---     β ---            β|
    |β str     β list[str]      β|
    |βββββββββββͺβββββββββββββββββ‘|
    |β foo bar β ["foo bar"]    β|
    |β foo_bar β ["foo", "bar"] β|
    |βββββββββββ΄βββββββββββββββββ|
    ββββββββββββββββββββββββββββββ
c                σh   > TR                   R                  U 5      R                  R                  TS9$ )N)Ϊby)r   r   r   Ϊsplit)r   rY   r   s    r   r   Ϊ+ExprStringNamespace.split.<locals>.<lambda>,  s(   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧDΡDΘΠDΡKr   r    )r   rY   s   ``r   rZ   ΪExprStringNamespace.split  s,   ω π: zzΧ#Ρ#έKΨJJΧ Ρ σ
π 	
r   c                σp   ^ ^ T R                   R                  UU 4S jT R                   R                  5      $ )a¬  Take the first n elements of each string.

Arguments:
    n: Number of elements to take. Negative indexing is **not** supported.

Returns:
    A new expression.

Notes:
    If the length of the string has fewer than `n` characters, the full string is returned.

Examples:
    >>> import pyarrow as pa
    >>> import narwhals as nw
    >>> df_native = pa.table({"lyrics": ["taata", "taatatata", "zukkyun"]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(lyrics_head=nw.col("lyrics").str.head()).to_native()
    pyarrow.Table
    lyrics: string
    lyrics_head: string
    ----
    lyrics: [["taata","taatatata","zukkyun"]]
    lyrics_head: [["taata","taata","zukky"]]
c                σn   > TR                   R                  U 5      R                  R                  ST5      $ )Nr   rS   ©r   r(   r   s    r   r   Ϊ*ExprStringNamespace.head.<locals>.<lambda>J  s'   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧDΡDΐQΘΤJr   r    ©r   r(   s   ``r   ΪheadΪExprStringNamespace.head0  s,   ω π2 zzΧ#Ρ#έJΨJJΧ Ρ σ
π 	
r   c                σp   ^ ^ T R                   R                  UU 4S jT R                   R                  5      $ )a«  Take the last n elements of each string.

Arguments:
    n: Number of elements to take. Negative indexing is **not** supported.

Returns:
    A new expression.

Notes:
    If the length of the string has fewer than `n` characters, the full string is returned.

Examples:
    >>> import pyarrow as pa
    >>> import narwhals as nw
    >>> df_native = pa.table({"lyrics": ["taata", "taatatata", "zukkyun"]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(lyrics_tail=nw.col("lyrics").str.tail()).to_native()
    pyarrow.Table
    lyrics: string
    lyrics_tail: string
    ----
    lyrics: [["taata","taatatata","zukkyun"]]
    lyrics_tail: [["taata","atata","kkyun"]]
c                σl   > TR                   R                  U 5      R                  R                  T* S S9$ rP   rS   r_   s    r   r   Ϊ*ExprStringNamespace.tail.<locals>.<lambda>h  s2   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧDΡDΨr $π Eρ r   r    ra   s   ``r   ΪtailΪExprStringNamespace.tailN  s0   ω π2 zzΧ#Ρ#υπ JJΧ Ρ σ	
π 	
r   c                σp   ^ ^ T R                   R                  UU 4S jT R                   R                  5      $ )u3  Convert to Datetime dtype.

Notes:
    - pandas defaults to nanosecond time unit, Polars to microsecond.
      Prior to pandas 2.0, nanoseconds were the only time unit supported
      in pandas, with no ability to set any other one. The ability to
      set the time unit in pandas, if the version permits, will arrive.
    - timezone-aware strings are all converted to and parsed as UTC.

Warning:
    As different backends auto-infer format in different ways, if `format=None`
    there is no guarantee that the result will be equal.

Arguments:
    format: Format to use for conversion. If set to None (default), the format is
        inferred from the data.

Returns:
    A new expression.

Examples:
    >>> import polars as pl
    >>> import narwhals as nw
    >>> df_native = pl.DataFrame({"a": ["2020-01-01", "2020-01-02"]})
    >>> df = nw.from_native(df_native)
    >>> df.select(nw.col("a").str.to_datetime(format="%Y-%m-%d"))
    βββββββββββββββββββββββββ
    |  Narwhals DataFrame   |
    |-----------------------|
    |shape: (2, 1)          |
    |βββββββββββββββββββββββ|
    |β a                   β|
    |β ---                 β|
    |β datetime[ΞΌs]        β|
    |βββββββββββββββββββββββ‘|
    |β 2020-01-01 00:00:00 β|
    |β 2020-01-02 00:00:00 β|
    |βββββββββββββββββββββββ|
    βββββββββββββββββββββββββ
c                σh   > TR                   R                  U 5      R                  R                  TS9$ )N)Ϊformat)r   r   r   Ϊto_datetime)r   rk   r   s    r   r   Ϊ1ExprStringNamespace.to_datetime.<locals>.<lambda>  s)   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧJΡJΠRXΠJΡYr   r    )r   rk   s   ``r   rl   ΪExprStringNamespace.to_datetimen  s-   ω πR zzΧ#Ρ#έYΨJJΧ Ρ σ
π 	
r   c                σl   ^  T R                   R                  U 4S jT R                   R                  5      $ )u0  Transform string to uppercase variant.

Returns:
    A new expression.

Notes:
    The PyArrow backend will convert 'Γ' to 'αΊ' instead of 'SS'.
    For more info see [the related issue](https://github.com/apache/arrow/issues/34599).
    There may be other unicode-edge-case-related variations across implementations.

Examples:
    >>> import pandas as pd
    >>> import narwhals as nw
    >>> df_native = pd.DataFrame({"fruits": ["apple", None]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(upper_col=nw.col("fruits").str.to_uppercase())
    ββββββββββββββββββββ
    |Narwhals DataFrame|
    |------------------|
    |  fruits upper_col|
    |0  apple     APPLE|
    |1   None      None|
    ββββββββββββββββββββ
c                σj   > TR                   R                  U 5      R                  R                  5       $ r   )r   r   r   Ϊto_uppercaser   s    r   r   Ϊ2ExprStringNamespace.to_uppercase.<locals>.<lambda>Ά  σ#   ψ 

Χ5Ρ5°cΣ:Χ>Ρ>ΧKΡKΤMr   r    r#   s   `r   rq   Ϊ ExprStringNamespace.to_uppercase  s,   ψ π2 zzΧ#Ρ#άMΨJJΧ Ρ σ
π 	
r   c                σl   ^  T R                   R                  U 4S jT R                   R                  5      $ )u7  Transform string to lowercase variant.

Returns:
    A new expression.

Examples:
    >>> import pandas as pd
    >>> import narwhals as nw
    >>> df_native = pd.DataFrame({"fruits": ["APPLE", None]})
    >>> df = nw.from_native(df_native)
    >>> df.with_columns(lower_col=nw.col("fruits").str.to_lowercase())
    ββββββββββββββββββββ
    |Narwhals DataFrame|
    |------------------|
    |  fruits lower_col|
    |0  APPLE     apple|
    |1   None      None|
    ββββββββββββββββββββ
c                σj   > TR                   R                  U 5      R                  R                  5       $ r   )r   r   r   Ϊto_lowercaser   s    r   r   Ϊ2ExprStringNamespace.to_lowercase.<locals>.<lambda>Ο  rs   r   r    r#   s   `r   rw   Ϊ ExprStringNamespace.to_lowercaseΊ  s,   ψ π( zzΧ#Ρ#άMΨJJΧ Ρ σ
π 	
r   r   )r   r   ΪreturnΪNone)rz   r   )
r,   r   r-   r   r'   Ϊboolr(   Ϊintrz   r   )r,   r   r-   r   r'   r|   rz   r   r   )r:   ϊ
str | Nonerz   r   )r@   r   rz   r   )rF   r   rz   r   )r,   r   r'   r|   rz   r   )rQ   r}   rR   z
int | Nonerz   r   )rY   r   rz   r   )ι   )r(   r}   rz   r   )rk   r~   rz   r   )Ϊ__name__Ϊ
__module__Ϊ__qualname__Ϊ__firstlineno__r   r   r+   r4   r9   r?   rE   rK   rT   rZ   rb   rg   rl   rq   rw   Ϊ__static_attributes__© r   r   r   r      s    ττ
πB <AΘ1ρ!
Ψπ!
Ψ#&π!
Ψ48π!
ΨEHπ!
ΰ	υ!
πF HMχ 
φ@
τ6
τ:
π: 9>χ "
φH
τB 
φD
φ<
φ@,
τ\
χ<
r   r   N)
Ϊ
__future__r   Ϊtypingr   r   r   Ϊnarwhals.exprr   r   r   r   r   r   Ϊ<module>r      s5   πέ "ε  έ έ ζέ"αvΡ&τD
' %.υ D
r   