Index: operator.rst
===================================================================
--- operator.rst	(revision 84368)
+++ operator.rst	(working copy)
@@ -22,6 +22,9 @@
 operations, mathematical operations, sequence operations, and abstract type
 tests.
 
+Object comparison
+-----------------
+
 The object comparison functions are useful for all objects, and are named after
 the rich comparison operators they support:
 
@@ -48,6 +51,9 @@
    :ref:`comparisons` for more information about rich comparisons.
 
 
+Logical operations
+------------------
+
 The logical operations are also generally applicable to all objects, and support
 truth tests, identity tests, and boolean operations:
 
@@ -77,6 +83,9 @@
    Return ``a is not b``.  Tests object identity.
 
 
+Mathematical and bitwise operations
+-----------------------------------
+
 The mathematical and bitwise operations are the most numerous:
 
 
@@ -185,6 +194,9 @@
    Return the bitwise exclusive or of *a* and *b*.
 
 
+Sequence operations
+-------------------
+
 Operations which work with sequences (some of them with mappings too) include:
 
 .. function:: concat(a, b)
@@ -226,14 +238,63 @@
 
    Set the value of *a* at index *b* to *c*.
 
+Example: Build a dictionary that maps the ordinals from ``0`` to ``255`` to
+their character equivalents.
 
-Many operations have an "in-place" version.  The following functions provide a
-more primitive access to in-place operators than the usual syntax does; for
-example, the :term:`statement` ``x += y`` is equivalent to
-``x = operator.iadd(x, y)``.  Another way to put it is to say that
-``z = operator.iadd(x, y)`` is equivalent to the compound statement
-``z = x; z += y``.
+   >>> d = {}
+   >>> keys = range(256)
+   >>> vals = map(chr, keys)
+   >>> map(operator.setitem, [d]*len(keys), keys, vals)   # doctest: +SKIP
 
+.. XXX: find a better, readable, example
+
+
+In-place operations
+-------------------
+
+In Python, some types can implement *in-place* addition via the
+:meth:`__iadd__` special method.  The :mod:`operator` module give access to
+this method through the ``operator.iadd(x, y)`` function which is then
+equivalent to ``x.__iadd__(y)``.  In-place operations are only
+possible for mutable types such as lists or dictionaries.  For
+example::
+
+    >>> l = ["spam"]
+    >>> operator.iadd(["eggs"])
+    >>> operator.iadd(l, ["eggs"])
+    ['spam', 'eggs']
+    >>> l
+    ['spam', 'eggs']
+    >>> l is operator.iadd(l, [4, 2])
+    True
+
+The important things to note are that ``x.__iadd__`` is a method that
+mutates *x* and returns *x*.
+
+For immutable types (such as integers, strings or tuples) and types
+which do not implement the :meth:`__iadd__` method, ``operator.iadd(x,
+y)`` falls back to ``x + y``.  Notice the difference with the previous
+example in the following::
+
+    >>> t = ("spam",)
+    >>> operator.iadd(t, ("eggs",))
+    ('spam', 'eggs')
+    >>> t
+    ('spam',)
+    >>> operator.iadd(t, (4, 2)) is t
+    False
+
+In-place operations can be used to obtain the same result as augmented
+assignement (e.g ``x += 2``).  But to achieve this for both mutable
+and immutable objects, one has to write::
+
+    x = operator.iadd(x, 2)
+
+This has no advantage over ``x += 2``.
+
+In-place operations are not limited to addition.  All mathematical and
+bitwise operations can be performed in-place - see the list below.
+
 .. function:: iadd(a, b)
               __iadd__(a, b)
 
@@ -311,16 +372,10 @@
 
    ``a = ixor(a, b)`` is equivalent to ``a ^= b``.
 
-Example: Build a dictionary that maps the ordinals from ``0`` to ``255`` to
-their character equivalents.
 
-   >>> d = {}
-   >>> keys = range(256)
-   >>> vals = map(chr, keys)
-   >>> map(operator.setitem, [d]*len(keys), keys, vals)   # doctest: +SKIP
+Generalized attribute and item lookups
+--------------------------------------
 
-.. XXX: find a better, readable, example
-
 The :mod:`operator` module also defines tools for generalized attribute and item
 lookups.  These are useful for making fast field extractors as arguments for
 :func:`map`, :func:`sorted`, :meth:`itertools.groupby`, or other functions that