Rollup merge of #47547 - varkor:infinite-iterators-warning-doc, r=frewsxcv
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.
This commit is contained in:
commit
4a827188cc
2 changed files with 18 additions and 0 deletions
|
@ -1431,6 +1431,10 @@ pub trait Iterator {
|
||||||
/// Folding is useful whenever you have a collection of something, and want
|
/// Folding is useful whenever you have a collection of something, and want
|
||||||
/// to produce a single value from it.
|
/// to produce a single value from it.
|
||||||
///
|
///
|
||||||
|
/// Note: `fold()`, and similar methods that traverse the entire iterator,
|
||||||
|
/// may not terminate for infinite iterators, even on traits for which a
|
||||||
|
/// result is determinable in finite time.
|
||||||
|
///
|
||||||
/// # Examples
|
/// # Examples
|
||||||
///
|
///
|
||||||
/// Basic usage:
|
/// Basic usage:
|
||||||
|
|
|
@ -298,7 +298,21 @@
|
||||||
//!
|
//!
|
||||||
//! This will print the numbers `0` through `4`, each on their own line.
|
//! 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 determined mathematically 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 not to return
|
||||||
|
//! successfully for any infinite iterators.
|
||||||
|
//!
|
||||||
|
//! ```no_run
|
||||||
|
//! let ones = std::iter::repeat(1);
|
||||||
|
//! let least = ones.min().unwrap(); // Oh no! An infinite loop!
|
||||||
|
//! // `ones.min()` causes an infinite loop, so we won't reach this point!
|
||||||
|
//! println!("The smallest number one is {}.", least);
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
//! [`take`]: trait.Iterator.html#method.take
|
//! [`take`]: trait.Iterator.html#method.take
|
||||||
|
//! [`min`]: trait.Iterator.html#method.min
|
||||||
|
|
||||||
#![stable(feature = "rust1", since = "1.0.0")]
|
#![stable(feature = "rust1", since = "1.0.0")]
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue