From fdfb964a821a2f61353146629977eecafc0aa947 Mon Sep 17 00:00:00 2001 From: varkor Date: Thu, 18 Jan 2018 15:28:10 +0000 Subject: [PATCH] Document the behaviour of infinite iterators on potentially-computable methods MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It’s not entirely clear from the current documentation what behaviour calling a method such as `min` on an infinite iterator like `RangeFrom` is. One might expect this to terminate, but in fact, for infinite iterators, `min` is always nonterminating (at least in the standard library). This adds a quick note about this behaviour for clarification. --- src/libcore/iter/iterator.rs | 4 ++++ src/libcore/iter/mod.rs | 14 ++++++++++++++ 2 files changed, 18 insertions(+) diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs index 35cd7441c66b..209a22d534a2 100644 --- a/src/libcore/iter/iterator.rs +++ b/src/libcore/iter/iterator.rs @@ -24,6 +24,10 @@ fn _assert_is_object_safe(_: &Iterator) {} /// This is the main iterator trait. For more about the concept of iterators /// generally, please see the [module-level documentation]. In particular, you /// may want to know how to [implement `Iterator`][impl]. +/// +/// Note: Methods on infinite iterators that generally require traversing every +/// element to produce a result may not terminate, even on traits for which a +/// result is determinable in finite time. /// /// [module-level documentation]: index.html /// [impl]: index.html#implementing-iterator diff --git a/src/libcore/iter/mod.rs b/src/libcore/iter/mod.rs index 06c29b47bf92..3a5a72d1b87c 100644 --- a/src/libcore/iter/mod.rs +++ b/src/libcore/iter/mod.rs @@ -297,8 +297,22 @@ //! ``` //! //! This will print the numbers `0` through `4`, each on their own line. +//! +//! Bear in mind that methods on infinite iterators, even those for which a +//! result can be computed in finite time, may not terminate. Specifically, +//! methods such as [`min`], which in the general case require traversing +//! every element in the iterator, are likely never to terminate for any +//! infinite iterators. +//! +//! ``` +//! let positives = 1..; +//! let least = positives.min().unwrap(); // Oh no! An infinite loop! +//! // `positives.min` causes an infinite loop, so we won't reach this point! +//! println!("The least positive number is {}.", least); +//! ``` //! //! [`take`]: trait.Iterator.html#method.take +//! [`min`]: trait.Iterator.html#method.min #![stable(feature = "rust1", since = "1.0.0")]