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 │
└─────────────┴──────────┘
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 │
└────────┴────────────┘
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 │
└─────────────────────┘