From a09bc3a404befca197b5d9959a9c62110ee61d77 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sat, 1 Jan 2022 10:37:26 -0800 Subject: bpo-46095: Improve SeqIter documentation. (GH-30316) --- Doc/library/stdtypes.rst | 10 ++++++++++ Doc/reference/compound_stmts.rst | 21 --------------------- 2 files changed, 10 insertions(+), 21 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 9d80661..dc423bf 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -959,6 +959,16 @@ This means that to compare equal, every element must compare equal and the two sequences must be of the same type and have the same length. (For full details see :ref:`comparisons` in the language reference.) +.. index:: + single: loop; over mutable sequence + single: mutable sequence; loop over + +Forward and reversed iterators over mutable sequences access values using an +index. That index will continue to march forward (or backward) even if the +underlying sequence is mutated. The iterator terminates only when an +:exc:`IndexError` or a :exc:`StopIteration` is encountered (or when the index +drops below zero). + Notes: (1) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index cf8ad17..03fc2cb 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -196,27 +196,6 @@ the built-in function :func:`range` returns an iterator of integers suitable to emulate the effect of Pascal's ``for i := a to b do``; e.g., ``list(range(3))`` returns the list ``[0, 1, 2]``. -.. note:: - - .. index:: - single: loop; over mutable sequence - single: mutable sequence; loop over - - There is a subtlety when the sequence is being modified by the loop (this can - only occur for mutable sequences, e.g. lists). An internal counter is used - to keep track of which item is used next, and this is incremented on each - iteration. When this counter has reached the length of the sequence the loop - terminates. This means that if the suite deletes the current (or a previous) - item from the sequence, the next item will be skipped (since it gets the - index of the current item which has already been treated). Likewise, if the - suite inserts an item in the sequence before the current item, the current - item will be treated again the next time through the loop. This can lead to - nasty bugs that can be avoided by making a temporary copy using a slice of - the whole sequence, e.g., :: - - for x in a[:]: - if x < 0: a.remove(x) - .. _try: .. _except: -- cgit v0.12