Uh oh!
There was an error while loading. Please reload this page.
Fix a misleading statement in Iterator.nth() - #39174
Conversation
rust-highfive
commented
Jan 19, 2017
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @BurntSushi (or someone else) soon. If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes. Please see the contribution instructions for more information. |
The nth element itself is not really "consumed" (without redeem) since it is returned. Can we have some explanation in between maybe, for example to clarify that the iterator's state is updated to be as if Edit: Just noticed a wrinkle, it's as if at most n + 1 calls to next had been called (less if the end was reached). |
BurntSushi
commented
Jan 23, 2017
@rspeer What are your thoughts on bluss' suggestion? |
I was making a distinction in the docstring between "consumed" and "discarded"; it seems to me that the returned element is "consumed", in that it's not in the iterator anymore, but only the preceding elements are "discarded". But maybe this is specific Rust terminology that doesn't work like I think. I messed up the distinction I was trying to make when making the initial comment on this PR, incidentally. bluss's clarification that it acts like at most |
bluss
commented
Jan 24, 2017
It does seem consistent, maybe the PR text can be expanded to say "will be consumed from the iterator". |
alexcrichton
commented
Feb 4, 2017
I like the terminology "consumed from the iterator" for this as well, @rspeer want to update the PR? |
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.
c136f65 to
11d36aeComparerspeer
commented
Feb 10, 2017
Alright, I clarified. I also moved the paragraph down (because it benefits from having already explained that n counts from 0). |
alexcrichton
commented
Feb 10, 2017
@bors: r+ rollup Thanks! |
bors
commented
Feb 10, 2017
📌 Commit 11d36ae has been approved by |
…hton 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 (there are 0 preceding elements, and maybe it just peeks at the start of the iterator somehow), so I added a sentence clarifying that it does. I also rephrased it to avoid the stunted "i.e." phrasing.
…hton 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 (there are 0 preceding elements, and maybe it just peeks at the start of the iterator somehow), so I added a sentence clarifying that it does. I also rephrased it to avoid the stunted "i.e." phrasing.
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 (there are 0 preceding elements, and maybe it just peeks at the start of the iterator somehow), so I added a sentence clarifying that it does. I also rephrased it to avoid the stunted "i.e." phrasing.