diff --git a/py-polars/polars/expr/string.py b/py-polars/polars/expr/string.py index c64662458d531..4b476b51c0955 100644 --- 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 index 306188e36b925..53593a64d11f6 100644 --- 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!" ] """