narwhals.Expr.str
contains
contains(pattern: str, *, literal: bool = False) -> ExprT
Check if string contains a substring that matches a pattern.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pattern
|
str
|
A Character sequence or valid regular expression pattern. |
required |
literal
|
bool
|
If True, treats the pattern as a literal string. If False, assumes the pattern is a regular expression. |
False
|
Returns:
| Type | Description |
|---|---|
ExprT
|
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]]
ends_with
ends_with(suffix: str) -> ExprT
Check if string values end with a substring.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
suffix
|
str
|
suffix substring |
required |
Returns:
| Type | Description |
|---|---|
ExprT
|
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|
└───────────────────┘
head
head(n: int = 5) -> ExprT
Take the first n elements of each string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of elements to take. Negative indexing is not supported. |
5
|
Returns:
| Type | Description |
|---|---|
ExprT
|
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"]]
len_chars
len_chars() -> ExprT
Return the length of each string as the number of characters.
Returns:
| Type | Description |
|---|---|
ExprT
|
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 │|
|└───────┴───────────┘|
└─────────────────────┘
replace
replace(
pattern: str,
value: str,
*,
literal: bool = False,
n: int = 1
) -> ExprT
Replace first matching regex/literal substring with a new string value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pattern
|
str
|
A valid regular expression pattern. |
required |
value
|
str
|
String that will replace the matched substring. |
required |
literal
|
bool
|
Treat |
False
|
n
|
int
|
Number of matches to replace. |
1
|
Returns:
| Type | Description |
|---|---|
ExprT
|
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|
└──────────────────────┘
replace_all
replace_all(
pattern: str, value: str, *, literal: bool = False
) -> ExprT
Replace all matching regex/literal substring with a new string value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pattern
|
str
|
A valid regular expression pattern. |
required |
value
|
str
|
String that will replace the matched substring. |
required |
literal
|
bool
|
Treat |
False
|
Returns:
| Type | Description |
|---|---|
ExprT
|
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|
└──────────────────────┘
slice
slice(offset: int, length: int | None = None) -> ExprT
Create subslices of the string values of an expression.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset
|
int
|
Start index. Negative indexing is supported. |
required |
length
|
int | None
|
Length of the slice. If set to |
None
|
Returns:
| Type | Description |
|---|---|
ExprT
|
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|
└──────────────────┘
split
split(by: str) -> ExprT
Split the string values of an expression by a substring.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
by
|
str
|
Substring to split by. |
required |
Returns:
| Type | Description |
|---|---|
ExprT
|
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"] │|
|└─────────┴────────────────┘|
└────────────────────────────┘
starts_with
starts_with(prefix: str) -> ExprT
Check if string values start with a substring.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prefix
|
str
|
prefix substring |
required |
Returns:
| Type | Description |
|---|---|
ExprT
|
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|
└───────────────────┘
strip_chars
strip_chars(characters: str | None = None) -> ExprT
Remove leading and trailing characters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
characters
|
str | None
|
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. |
None
|
Returns:
| Type | Description |
|---|---|
ExprT
|
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']}
tail
tail(n: int = 5) -> ExprT
Take the last n elements of each string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of elements to take. Negative indexing is not supported. |
5
|
Returns:
| Type | Description |
|---|---|
ExprT
|
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"]]
to_datetime
to_datetime(format: str | None = None) -> ExprT
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.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
format
|
str | None
|
Format to use for conversion. If set to None (default), the format is inferred from the data. |
None
|
Returns:
| Type | Description |
|---|---|
ExprT
|
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 │|
|└─────────────────────┘|
└───────────────────────┘
to_lowercase
to_lowercase() -> ExprT
Transform string to lowercase variant.
Returns:
| Type | Description |
|---|---|
ExprT
|
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|
└──────────────────┘
to_uppercase
to_uppercase() -> ExprT
Transform string to uppercase variant.
Returns:
| Type | Description |
|---|---|
ExprT
|
A new expression. |
Notes
The PyArrow backend will convert 'ß' to 'ẞ' instead of 'SS'. For more info see the related issue. 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|
└──────────────────┘