From 81de0d24d589251d9465b3a214a9b9adb3962f4a Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 6 Jan 2008 16:17:56 +0000 Subject: #1582: document __reversed__, patch by Mark Russell. --- Doc/ACKS.txt | 1 + Doc/library/functions.rst | 10 +++++++--- Doc/reference/datamodel.rst | 16 ++++++++++++++++ 3 files changed, 24 insertions(+), 3 deletions(-) diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index 32943bd..7344cf8 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -158,6 +158,7 @@ docs@python.org), and we'll be glad to correct the problem. * Jim Roskind * Guido van Rossum * Donald Wallace Rouse II + * Mark Russell * Nick Russo * Chris Ryland * Constantina S. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 4f86fc7..693af64 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -977,12 +977,16 @@ available. They are listed here in alphabetical order. .. function:: reversed(seq) - Return a reverse :term:`iterator`. *seq* must be an object which supports - the sequence protocol (the :meth:`__len__` method and the :meth:`__getitem__` - method with integer arguments starting at ``0``). + Return a reverse :term:`iterator`. *seq* must be an object which has + a :meth:`__reversed__` method or supports the sequence protocol (the + :meth:`__len__` method and the :meth:`__getitem__` method with integer + arguments starting at ``0``). .. versionadded:: 2.4 + .. versionchanged:: 2.6 + Added the possibility to write a custom :meth:`__reversed__` method. + .. function:: round(x[, n]) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 7ea6ca7..ed05b32 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1796,6 +1796,22 @@ sequences, it should iterate through the values. Iterator objects also need to implement this method; they are required to return themselves. For more information on iterator objects, see :ref:`typeiter`. + +.. method:: object.__reversed__(self) + + Called (if present) by the :func:`reversed` builtin to implement + reverse iteration. It should return a new iterator object that iterates + over all the objects in the container in reverse order. + + If the :meth:`__reversed__` method is not provided, the + :func:`reversed` builtin will fall back to using the sequence protocol + (:meth:`__len__` and :meth:`__getitem__`). Objects should normally + only provide :meth:`__reversed__` if they do not support the sequence + protocol and an efficient implementation of reverse iteration is possible. + + .. versionadded:: 2.6 + + The membership test operators (:keyword:`in` and :keyword:`not in`) are normally implemented as an iteration through a sequence. However, container objects can supply the following special method with a more efficient implementation, which -- cgit v0.12