feat: add str.len_chars

docs/api-reference/expr_str.md

@@ -7,6 +7,7 @@
         - contains
         - ends_with
         - head
+        - len_chars
         - slice
         - replace
         - replace_all

docs/api-reference/series_str.md

@@ -7,6 +7,7 @@
         - contains
         - ends_with
         - head
+        - len_chars
         - replace
         - replace_all
         - slice

narwhals/_arrow/expr.py

@@ -429,6 +429,9 @@ class ArrowExprStringNamespace:
     def __init__(self, expr: ArrowExpr) -> None:
         self._expr = expr
 
+    def len_chars(self) -> ArrowExpr:
+        return reuse_series_namespace_implementation(self._expr, "str", "len_chars")
+
     def replace(
         self,
         pattern: str,

narwhals/_arrow/series.py

@@ -942,6 +942,13 @@ class ArrowSeriesStringNamespace:
     def __init__(self: Self, series: ArrowSeries) -> None:
         self._arrow_series = series
 
+    def len_chars(self) -> ArrowSeries:
+        import pyarrow.compute as pc  # ignore-banned-import()
+
+        return self._arrow_series._from_native_series(
+            pc.utf8_length(self._arrow_series._native_series)
+        )
+
     def replace(
         self, pattern: str, value: str, *, literal: bool = False, n: int = 1
     ) -> ArrowSeries:

narwhals/_dask/expr.py

@@ -695,6 +695,11 @@ class DaskExprStringNamespace:
     def __init__(self, expr: DaskExpr) -> None:
         self._expr = expr
 
+    def len_chars(self) -> DaskExpr:
+        return self._expr._from_call(
+            lambda _input: _input.str.len(), "len", returns_scalar=False
+        )
+
     def replace(
         self,
         pattern: str,

narwhals/_pandas_like/expr.py

@@ -380,6 +380,11 @@ class PandasLikeExprStringNamespace:
     def __init__(self, expr: PandasLikeExpr) -> None:
         self._expr = expr
 
+    def len_chars(
+        self,
+    ) -> PandasLikeExpr:
+        return reuse_series_namespace_implementation(self._expr, "str", "len_chars")
+
     def replace(
         self,
         pattern: str,

narwhals/_pandas_like/series.py

@@ -693,6 +693,11 @@ class PandasLikeSeriesStringNamespace:
     def __init__(self, series: PandasLikeSeries) -> None:
         self._pandas_series = series
 
+    def len_chars(self) -> PandasLikeSeries:
+        return self._pandas_series._from_native_series(
+            self._pandas_series._native_series.str.len()
+        )
+
     def replace(
         self, pattern: str, value: str, *, literal: bool = False, n: int = 1
     ) -> PandasLikeSeries:

narwhals/expr.py

@@ -2021,6 +2021,50 @@ class ExprStringNamespace:
     def __init__(self, expr: Expr) -> None:
         self._expr = expr
 
+    def len_chars(self) -> Expr:
+        r"""
+        Return the length of each string as the number of characters.
+
+        Examples:
+            >>> import pandas as pd
+            >>> import polars as pl
+            >>> import narwhals as nw
+            >>> data = {"words": ["foo", "Café", "345", "東京", 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(words_len=nw.col("words").str.len_chars())
+
+            We can then pass either pandas or Polars to `func`:
+
+            >>> func(df_pd)
+              words  words_len
+            0   foo        3.0
+            1  Café        4.0
+            2   345        3.0
+            3    東京        2.0
+            4  None        NaN
+
+            >>> func(df_pl)
+            shape: (5, 2)
+            ┌───────┬───────────┐
+            │ words ┆ words_len │
+            │ ---   ┆ ---       │
+            │ str   ┆ u32       │
+            ╞═══════╪═══════════╡
+            │ foo   ┆ 3         │
+            │ Café  ┆ 4         │
+            │ 345   ┆ 3         │
+            │ 東京  ┆ 2         │
+            │ null  ┆ null      │
+            └───────┴───────────┘
+        """
+        return self._expr.__class__(lambda plx: self._expr._call(plx).str.len_chars())
+
     def replace(
         self, pattern: str, value: str, *, literal: bool = False, n: int = 1
     ) -> Expr:

narwhals/series.py

@@ -2467,6 +2467,49 @@ class SeriesStringNamespace:
     def __init__(self, series: Series) -> None:
         self._narwhals_series = series
 
+    def len_chars(self) -> Series:
+        r"""
+        Return the length of each string as the number of characters.
+
+        Examples:
+            >>> import pandas as pd
+            >>> import polars as pl
+            >>> import narwhals as nw
+            >>> data = ["foo", "Café", "345", "東京", None]
+            >>> s_pd = pd.Series(data)
+            >>> s_pl = pl.Series(data)
+
+            We define a dataframe-agnostic function:
+
+            >>> @nw.narwhalify
+            ... def func(s):
+            ...     return s.str.len_chars()
+
+            We can then pass either pandas or Polars to `func`:
+
+            >>> func(s_pd)
+            0    3.0
+            1    4.0
+            2    3.0
+            3    2.0
+            4    NaN
+            dtype: float64
+
+            >>> func(s_pl)  # doctest: +NORMALIZE_WHITESPACE
+            shape: (5,)
+            Series: '' [u32]
+            [
+               3
+               4
+               3
+               2
+               null
+            ]
+        """
+        return self._narwhals_series._from_compliant_series(
+            self._narwhals_series._compliant_series.str.len_chars()
+        )
+
     def replace(
         self, pattern: str, value: str, *, literal: bool = False, n: int = 1
     ) -> Series:

tests/expr_and_series/str/len_chars_test.py

@@ -0,0 +1,25 @@
+from typing import Any
+
+import narwhals.stable.v1 as nw
+from tests.utils import Constructor
+from tests.utils import compare_dicts
+
+data = {"a": ["foo", "foobar", "Café", "345", "東京"]}
+
+
+def test_str_len_chars(constructor: Constructor) -> None:
+    df = nw.from_native(constructor(data))
+    result = df.select(nw.col("a").str.len_chars())
+    expected = {
+        "a": [3, 6, 4, 3, 2],
+    }
+    compare_dicts(result, expected)
+
+
+def test_str_len_chars_series(constructor_eager: Any) -> None:
+    df = nw.from_native(constructor_eager(data), eager_only=True)
+    expected = {
+        "a": [3, 6, 4, 3, 2],
+    }
+    result = df.select(df["a"].str.len_chars())
+    compare_dicts(result, expected)