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 "inplace" version. The following functions provide a
more primitive access to inplace 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
+
+
+Inplace operations
+
+
+In Python, some types can implement *inplace* 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)``. Inplace 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
+
+Inplace 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``.
+
+Inplace operations are not limited to addition. All mathematical and
+bitwise operations can be performed inplace  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