Add comments around code where ordering is important due for panic-safety
Iterators contain arbitrary code which may panic. Unsafe code has to be
careful to do its state updates at the right point between calls that may panic.
As requested in https://github.com/rust-lang/rust/pull/86452#discussion_r655153948
r? `@RalfJung`
Iterators contain arbitrary code which may panic. Unsafe code has to be
careful to do its state updates at the right point between calls
that may panic.
Rollup of 11 pull requests
Successful merges:
- #85054 (Revert SGX inline asm syntax)
- #85182 (Move `available_concurrency` implementation to `sys`)
- #86037 (Add `io::Cursor::{remaining, remaining_slice, is_empty}`)
- #86114 (Reopen#79692 (Format symbols under shared frames))
- #86297 (Allow to pass arguments to rustdoc-gui tool)
- #86334 (Resolve type aliases to the type they point to in intra-doc links)
- #86367 (Fix comment about rustc_inherit_overflow_checks in abs().)
- #86381 (Add regression test for issue #39161)
- #86387 (Remove `#[allow(unused_lifetimes)]` which is now unnecessary)
- #86398 (Add regression test for issue #54685)
- #86493 (Say "this enum variant takes"/"this struct takes" instead of "this function takes")
Failed merges:
r? `@ghost`
`@rustbot` modify labels: rollup
Add MIR pass to lower call to `core::slice::len` into `Len` operand
During some larger experiment with range analysis I've found that code like `let l = slice.len()` produces different MIR then one found in bound checks. This optimization pass replaces terminators that are calls to `core::slice::len` with just a MIR operand and Goto terminator.
It uses some heuristics to remove the outer borrow that is made to call `core::slice::len`, but I assume it can be eliminated, just didn't find how.
Would like to express my gratitude to `@oli-obk` who helped me a lot on Zullip
fix panic-safety in specialized Zip::next_back
This was unsound since a panic in a.next_back() would result in the
length not being updated which would then lead to the same element
being revisited in the side-effect preserving code.
fixes#86443
Alter std::cell::Cell::get_mut documentation
I felt that there was some inconsistency between between Cell and RefCell with regards to their `get_mut` method documentation: `RefCell` flags this method as "unusual" in that it takes `&mut self`, while `Cell` does not. I attempted to flag this in `Cell`s documentation as well, and point to `RefCell`s method in the case where it is required.
Find relevant parts of docs and the new version below.
The current docs for `Cell::get_mut`:
> Returns a mutable reference to the underlying data.
This call borrows Cell mutably (at compile-time) which guarantees that we possess the only reference.
And `RefCell::get_mut`:
> Returns a mutable reference to the underlying data.
This call borrows `RefCell` mutably (at compile-time) so there is no need for dynamic checks.
However be cautious: this method expects self to be mutable, which is generally not the case when using a `RefCell`. Take a look at the `borrow_mut` method instead if self isn’t mutable.
Also, please be aware that this method is only for special circumstances and is usually not what you want. In case of doubt, use `borrow_mut` instead.
My attempt to make `Cell::get_mut` clearer:
> Returns a mutable reference to the underlying data.
This call borrows `Cell` mutably (at compile-time) which guaranteesthat we possess the only reference.
However be cautious: this method expects `self` to be mutable, which is generally not the case when using a `Cell`. If you require interior mutability by reference, consider using `RefCell` which provides run-time checked mutable borrows through its `borrow_mut` method.
This was unsound since a panic in a.next_back() would result in the
length not being updated which would then lead to the same element
being revisited in the side-effect preserving code.
Make `sum()` and `product()` documentation hyperlinks refer to `Iterator` methods.
The previous linking seemed confusing: within "the sum() method on iterators", "sum()" was linked to `Sum::sum`, not `Iterator::sum`, even though the sentence is talking about the latter. I have rewritten the sentence to be, I believe, clearer, as well as changing the link destinations; applying the same change to the `Product` documentation as well as `Sum`.
I reviewed other traits in the same module and did not see similar issues, and previewed the results using `./x.py doc library/std`.
This method on the Iterator trait is doc(hidden), and about half of
implementations were doc(hidden). This adds the attribute to the
remaining implementations.
The previous linking seemed confusing: within "the sum() method on
iterators", "sum()" was linked to `Sum::sum`, not `Iterator::sum`, even
though the sentence is talking about the latter.
I have rewritten the sentence to be, I believe, clearer, as well as
changing the link destinations; applying the same change to the
`Product` documentation as well as `Sum`.
Mention the `Borrow` guarantee on the `Hash` implementations for Arrays and `Vec`
To remind people like me who forget about it and send PRs to make them different, and to (probably) get a test failure if the code is changed to no longer uphold it.
Updates `Clone` docs for `Copy` comparison.
Quite a few people (myself included) have come under the impression that the difference between `Copy` and `Clone` is that `Copy` is cheap and `Clone` is expensive, where the actual difference is that `Copy` constrains the type to bit-wise copying, and `Clone` allows for more expensive operations. The source of this misconception is in the `Clone` docs, where the following line is in the description:
> Differs from `Copy` in that `Copy` is implicit and extremely inexpensive, while `Clone` is always explicit and may or may not be expensive.
The `Clone` documentation page also comes up before the `Copy` page on google when searching for "the difference between `Clone` and `Copy`".
This PR updates the documentation to clarify that "extremely inexpensive" means an "inexpensive bit-wise copy" to hopefully prevent future rust users from falling into this misunderstanding.
Integrate binary search codes of binary_search_by and partition_point
For now partition_point has own binary search code piece.
It is because binary_search_by had called the comparer more times and the author (=me) wanted to avoid it.
However, now binary_search_by uses the comparer minimum times. (#74024)
So it's time to integrate them.
The appearance of the codes are a bit different but both use completely same logic.
Stabilize {std, core}::prelude::rust_*.
This stabilizes the `{core, std}::prelude::{rust_2015, rust_2018, rust_2021}` modules.
The usage of these modules as the prelude in those editions was already stabilized. This just stabilizes the modules themselves, making it possible for a user to explicitly refer to them.
Tracking issue: https://github.com/rust-lang/rust/issues/85684
FCP on the RFC that included this finished here: https://github.com/rust-lang/rfcs/pull/3114#issuecomment-840577395
Add functions `Duration::try_from_secs_{f32, f64}`
These functions allow constructing a Duration from a floating point value that could be out of range without panicking.
Tracking issue: #83400
Revert #85176 addition of `clone_from` for `ManuallyDrop`
Forwarding `clone_from` to the inner value changes the observable behavior, as previously the inner value would *not* be dropped by the default implementation.
Frankly, this is a super-niche case, so #85176 is welcome to argue the behavior should be otherwise! But if we overrride it, IMO documenting the behavior would be good.
Example: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2018&gist=c5d0856686fa850c1d7ee16891014efb
Implement nonzero arithmetics for NonZero types.
Hello'all, this is my first PR to this repo.
Non-zero natural numbers are stable by addition/multiplication/exponentiation, so it makes sense to make this arithmetic possible with `NonZeroU*`.
The major pitfall is that overflowing underlying `u*` types possibly lead to underlying `0` values, which break the major invariant of `NonZeroU*`. To accommodate it, only `checked_` and `saturating_` operations are implemented.
Other variants allowing wrapped results like `wrapping_` or `overflowing_` are ruled out *de facto*.
`impl Add<u*> for NonZeroU* { .. }` was considered, as it panics on overflow which enforces the invariant, but it does not so in release mode. I considered forcing `NonZeroU*::add` to panic in release mode by deferring the check to `u*::checked_add`, but this is less explicit for the user than directly using `NonZeroU*::checked_add`.
Following `@Lokathor's` advice on zulip, I have dropped the idea.
`@poliorcetics` on Discord also suggested implementing `_sub` operations, but I'd postpone this to another PR if there is a need for it. My opinion is that it could be useful in some cases, but that it makes less sense because non-null natural numbers are not stable by subtraction even in theory, while the overflowing problem is just about technical implementation.
One thing I don't like is that the type of the `other` arg differs in every implementation: `_add` methods accept any raw positive integer, `_mul` methods only accept non-zero values otherwise the invariant is also broken, and `_pow` only seems to accept `u32` for a reason I ignore but that seems consistent throughout `std`. Maybe there is a better way to harmonize this?
This is it, Iope I haven't forgotten anything and I'll be happy to read your feedback.
std: Stabilize wasm simd intrinsics
This commit performs two changes to stabilize Rust support for
WebAssembly simd intrinsics:
* The stdarch submodule is updated to pull in rust-lang/stdarch#1179.
* The `wasm_target_feature` feature gate requirement for the `simd128`
feature has been removed, stabilizing the name `simd128`.
This should conclude the FCP started on #74372 and...
Closes#74372
This commit performs two changes to stabilize Rust support for
WebAssembly simd intrinsics:
* The stdarch submodule is updated to pull in rust-lang/stdarch#1179.
* The `wasm_target_feature` feature gate requirement for the `simd128`
feature has been removed, stabilizing the name `simd128`.
This should conclude the FCP started on #74372 and...
Closes#74372
to_digit simplification (less jumps)
I just realised we might be able to make use of the fact that changing case in ascii is easy to help simplify to_digit some more.
It looks a bit cleaner and it looks like it's less jumps and there's less instructions in the generated assembly:
https://godbolt.org/z/84Erh5dhz
The benchmarks don't really tell me much. Maybe a slight improvement on the var radix.
Before:
```
test char::methods::bench_to_digit_radix_10 ... bench: 53,819 ns/iter (+/- 8,314)
test char::methods::bench_to_digit_radix_16 ... bench: 57,265 ns/iter (+/- 10,730)
test char::methods::bench_to_digit_radix_2 ... bench: 55,077 ns/iter (+/- 5,431)
test char::methods::bench_to_digit_radix_36 ... bench: 56,549 ns/iter (+/- 3,248)
test char::methods::bench_to_digit_radix_var ... bench: 43,848 ns/iter (+/- 3,189)
test char::methods::bench_to_digit_radix_10 ... bench: 51,707 ns/iter (+/- 10,946)
test char::methods::bench_to_digit_radix_16 ... bench: 52,835 ns/iter (+/- 2,689)
test char::methods::bench_to_digit_radix_2 ... bench: 51,012 ns/iter (+/- 2,746)
test char::methods::bench_to_digit_radix_36 ... bench: 53,210 ns/iter (+/- 8,645)
test char::methods::bench_to_digit_radix_var ... bench: 40,386 ns/iter (+/- 4,711)
test char::methods::bench_to_digit_radix_10 ... bench: 54,088 ns/iter (+/- 5,677)
test char::methods::bench_to_digit_radix_16 ... bench: 55,972 ns/iter (+/- 17,229)
test char::methods::bench_to_digit_radix_2 ... bench: 52,083 ns/iter (+/- 2,425)
test char::methods::bench_to_digit_radix_36 ... bench: 54,132 ns/iter (+/- 1,548)
test char::methods::bench_to_digit_radix_var ... bench: 41,250 ns/iter (+/- 5,299)
```
After:
```
test char::methods::bench_to_digit_radix_10 ... bench: 48,907 ns/iter (+/- 19,449)
test char::methods::bench_to_digit_radix_16 ... bench: 52,673 ns/iter (+/- 8,122)
test char::methods::bench_to_digit_radix_2 ... bench: 48,509 ns/iter (+/- 2,885)
test char::methods::bench_to_digit_radix_36 ... bench: 50,526 ns/iter (+/- 4,610)
test char::methods::bench_to_digit_radix_var ... bench: 38,618 ns/iter (+/- 3,180)
test char::methods::bench_to_digit_radix_10 ... bench: 54,202 ns/iter (+/- 6,994)
test char::methods::bench_to_digit_radix_16 ... bench: 56,585 ns/iter (+/- 8,448)
test char::methods::bench_to_digit_radix_2 ... bench: 50,548 ns/iter (+/- 1,674)
test char::methods::bench_to_digit_radix_36 ... bench: 52,749 ns/iter (+/- 2,576)
test char::methods::bench_to_digit_radix_var ... bench: 40,215 ns/iter (+/- 3,327)
test char::methods::bench_to_digit_radix_10 ... bench: 50,233 ns/iter (+/- 22,272)
test char::methods::bench_to_digit_radix_16 ... bench: 50,841 ns/iter (+/- 19,981)
test char::methods::bench_to_digit_radix_2 ... bench: 50,386 ns/iter (+/- 4,555)
test char::methods::bench_to_digit_radix_36 ... bench: 52,369 ns/iter (+/- 2,737)
test char::methods::bench_to_digit_radix_var ... bench: 40,417 ns/iter (+/- 2,766)
```
I removed the likely as it resulted in a few less instructions. (It's not been in there long - I added it in the last to_digit iteration).
fix off by one in `std::iter::Iterator` documentation
the range `(0..10)` is documented as "The even numbers from zero to ten." - should be ".. to nine".
