L iATddlmZddlmZmZddlmZddlmZGddeeZ y)) annotations)AnyGeneric)is_narwhals_series)SeriesTceZdZddZddZddZddd ddZdd dd Zddd Zd d Z d!d Z ddd"dZ dd#dZ d$dZ d%d&dZd%d&dZddZddZdd'dZdd'dZddZd(dZy ))SeriesStringNamespacec||_yN)_narwhals_series)selfseriess Y/mnt/ssd/data/python-lab/Trading/venv/lib/python3.12/site-packages/narwhals/series_str.py__init__zSeriesStringNamespace.__init__ s &c|jj|jjjj S)aReturn the length of each string as the number of characters. Examples: >>> import polars as pl >>> import narwhals as nw >>> s_native = pl.Series(["foo", "345", None]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.len_chars().to_native() # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: '' [u32] [ 3 3 null ] )r _with_compliant_compliant_seriesstr len_charsr s rrzSeriesStringNamespace.len_chars s;"$$44  ! ! 3 3 7 7 A A C  rc4t|r |jS|Sr )rr)r args r_extract_compliantz(SeriesStringNamespace._extract_compliant"s(:3(?s$$HSHrF)literalnc|jj|jjjj |j ||||S)aReplace 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. Examples: >>> import pandas as pd >>> import narwhals as nw >>> s_native = pd.Series(["123abc", "abc abc123"]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.replace("abc", "").to_native() 0 123 1 abc123 dtype: object )patternrr)r rrrreplacer)r rvaluerrs rr zSeriesStringNamespace.replace%sX*$$44  ! ! 3 3 7 7 ? ?''.TU @   rrc|jj|jjjj |j |||S)arReplace 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. Examples: >>> import pandas as pd >>> import narwhals as nw >>> s_native = pd.Series(["123abc", "abc abc123"]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.replace_all("abc", "").to_native() 0 123 1 123 dtype: object r")r rrr replace_allr)r rr!rs rr$z!SeriesStringNamespace.replace_all@sU($$44  ! ! 3 3 7 7 C C''. D   rNc|jj|jjjj |S)aRemove 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. Examples: >>> import polars as pl >>> import narwhals as nw >>> s_native = pl.Series(["apple", "\nmango"]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.strip_chars().to_native() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [str] [ "apple" "mango" ] )r rrr strip_chars)r characterss rr&z!SeriesStringNamespace.strip_charsZs=&$$44  ! ! 3 3 7 7 C CJ O  rc|jj|jjjj |S)aCheck if string values start with a substring. Arguments: prefix: prefix substring Examples: >>> import pandas as pd >>> import narwhals as nw >>> s_native = pd.Series(["apple", "mango", None]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.starts_with("app").to_native() 0 True 1 False 2 None dtype: object )r rrr starts_with)r prefixs rr)z!SeriesStringNamespace.starts_withqs="$$44  ! ! 3 3 7 7 C CF K  rc|jj|jjjj |S)aCheck if string values end with a substring. Arguments: suffix: suffix substring Examples: >>> import pandas as pd >>> import narwhals as nw >>> s_native = pd.Series(["apple", "mango", None]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.ends_with("ngo").to_native() 0 False 1 True 2 None dtype: object )r rrr ends_with)r suffixs rr,zSeriesStringNamespace.ends_withs="$$44  ! ! 3 3 7 7 A A& I  rc|jj|jjjj ||S)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. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> s_native = pa.chunked_array([["cat", "dog", "rabbit and parrot"]]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.contains("cat|parrot").to_native() # doctest: +ELLIPSIS [ [ true, false, true ] ] r")r rrrcontains)r rrs rr/zSeriesStringNamespace.containssC.$$44  ! ! 3 3 7 7 @ @RY @ Z  rc|jj|jjjj ||S)aCreate subslices of the string values of a Series. 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. Examples: >>> import pandas as pd >>> import narwhals as nw >>> s_native = pd.Series(["pear", None, "papaya"]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.slice(4, 3).to_native() # doctest: +NORMALIZE_WHITESPACE 0 1 None 2 ya dtype: object offsetlengthr rrrslice)r r2r3s rr5zSeriesStringNamespace.slicesG&$$44  ! ! 3 3 7 7 = =f >   rc|jj|jjjj |S)a9Split the string values of a Series by a substring. Arguments: by: Substring to split by. Examples: >>> import polars as pl >>> import narwhals as nw >>> s_native = pl.Series(["foo bar", "foo_bar"]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.split("_").to_native() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [list[str]] [ ["foo bar"] ["foo", "bar"] ] )by)r rrrsplit)r r7s rr8zSeriesStringNamespace.splits@&$$44  ! ! 3 3 7 7 = = = D  rc|jj|jjjj d|S)aTake the first n elements of each string. Arguments: n: Number of elements to take. Negative indexing is supported (see note (1.)) Notes: 1. When the `n` input 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. 2. 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 >>> s_native = pa.chunked_array([["taata", "taatatata", "zukkyun"]]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.head().to_native() # doctest: +ELLIPSIS [ [ "taata", "taata", "zukky" ] ] rr1r4r rs rheadzSeriesStringNamespace.headsB4$$44  ! ! 3 3 7 7 = =Qq = Q  rc|jj|jjjj | dS)aTake the last n elements of each string. Arguments: n: Number of elements to take. Negative indexing is supported (see note (1.)) Notes: 1. When the `n` input 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. 2. 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 >>> s_native = pa.chunked_array([["taata", "taatatata", "zukkyun"]]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.tail().to_native() # doctest: +ELLIPSIS [ [ "taata", "atata", "kkyun" ] ] Nr1r4r:s rtailzSeriesStringNamespace.tailsE4$$44  ! ! 3 3 7 7 = =aRPT = U  rc|jj|jjjj S)u~Transform string to uppercase variant. Notes: The PyArrow backend will convert 'ß' to 'ẞ' instead of 'SS'. For more info see: 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 >>> s_native = pd.Series(["apple", None]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.to_uppercase().to_native() 0 APPLE 1 None dtype: object )r rrr to_uppercasers rr?z"SeriesStringNamespace.to_uppercase"s;$$$44  ! ! 3 3 7 7 D D F  rc|jj|jjjj S)azTransform string to lowercase variant. Examples: >>> import pandas as pd >>> import narwhals as nw >>> s_native = pd.Series(["APPLE", None]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.to_lowercase().to_native() 0 apple 1 None dtype: object )r rrr to_lowercasers rrAz"SeriesStringNamespace.to_lowercase8s;$$44  ! ! 3 3 7 7 D D F  rc|jj|jjjj |S)u1Parse Series with strings to a Series with 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. Examples: >>> import polars as pl >>> import narwhals as nw >>> s_native = pl.Series(["2020-01-01", "2020-01-02"]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.to_datetime( ... format="%Y-%m-%d" ... ).to_native() # doctest: +NORMALIZE_WHITESPACE shape: (2,) Series: '' [datetime[μs]] [ 2020-01-01 00:00:00 2020-01-02 00:00:00 ] format)r rrr to_datetimer rDs rrEz!SeriesStringNamespace.to_datetimeIsAB$$44  ! ! 3 3 7 7 C C6 C R  rc|jj|jjjj |S)aDConvert to date dtype. 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. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> s_native = pa.chunked_array([["2020-01-01", "2020-01-02"]]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.to_date(format="%Y-%m-%d").to_native() # doctest: +ELLIPSIS [ [ 2020-01-01, 2020-01-02 ] ] rC)r rrrto_daterFs rrHzSeriesStringNamespace.to_datens@2$$44  ! ! 3 3 7 7 ? ?v ? N  rc|jj|jjjj S)aModify 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. Word boundaries are defined by non-**alphabetic** characters, matching the behavior of [`str.title`](https://docs.python.org/3/library/stdtypes.html#str.title) Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> s_native = pa.chunked_array( ... [ ... [ ... "'e.t. phone home'", ... "you talkin' to me?", ... "to infinity,and BEYOND!", ... ] ... ] ... ) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.to_titlecase().to_native() # doctest: +ELLIPSIS [ [ "'E.T. Phone Home'", "You Talkin' To Me?", "To Infinity,And Beyond!" ] ] )r rrr to_titlecasers rrJz"SeriesStringNamespace.to_titlecases<B$$44  ! ! 3 3 7 7 D D F  rc|jj|jjjj |S)aMPad strings with zeros on the left. Arguments: width: The target width of the string. If the string is shorter than this width, it will be padded with zeros on the left. Examples: >>> import pandas as pd >>> import narwhals as nw >>> s_native = pd.Series(["+1", "-23", "456", "123456"]) >>> s = nw.from_native(s_native, series_only=True) >>> s.str.zfill(5).to_native() 0 +0001 1 -0023 2 00456 3 123456 dtype: object )r rrrzfill)r widths rrLzSeriesStringNamespace.zfills=$$$44  ! ! 3 3 7 7 = =e D  r)rrreturnNone)rNr)rrrNr) rrr! str | SeriesTrboolrintrNr)rrr!rPrrQrNrr )r' str | NonerNr)r*rrNr)r-rrNr)rrrrQrNr)r2rRr3z int | NonerNr)r7rrNr))rrRrNr)rDrSrNr)rMrRrNr)__name__ __module__ __qualname__rrrr r$r&r)r,r/r5r8r;r=r?rArErHrJrLrrr r s' *IFKUV  #0 >B OR  8FK  #0 >B  4 . * *9> 6 2 . < < , "# J :# J rr N) __future__rtypingrrnarwhals.dependenciesrnarwhals.typingrr rXrrr]s$"4#{ GG,{ r