Author: raymond.hettinger Date: Tue Sep 29 20:56:36 2009 New Revision: 75140 Log: Issue 7008: Better document str.title and show how to work around the apostrophe problem. Modified: python/branches/release31-maint/Doc/library/stdtypes.rst Modified: python/branches/release31-maint/Doc/library/stdtypes.rst ============================================================================== --- python/branches/release31-maint/Doc/library/stdtypes.rst (original) +++ python/branches/release31-maint/Doc/library/stdtypes.rst Tue Sep 29 20:56:36 2009 @@ -1125,8 +1125,28 @@ .. method:: str.title() - Return a titlecased version of the string: words start with uppercase - characters, all remaining cased characters are lowercase. + Return a titlecased version of the string where words start with an uppercase + character and the remaining characters are lowercase. + + The algorithm uses a simple language-independent definition of a word as + groups of consecutive letters. The definition works in many contexts but + it means that apostrophes in contractions and possessives form word + boundaries, which may not be the desired result:: + + >>> "they're bill's friends from the UK".title() + "They'Re Bill'S Friends From The Uk" + + A workaround for apostrophes can be constructed using regular expressions:: + + >>> import re + >>> def titlecase(s): + return re.sub(r"[A-Za-z]+('[A-Za-z]+)?", + lambda mo: mo.group(0)[0].upper() + + mo.group(0)[1:].lower(), + s) + + >>> titlecase("they're bill's friends.") + "They're Bill's Friends." .. method:: str.translate(map)