[Python-checkins] r82845 - in python/branches/release27-maint: Doc/library/stdtypes.rst

[antoine.pitrou]

Author: antoine.pitrou
Date: Mon Jul 12 22:11:52 2010
New Revision: 82845

Log:
Merged revisions 82842 via svnmerge from 
svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r82842 | antoine.pitrou | 2010-07-12 22:01:52 +0200 (lun., 12 juil. 2010) | 3 lines
  
  Fix definition of len() and indexing for memoryview objects (part of #7696).
........


Modified:
   python/branches/release27-maint/   (props changed)
   python/branches/release27-maint/Doc/library/stdtypes.rst

Modified: python/branches/release27-maint/Doc/library/stdtypes.rst
==============================================================================
--- python/branches/release27-maint/Doc/library/stdtypes.rst	(original)
+++ python/branches/release27-maint/Doc/library/stdtypes.rst	Mon Jul 12 22:11:52 2010
@@ -2554,10 +2554,18 @@
    buffer protocol.  Builtin objects that support the buffer protocol include
    :class:`str` and :class:`bytearray` (but not :class:`unicode`).
 
-   ``len(view)`` returns the total number of bytes in the memoryview, *view*.
+   A :class:`memoryview` has the notion of an *element*, which is the
+   atomic memory unit handled by the originating object *obj*.  For many
+   simple types such as :class:`str` and :class:`bytearray`, an element
+   is a single byte, but other third-party types may expose larger elements.
+
+   ``len(view)`` returns the total number of elements in the memoryview,
+   *view*.  The :class:`~memoryview.itemsize` attribute will give you the
+   number of bytes in a single element.
 
    A :class:`memoryview` supports slicing to expose its data.  Taking a single
-   index will return a single byte.  Full slicing will result in a subview::
+   index will return a single element as a :class:`str` object.  Full
+   slicing will result in a subview::
 
       >>> v = memoryview('abcefg')
       >>> v[1]
@@ -2568,12 +2576,8 @@
       <memory at 0x77ab28>
       >>> str(v[1:4])
       'bce'
-      >>> v[3:-1]
-      <memory at 0x744f18>
-      >>> str(v[4:-1])
-      'f'
 
-   If the object the memory view is over supports changing its data, the
+   If the object the memoryview is over supports changing its data, the
    memoryview supports slice assignment::
 
       >>> data = bytearray('abcefg')
@@ -2593,13 +2597,16 @@
 
    Notice how the size of the memoryview object cannot be changed.
 
-
    :class:`memoryview` has two methods:
 
    .. method:: tobytes()
 
       Return the data in the buffer as a bytestring (an object of class
-      :class:`str`).
+      :class:`str`). ::
+
+         >>> m = memoryview("abc")
+         >>> m.tobytes()
+         'abc'
 
    .. method:: tolist()