feat: Add support for {Expr,Series}.str.to_titlecase (#3116)

Co-authored-by: Dan Redding <[email protected]>

---------

Co-authored-by: dangotbanned <[email protected]>

Author: FBruzzesi

docs/api-reference/expr_str.md

@@ -18,6 +18,7 @@
         - to_date
         - to_datetime
         - to_lowercase
+        - to_titlecase
         - to_uppercase
         - zfill
       show_source: false

docs/api-reference/series_str.md

@@ -18,6 +18,7 @@
         - to_date
         - to_datetime
         - to_lowercase
+        - to_titlecase
         - to_uppercase
         - zfill
       show_source: false

narwhals/_arrow/series_str.py

@@ -79,6 +79,9 @@ def to_uppercase(self) -> ArrowSeries:
     def to_lowercase(self) -> ArrowSeries:
         return self.with_native(pc.utf8_lower(self.native))
 
+    def to_titlecase(self) -> ArrowSeries:
+        return self.with_native(pc.utf8_title(self.native))
+
     def zfill(self, width: int) -> ArrowSeries:
         binary_join: Incomplete = pc.binary_join_element_wise
         native = self.native

narwhals/_compliant/any_namespace.py

@@ -100,6 +100,7 @@ def split(self, by: str) -> CompliantT_co: ...
     def to_datetime(self, format: str | None) -> CompliantT_co: ...
     def to_date(self, format: str | None) -> CompliantT_co: ...
     def to_lowercase(self) -> CompliantT_co: ...
+    def to_titlecase(self) -> CompliantT_co: ...
     def to_uppercase(self) -> CompliantT_co: ...
     def zfill(self, width: int) -> CompliantT_co: ...
 

narwhals/_compliant/expr.py

@@ -1156,6 +1156,9 @@ def to_uppercase(self) -> EagerExprT:
     def zfill(self, width: int) -> EagerExprT:
         return self.compliant._reuse_series_namespace("str", "zfill", width=width)
 
+    def to_titlecase(self) -> EagerExprT:
+        return self.compliant._reuse_series_namespace("str", "to_titlecase")
+
 
 class EagerExprStructNamespace(
     EagerExprNamespace[EagerExprT], StructNamespace[EagerExprT], Generic[EagerExprT]

narwhals/_dask/expr_str.py

@@ -113,6 +113,11 @@ def to_lowercase(self) -> DaskExpr:
             lambda expr: expr.str.lower(), "to_lowercase"
         )
 
+    def to_titlecase(self) -> DaskExpr:
+        return self.compliant._with_callable(
+            lambda expr: expr.str.title(), "to_titlecase"
+        )
+
     def zfill(self, width: int) -> DaskExpr:
         return self.compliant._with_callable(
             lambda expr, width: expr.str.zfill(width), "zfill", width=width

narwhals/_duckdb/expr_str.py

@@ -2,11 +2,13 @@
 
 from typing import TYPE_CHECKING
 
-from narwhals._duckdb.utils import F, lit
+from narwhals._duckdb.utils import F, col, concat_str, lit
 from narwhals._sql.expr_str import SQLExprStringNamespace
-from narwhals._utils import not_implemented
+from narwhals._utils import not_implemented, requires
 
 if TYPE_CHECKING:
+    from duckdb import Expression
+
     from narwhals._duckdb.expr import DuckDBExpr
 
 
@@ -27,4 +29,25 @@ def to_date(self, format: str | None) -> DuckDBExpr:
         compliant_expr = self.compliant
         return compliant_expr.cast(compliant_expr._version.dtypes.Date())
 
+    @requires.backend_version((1, 2))
+    def to_titlecase(self) -> DuckDBExpr:
+        from narwhals._duckdb.utils import lambda_expr
+
+        def _to_titlecase(expr: Expression) -> Expression:
+            extract_expr = F(
+                "regexp_extract_all", F("lower", expr), lit(r"[a-z0-9]*[^a-z0-9]*")
+            )
+            elem = col("_")
+            capitalize = lambda_expr(
+                elem,
+                concat_str(
+                    F("upper", F("array_extract", elem, lit(1))),
+                    F("substring", elem, lit(2)),
+                ),
+            )
+            capitalized_expr = F("list_transform", extract_expr, capitalize)
+            return F("list_aggregate", capitalized_expr, lit("string_agg"), lit(""))
+
+        return self.compliant._with_elementwise(_to_titlecase)
+
     replace = not_implemented()

narwhals/_duckdb/utils.py

@@ -5,6 +5,7 @@
 
 import duckdb
 import duckdb.typing as duckdb_dtypes
+from duckdb import Expression
 from duckdb.typing import DuckDBPyType
 
 from narwhals._utils import Version, isinstance_or_issubclass, zip_strict
@@ -13,7 +14,7 @@
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
 
-    from duckdb import DuckDBPyRelation, Expression
+    from duckdb import DuckDBPyRelation
 
     from narwhals._compliant.typing import CompliantLazyFrameAny
     from narwhals._duckdb.dataframe import DuckDBLazyFrame
@@ -50,6 +51,22 @@
 """Alias for `duckdb.FunctionExpression`."""
 
 
+def lambda_expr(
+    params: str | Expression | tuple[Expression, ...], expr: Expression, /
+) -> Expression:
+    """Wraps [`duckdb.LambdaExpression`].
+
+    [`duckdb.LambdaExpression`]: https://duckdb.org/docs/stable/sql/functions/lambda
+    """
+    try:
+        from duckdb import LambdaExpression
+    except ModuleNotFoundError as exc:  # pragma: no cover
+        msg = f"DuckDB>=1.2.0 is required for this operation. Found: DuckDB {duckdb.__version__}"
+        raise NotImplementedError(msg) from exc
+    args = (params,) if isinstance(params, Expression) else params
+    return LambdaExpression(args, expr)
+
+
 def concat_str(*exprs: Expression, separator: str = "") -> Expression:
     """Concatenate many strings, NULL inputs are skipped.
 

narwhals/_ibis/expr_str.py

@@ -81,3 +81,4 @@ def fn(expr: ir.StringColumn) -> ir.DateValue:
         return self.compliant._with_callable(fn)
 
     replace = not_implemented()
+    to_titlecase = not_implemented()

narwhals/_pandas_like/series_str.py

@@ -88,5 +88,8 @@ def to_uppercase(self) -> PandasLikeSeries:
     def to_lowercase(self) -> PandasLikeSeries:
         return self.with_native(self.native.str.lower())
 
+    def to_titlecase(self) -> PandasLikeSeries:
+        return self.with_native(self.native.str.title())
+
     def zfill(self, width: int) -> PandasLikeSeries:
         return self.with_native(self.native.str.zfill(width))