From 5cc5e0851e5bd14b9855462408ecb9058ed5eaad Mon Sep 17 00:00:00 2001 From: Rob Speer Date: Thu, 19 Jan 2017 02:51:29 -0500 Subject: [PATCH 1/3] Fix a misleading statement in `Iterator.nth()` The `Iterator.nth()` documentation says "Note that all preceding elements will be consumed". I assumed from that that the preceding elements would be the *only* ones that were consumed, but in fact the returned element is consumed as well. The way I read the documentation, I assumed that `nth(0)` would not discard anything (as there are 0 preceding elements), so I added a sentence clarifying that it does. I also rephrased it to avoid the stunted "i.e." phrasing. --- src/libcore/iter/iterator.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs index 3b406873d4b19..0e14a93d25396 100644 --- a/src/libcore/iter/iterator.rs +++ b/src/libcore/iter/iterator.rs @@ -209,7 +209,10 @@ pub trait Iterator { /// Returns the `n`th element of the iterator. /// - /// Note that all preceding elements will be consumed (i.e. discarded). + /// Note that all preceding elements, as well as the returned element, will be + /// consumed. That means that the preceding elements will be discarded, and also + /// that calling `nth(0)` multiple times on the same iterator will return different + /// objects. /// /// Like most indexing operations, the count starts from zero, so `nth(0)` /// returns the first value, `nth(1)` the second, and so on. From ebf29ef0733ec0ac13ef16eb42bac17e3b94da3c Mon Sep 17 00:00:00 2001 From: Rob Speer Date: Thu, 19 Jan 2017 02:53:33 -0500 Subject: [PATCH 2/3] Rephrase my proposed edit ("objects" -> "elements") --- src/libcore/iter/iterator.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs index 0e14a93d25396..4a8c8b53a8c29 100644 --- a/src/libcore/iter/iterator.rs +++ b/src/libcore/iter/iterator.rs @@ -212,7 +212,7 @@ pub trait Iterator { /// Note that all preceding elements, as well as the returned element, will be /// consumed. That means that the preceding elements will be discarded, and also /// that calling `nth(0)` multiple times on the same iterator will return different - /// objects. + /// elements. /// /// Like most indexing operations, the count starts from zero, so `nth(0)` /// returns the first value, `nth(1)` the second, and so on. From 11d36aec8317dba64e30b98aad75c70e4eed6b3e Mon Sep 17 00:00:00 2001 From: Rob Speer Date: Fri, 10 Feb 2017 01:35:29 -0500 Subject: [PATCH 3/3] iterator docs: Move paragraph about discarding; clarify "consumed" --- src/libcore/iter/iterator.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs index 4a8c8b53a8c29..d41767cce18fe 100644 --- a/src/libcore/iter/iterator.rs +++ b/src/libcore/iter/iterator.rs @@ -209,14 +209,14 @@ pub trait Iterator { /// Returns the `n`th element of the iterator. /// - /// Note that all preceding elements, as well as the returned element, will be - /// consumed. That means that the preceding elements will be discarded, and also - /// that calling `nth(0)` multiple times on the same iterator will return different - /// elements. - /// /// Like most indexing operations, the count starts from zero, so `nth(0)` /// returns the first value, `nth(1)` the second, and so on. /// + /// Note that all preceding elements, as well as the returned element, will be + /// consumed from the iterator. That means that the preceding elements will be + /// discarded, and also that calling `nth(0)` multiple times on the same iterator + /// will return different elements. + /// /// `nth()` will return [`None`] if `n` is greater than or equal to the length of the /// iterator. ///