update titlecase docstrings

pola-rs · Aug 9, 2024 · dae097f · dae097f
1 parent 3438449
commit dae097f
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 15 deletions.
diff --git a/py-polars/polars/expr/string.py b/py-polars/polars/expr/string.py
@@ -447,7 +447,7 @@ def len_chars(self) -> Expr:
 
     def to_uppercase(self) -> Expr:
         """
-        Transform to uppercase variant.
+        Modify the strings to their uppercase equivalent.
 
         Examples
         --------
@@ -467,7 +467,7 @@ def to_uppercase(self) -> Expr:
 
     def to_lowercase(self) -> Expr:
         """
-        Transform to lowercase variant.
+        Modify the strings to their lowercase equivalent.
 
         Examples
         --------
@@ -487,22 +487,37 @@ def to_lowercase(self) -> Expr:
 
     def to_titlecase(self) -> Expr:
         """
-        Transform to titlecase variant.
+        Modify strings to their titlecase equivalent.
+
+        Notes
+        -----
+        This is a form of case transform where the first letter of each word is
+        capitalized, with the rest of the word in lowercase. Non-alphanumeric
+        characters define the word boundaries.
 
         Examples
         --------
         >>> df = pl.DataFrame(
-        ...     {"sing": ["welcome to my world", "THERE'S NO TURNING BACK"]}
+        ...     {
+        ...         "quotes": [
+        ...             "'e.t. phone home'",
+        ...             "you talkin' to me?",
+        ...             "to infinity,and BEYOND!",
+        ...         ]
+        ...     }
         ... )
-        >>> df.with_columns(foo_title=pl.col("sing").str.to_titlecase())
-        shape: (2, 2)
+        >>> df.with_columns(
+        ...     quotes_title=pl.col("quotes").str.to_titlecase(),
+        ... )
+        shape: (3, 2)
         ┌─────────────────────────┬─────────────────────────┐
-        │ sing                    ┆ foo_title               │
+        │ quotes                  ┆ quotes_title            │
         │ ---                     ┆ ---                     │
         │ str                     ┆ str                     │
         ╞═════════════════════════╪═════════════════════════╡
-        │ welcome to my world     ┆ Welcome To My World     │
-        │ THERE'S NO TURNING BACK ┆ There's No Turning Back │
+        │ 'e.t. phone home'       ┆ 'E.T. Phone Home'       │
+        │ you talkin' to me?      ┆ You Talkin' To Me?      │
+        │ to infinity,and BEYOND! ┆ To Infinity,And Beyond! │
         └─────────────────────────┴─────────────────────────┘
         """
         return wrap_expr(self._pyexpr.str_to_titlecase())

diff --git a/py-polars/polars/series/string.py b/py-polars/polars/series/string.py
@@ -1513,17 +1513,31 @@ def to_uppercase(self) -> Series:
 
     def to_titlecase(self) -> Series:
         """
-        Modify the strings to their titlecase equivalent.
+        Modify strings to their titlecase equivalent.
+
+        Notes
+        -----
+        This is a form of case transform where the first letter of each word is
+        capitalized, with the rest of the word in lowercase. Non-alphanumeric
+        characters define the word boundaries.
 
         Examples
         --------
-        >>> s = pl.Series("sing", ["welcome to my world", "THERE'S NO TURNING BACK"])
+        >>> s = pl.Series(
+        ...     "quotes",
+        ...     [
+        ...         "'e.t. phone home'",
+        ...         "you talkin' to me?",
+        ...         "to infinity,and BEYOND!",
+        ...     ],
+        ... )
         >>> s.str.to_titlecase()
-        shape: (2,)
-        Series: 'sing' [str]
+        shape: (3,)
+        Series: 'quotes' [str]
         [
-            "Welcome To My World"
-            "There's No Turning Back"
+            "'E.T. Phone Home'"
+            "You Talkin' To Me?"
+            "To Infinity,And Beyond!"
         ]
         """