These two commits do a few things:
1. reformat to 80 cols
2. use the reference-style links where appropriate for improved in-source readability
3. adds a few links, tweaks a couple of words, `3` -> `three`, stuff like that
While the diff is big due to these edits, there's no significant content change.
r? @brson
Before this patch `reserve` function allocated twice as requested
amount elements (not twice as capacity). It leaded to unnecessary
excessive memory usage in scenarios like this:
```
let mut v = Vec::new();
v.push(17);
v.extend(0..10);
println!("{}", v.capacity());
```
`Vec` allocated 22 elements, while it could allocate just 11.
`reserve` function must have a property of keeping `push` operation
cost (which calls `reserve`) `O(1)`. To achieve this `reserve` must
exponentialy grow its capacity when it does reallocation.
There's better strategy to implement `reserve`:
```
let new_capacity = max(current_capacity * 2, requested_capacity);
```
This strategy still guarantees that capacity grows at `O(1)` with
`reserve`, and fixes the issue with `extend`.
Patch imlpements this strategy.
Before this patch `reserve` function allocated twice as requested
amount elements (not twice as capacity). It leaded to unnecessary
excessive memory usage in scenarios like this:
```
let mut v = Vec::new();
v.push(17);
v.extend(0..10);
println!("{}", v.capacity());
```
`Vec` allocated 22 elements, while it could allocate just 11.
`reserve` function must have a property of keeping `push` operation
cost (which calls `reserve`) `O(1)`. To achieve this `reserve` must
exponentialy grow its capacity when it does reallocation.
There's better strategy to implement `reserve`:
```
let new_capacity = max(current_capacity * 2, requested_capacity);
```
This strategy still guarantees that capacity grows at `O(1)` with
`reserve`, and fixes the issue with `extend`.
Patch imlpements this strategy.
This documentation confused me when trying to use truncate on a project. Originally, it was unclear whether truncate removed the last `len` elements, or whether it cut down the vector to be exactly `len` elements long. The example was also ambiguous.
This fixes#29048 (though I think adding better transactional support would be a better fix for that issue, but that is more difficult). It also simplifies region inference and changes the model to a pure data flow one, as discussed in [this internals thread](https://internals.rust-lang.org/t/rough-thoughts-on-the-impl-of-region-inference-mir-etc/2800). I am not 100% sure though if this PR is the right thing to do -- or at least maybe not at this moment, so thoughts on that would be appreciated.
r? @pnkfelix
cc @arielb1
This is two sentences that have been comma spliced, and should
be split with a full stop. (This error made me stop and re-read,
and I submit this as an actual improvement to readability, not
as a grammar weird-o!)
This helps for the case where a match, such as below:
```rust
let foo = match foo {
Some(x) => x,
None => 0
};
```
gets refactored to no longer need the match, but the match keyword has been left accidentally:
```rust
let foo = match foo.unwrap_or(0);
```
This can be hard to spot as the expression grows more complex.
r? @alexcrichton
This documentation confused me when trying to use truncate on a project. Originally, it was unclear whether truncate removed the last `len` elements, or whether it cut down the vector to be exactly `len` elements long. The example was also ambiguous.
This is two sentences that have been comma spliced, and should
be split with a full stop. (This error made me stop and re-read,
and I submit this as an actual improvement to readability, not
as a grammar weird-o!)
I put the reference under the function return operator `->` rather than near the suggested `!` operators as I thought it was more relevant there.
Resolves#29431
…m message
I recently discovered that this is not mentioned in the docs, only in
the examples, and it's not evident for people coming from C++
r? @steveklabnik
