1698773263
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
|
||
|---|---|---|
| .. | ||
| alloc | ||
| backtrace@af078ecc0b | ||
| core | ||
| panic_abort | ||
| panic_unwind | ||
| proc_macro | ||
| profiler_builtins | ||
| rtstartup | ||
| rustc-std-workspace-alloc | ||
| rustc-std-workspace-core | ||
| rustc-std-workspace-std | ||
| std | ||
| stdarch@777efaf564 | ||
| term | ||
| test | ||
| unwind | ||