Fix a misleading statement in Iterator.nth()
#39174
Conversation
|
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). |
|
@rspeer What are your thoughts on bluss' suggestion? |
BurntSushi
added
A-docs
|
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 |
|
It does seem consistent, maybe the PR text can be expanded to say "will be consumed from the iterator". |
|
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.
rspeer
force-pushed
the
iter-nth-doc-fix
branch
from
c136f65
to
11d36ae
Compare
|
Alright, I clarified. I also moved the paragraph down (because it benefits from having already explained that n counts from 0). |
|
@bors: r+ rollup Thanks! |
|
📌 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.