Document the behaviour of infinite iterators on potentially-computable methods

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.

diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs
index 35cd7441c66bcf4e0ef93706c54d4ada83a6b365..209a22d534a2ed705b1a2f683d11641955538b4a 100644 (file)
--- a/src/libcore/iter/iterator.rs
+++ b/src/libcore/iter/iterator.rs
@@ -24,6 +24,10 @@ fn _assert_is_object_safe(_: &Iterator<Item=()>) {}
 /// 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 06c29b47bf9217db2fe131db59099d0f807e6fc8..3a5a72d1b87c10fcfb1800a2a908a02a61373de7 100644 (file)
--- 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")]