[Python-checkins] cpython: improve casefold/lower/upper docs

[benjamin.peterson]

http://hg.python.org/cpython/rev/0b5ce36a7a24
changeset:   74515:0b5ce36a7a24
parent:      74513:83e8c3a6a81c
user:        Benjamin Peterson <benjamin at python.org>
date:        Wed Jan 18 23:09:32 2012 -0500
summary:
  improve casefold/lower/upper docs

files:
  Doc/library/stdtypes.rst |  20 ++++++++++++++++++--
  1 files changed, 18 insertions(+), 2 deletions(-)


diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1005,7 +1005,16 @@
 .. method:: str.casefold()
 
    Return a casefolded copy of the string. Casefolded strings may be used for
-   caseless matching. For example, ``"MASSE".casefold() == "maße".casefold()``.
+   caseless matching.
+
+   Casefolding is similar to lowercasing but more aggressive because it is
+   intended to remove all case distinctions in a string. For example, the German
+   lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already
+   lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold`
+   converts it to ``"ss"``.
+
+   The casefolding algorithm is described in section 3.13 of the Unicode
+   Standard.
 
    .. versionadded:: 3.3
 
@@ -1217,6 +1226,9 @@
    Return a copy of the string with all the cased characters [4]_ converted to
    lowercase.
 
+   The lowercasing algorithm used is described in section 3.13 of the Unicode
+   Standard.
+
 
 .. method:: str.lstrip([chars])
 
@@ -1420,7 +1432,11 @@
    Return a copy of the string with all the cased characters [4]_ converted to
    uppercase.  Note that ``str.upper().isupper()`` might be ``False`` if ``s``
    contains uncased characters or if the Unicode category of the resulting
-   character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, titlecase).
+   character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter,
+   titlecase).
+
+   The uppercasing algorithm used is described in section 3.13 of the Unicode
+   Standard.
 
 
 .. method:: str.zfill(width)

-- 
Repository URL: http://hg.python.org/cpython