std::iter: document iteration over &T and &mut T
#79360
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
A colleague of mine is new to Rust, and mentioned that it was “slightly
confusing” to figure out what `&mut` does in iterating over `&mut foo`:
```rust
for value in &mut self.my_vec {
// ...
}
```
My colleague had read the `std::iter` docs and not found the answer
there. There is a brief section at the top about “the three forms of
iteration”, which mentions `iter_mut`, but it doesn’t cover the purpose
of `&mut coll` for a collection `coll`. This patch adds an explanatory
section to the docs. I opted to create a new section so that it can
appear after the note that `impl<I: Iterator> IntoIterator for I`, and
it’s nice for the existing “three forms of iteration” to appear near the
top.
Implementation note: I haven’t linkified the references to `HashSet` and
`HashMap`, since those are in `std` and these docs are in `core`;
linkifying them gave an “unresolved link” rustdoc error.
Test Plan:
Ran `./x.py doc library/core`, and the result looked good. Manually
copy-pasted the two doctests into the playground and ran them.
wchargin-branch: doc-iter-by-reference
wchargin-source: 0f35369a8a735868621166608797744e97536792
|
(rust_highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
|
@rustbot modify labels +T-doc |
rustbot
added
the
A-docs
camelid
added
A-iterators
|
This seems good! |
jyn514
reviewed
Nov 23, 2020
wchargin-branch: doc-iter-by-reference wchargin-source: e4069ac9a9d73860467cea74cf3ae1605af37d74
crlf0710
added
S-waiting-on-review
|
r? @KodrAus |
|
This is great, thanks! @bors r+ rollup |
|
📌 Commit 6edc90a has been approved by |
bors
added
S-waiting-on-bors
@wchargin Btw, I don't think you should worry about testing manually! CI should run the equivalent for you. |
Dylan-DPC-zz
pushed a commit
to Dylan-DPC-zz/rust
that referenced
this pull request
Dec 12, 2020
…ence, r=m-ou-se
std::iter: document iteration over `&T` and `&mut T`
A colleague of mine is new to Rust, and mentioned that it was “slightly
confusing” to figure out what `&mut` does in iterating over `&mut foo`:
```rust
for value in &mut self.my_vec {
// ...
}
```
My colleague had read the `std::iter` docs and not found the answer
there. There is a brief section at the top about “the three forms of
iteration”, which mentions `iter_mut`, but it doesn’t cover the purpose
of `&mut coll` for a collection `coll`. This patch adds an explanatory
section to the docs. I opted to create a new section so that it can
appear after the note that `impl<I: Iterator> IntoIterator for I`, and
it’s nice for the existing “three forms of iteration” to appear near the
top.
Test Plan:
Ran `./x.py doc library/core`, and the result looked good, including
links. Manually copy-pasted the two doctests into the playground and ran
them.
wchargin-branch: doc-iter-by-reference
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Dec 13, 2020
Rollup of 12 pull requests Successful merges: - rust-lang#79360 (std::iter: document iteration over `&T` and `&mut T`) - rust-lang#79398 (Link loop/for keyword) - rust-lang#79834 (Remove deprecated linked_list_extras methods.) - rust-lang#79845 (Fix rustup support in default_build_triple for python3) - rust-lang#79940 (fix more clippy::complexity findings) - rust-lang#79942 (Add post-init hook for static memory for miri.) - rust-lang#79954 (Fix building compiler docs with stage 0) - rust-lang#79963 (Fix typo in `DebruijnIndex` documentation) - rust-lang#79970 (Misc rustbuild improvements when the LLVM backend isn't used) - rust-lang#79973 (rustdoc light theme: Fix CSS for selected buttons) - rust-lang#79984 (Remove an unused dependency that made `rustdoc` crash) - rust-lang#79985 (Fixes submit event of the search input) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
A colleague of mine is new to Rust, and mentioned that it was “slightly
confusing” to figure out what
&mutdoes in iterating over&mut foo:My colleague had read the
std::iterdocs and not found the answerthere. There is a brief section at the top about “the three forms of
iteration”, which mentions
iter_mut, but it doesn’t cover the purposeof
&mut collfor a collectioncoll. This patch adds an explanatorysection to the docs. I opted to create a new section so that it can
appear after the note that
impl<I: Iterator> IntoIterator for I, andit’s nice for the existing “three forms of iteration” to appear near the
top.
Test Plan:
Ran
./x.py doc library/core, and the result looked good, includinglinks. Manually copy-pasted the two doctests into the playground and ran
them.
wchargin-branch: doc-iter-by-reference