narwhals.Expr.str
contains(pattern, *, literal=False)
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
|
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> data = {"pets": ["cat", "dog", "rabbit and parrot", "dove", None]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... return df.with_columns(
... default_match=nw.col("pets").str.contains("parrot|Dove"),
... case_insensitive_match=nw.col("pets").str.contains("(?i)parrot|Dove"),
... literal_match=nw.col("pets").str.contains(
... "parrot|Dove", literal=True
... ),
... )
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
pets default_match case_insensitive_match literal_match
0 cat False False False
1 dog False False False
2 rabbit and parrot True True False
3 dove False True False
4 None None None None
>>> func(df_pl)
shape: (5, 4)
┌───────────────────┬───────────────┬────────────────────────┬───────────────┐
│ pets ┆ default_match ┆ case_insensitive_match ┆ literal_match │
│ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ bool ┆ bool ┆ bool │
╞═══════════════════╪═══════════════╪════════════════════════╪═══════════════╡
│ cat ┆ false ┆ false ┆ false │
│ dog ┆ false ┆ false ┆ false │
│ rabbit and parrot ┆ true ┆ true ┆ false │
│ dove ┆ false ┆ true ┆ false │
│ null ┆ null ┆ null ┆ null │
└───────────────────┴───────────────┴────────────────────────┴───────────────┘
ends_with(suffix)
Check if string values end with a substring.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
suffix |
str
|
suffix substring |
required |
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> data = {"fruits": ["apple", "mango", None]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... return df.with_columns(has_suffix=nw.col("fruits").str.ends_with("ngo"))
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
fruits has_suffix
0 apple False
1 mango True
2 None None
>>> func(df_pl)
shape: (3, 2)
┌────────┬────────────┐
│ fruits ┆ has_suffix │
│ --- ┆ --- │
│ str ┆ bool │
╞════════╪════════════╡
│ apple ┆ false │
│ mango ┆ true │
│ null ┆ null │
└────────┴────────────┘
head(n=5)
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
|
Notes
If the length of the string has fewer than n
characters, the full string is returned.
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> data = {"lyrics": ["Atatata", "taata", "taatatata", "zukkyun"]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... return df.with_columns(lyrics_head=nw.col("lyrics").str.head())
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
lyrics lyrics_head
0 Atatata Atata
1 taata taata
2 taatatata taata
3 zukkyun zukky
>>> func(df_pl)
shape: (4, 2)
┌───────────┬─────────────┐
│ lyrics ┆ lyrics_head │
│ --- ┆ --- │
│ str ┆ str │
╞═══════════╪═════════════╡
│ Atatata ┆ Atata │
│ taata ┆ taata │
│ taatatata ┆ taata │
│ zukkyun ┆ zukky │
└───────────┴─────────────┘
slice(offset, length=None)
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
|
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> data = {"s": ["pear", None, "papaya", "dragonfruit"]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... return df.with_columns(s_sliced=nw.col("s").str.slice(4, length=3))
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
s s_sliced
0 pear
1 None None
2 papaya ya
3 dragonfruit onf
>>> func(df_pl)
shape: (4, 2)
┌─────────────┬──────────┐
│ s ┆ s_sliced │
│ --- ┆ --- │
│ str ┆ str │
╞═════════════╪══════════╡
│ pear ┆ │
│ null ┆ null │
│ papaya ┆ ya │
│ dragonfruit ┆ onf │
└─────────────┴──────────┘
Using negative indexes:
>>> @nw.narwhalify
... def func(df):
... return df.with_columns(s_sliced=nw.col("s").str.slice(-3))
>>> func(df_pd)
s s_sliced
0 pear ear
1 None None
2 papaya aya
3 dragonfruit uit
>>> func(df_pl)
shape: (4, 2)
┌─────────────┬──────────┐
│ s ┆ s_sliced │
│ --- ┆ --- │
│ str ┆ str │
╞═════════════╪══════════╡
│ pear ┆ ear │
│ null ┆ null │
│ papaya ┆ aya │
│ dragonfruit ┆ uit │
└─────────────┴──────────┘
replace(pattern, value, *, literal=False, n=1)
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
|
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> data = {"foo": ["123abc", "abc abc123"]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... df = df.with_columns(replaced=nw.col("foo").str.replace("abc", ""))
... return df.to_dict(as_series=False)
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
{'foo': ['123abc', 'abc abc123'], 'replaced': ['123', ' abc123']}
>>> func(df_pl)
{'foo': ['123abc', 'abc abc123'], 'replaced': ['123', ' abc123']}
replace_all(pattern, value, *, literal=False)
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
|
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> data = {"foo": ["123abc", "abc abc123"]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... df = df.with_columns(replaced=nw.col("foo").str.replace_all("abc", ""))
... return df.to_dict(as_series=False)
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
{'foo': ['123abc', 'abc abc123'], 'replaced': ['123', ' 123']}
>>> func(df_pl)
{'foo': ['123abc', 'abc abc123'], 'replaced': ['123', ' 123']}
starts_with(prefix)
Check if string values start with a substring.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
prefix |
str
|
prefix substring |
required |
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> data = {"fruits": ["apple", "mango", None]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... return df.with_columns(has_prefix=nw.col("fruits").str.starts_with("app"))
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
fruits has_prefix
0 apple True
1 mango False
2 None None
>>> func(df_pl)
shape: (3, 2)
┌────────┬────────────┐
│ fruits ┆ has_prefix │
│ --- ┆ --- │
│ str ┆ bool │
╞════════╪════════════╡
│ apple ┆ true │
│ mango ┆ false │
│ null ┆ null │
└────────┴────────────┘
strip_chars(characters=None)
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
|
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> data = {"fruits": ["apple", "\nmango"]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... df = df.with_columns(stripped=nw.col("fruits").str.strip_chars())
... return df.to_dict(as_series=False)
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
{'fruits': ['apple', '\nmango'], 'stripped': ['apple', 'mango']}
>>> func(df_pl)
{'fruits': ['apple', '\nmango'], 'stripped': ['apple', 'mango']}
tail(n=5)
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
|
Notes
If the length of the string has fewer than n
characters, the full string is returned.
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> data = {"lyrics": ["Atatata", "taata", "taatatata", "zukkyun"]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... return df.with_columns(lyrics_tail=nw.col("lyrics").str.tail())
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
lyrics lyrics_tail
0 Atatata atata
1 taata taata
2 taatatata atata
3 zukkyun kkyun
>>> func(df_pl)
shape: (4, 2)
┌───────────┬─────────────┐
│ lyrics ┆ lyrics_tail │
│ --- ┆ --- │
│ str ┆ str │
╞═══════════╪═════════════╡
│ Atatata ┆ atata │
│ taata ┆ taata │
│ taatatata ┆ atata │
│ zukkyun ┆ kkyun │
└───────────┴─────────────┘
to_datetime(format)
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.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
format |
str
|
Format to parse strings with. Must be passed, as different dataframe libraries have different ways of auto-inferring formats. |
required |
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> df_pd = pd.DataFrame({"a": ["2020-01-01", "2020-01-02"]})
>>> df_pl = pl.DataFrame({"a": ["2020-01-01", "2020-01-02"]})
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... return df.select(nw.col("a").str.to_datetime(format="%Y-%m-%d"))
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
a
0 2020-01-01
1 2020-01-02
>>> func(df_pl)
shape: (2, 1)
┌─────────────────────┐
│ a │
│ --- │
│ datetime[μs] │
╞═════════════════════╡
│ 2020-01-01 00:00:00 │
│ 2020-01-02 00:00:00 │
└─────────────────────┘
to_lowercase()
Transform string to lowercase variant.
Examples:
>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> data = {"fruits": ["APPLE", "MANGO", None]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... return df.with_columns(lower_col=nw.col("fruits").str.to_lowercase())
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
fruits lower_col
0 APPLE apple
1 MANGO mango
2 None None
>>> func(df_pl)
shape: (3, 2)
┌────────┬───────────┐
│ fruits ┆ lower_col │
│ --- ┆ --- │
│ str ┆ str │
╞════════╪═══════════╡
│ APPLE ┆ apple │
│ MANGO ┆ mango │
│ null ┆ null │
└────────┴───────────┘
to_uppercase()
Transform string to uppercase variant.
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 polars as pl
>>> import narwhals as nw
>>> data = {"fruits": ["apple", "mango", None]}
>>> df_pd = pd.DataFrame(data)
>>> df_pl = pl.DataFrame(data)
We define a dataframe-agnostic function:
>>> @nw.narwhalify
... def func(df):
... return df.with_columns(upper_col=nw.col("fruits").str.to_uppercase())
We can then pass either pandas or Polars to func
:
>>> func(df_pd)
fruits upper_col
0 apple APPLE
1 mango MANGO
2 None None
>>> func(df_pl)
shape: (3, 2)
┌────────┬───────────┐
│ fruits ┆ upper_col │
│ --- ┆ --- │
│ str ┆ str │
╞════════╪═══════════╡
│ apple ┆ APPLE │
│ mango ┆ MANGO │
│ null ┆ null │
└────────┴───────────┘