[Python-checkins] r67969 - python/branches/py3k/Doc/library/stdtypes.rst

[georg.brandl]

Author: georg.brandl
Date: Sun Dec 28 00:33:20 2008
New Revision: 67969

Log:
Document bytes.translate().

BTW, having str.maketrans() as a static method and
string.maketrans() as a function that creates translation tables for bytes objects is not very consistent :)


Modified:
   python/branches/py3k/Doc/library/stdtypes.rst

Modified: python/branches/py3k/Doc/library/stdtypes.rst
==============================================================================
--- python/branches/py3k/Doc/library/stdtypes.rst	(original)
+++ python/branches/py3k/Doc/library/stdtypes.rst	Sun Dec 28 00:33:20 2008
@@ -1116,13 +1116,12 @@
 .. method:: str.translate(map)
 
    Return a copy of the *s* where all characters have been mapped through the
-   *map* which must be a dictionary of Unicode ordinals(integers) to Unicode
+   *map* which must be a dictionary of Unicode ordinals (integers) to Unicode
    ordinals, strings or ``None``.  Unmapped characters are left untouched.
    Characters mapped to ``None`` are deleted.
 
-   You can use :meth:`str.maketrans` to create a translation table.  For string
-   objects, set the *table* argument to ``None`` for translations that only
-   delete characters:
+   You can use :meth:`str.maketrans` to create a translation map from
+   character-to-character mappings in different formats.
 
    .. note::
 
@@ -1525,23 +1524,23 @@
    >>> bytes.fromhex('f0 f1f2  ')
    b'\xf0\xf1\xf2'
 
-.. XXX verify/document translate() semantics!
-
-   .. method:: bytes.translate(table[, delete])
+The translate method differs in semantics from the version available on strings:
+   
+.. method:: bytes.translate(table[, delete])
 
-   Return a copy of the bytes object where all bytes occurring in the optional
-   argument *delete* are removed, and the remaining bytes have been mapped
-   through the given translation table, which must be a bytes object of length
-   256.
+   Return a copy of the bytes or bytearray object where all bytes occurring in
+   the optional argument *delete* are removed, and the remaining bytes have been
+   mapped through the given translation table, which must be a bytes object of
+   length 256.
 
-   You can use the :func:`maketrans` helper function in the :mod:`string` module to
-   create a translation table.
+   You can use the :func:`string.maketrans` helper function to create a
+   translation table.
 
-   .. XXX a None table doesn't seem to be supported
-      Set the *table* argument to ``None`` for translations that only delete characters::
+   Set the *table* argument to ``None`` for translations that only delete
+   characters::
 
-         >>> 'read this short text'.translate(None, 'aeiou')
-         'rd ths shrt txt'
+      >>> b'read this short text'.translate(None, b'aeiou')
+      b'rd ths shrt txt'
 
 
 .. _types-set: