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.
Document the associativity of `Iterator::fold` and
`DoubleEndedIterator::rfold` and add examples demonstrating this.
Add links to direct users to the fold of the opposite associativity.
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
Make minor wording changes in a few places. Move `filter` to the
"transformations" section. Add `zip` methods to the "transformations"
section. Clarify the section about `Option` iterators, and add a section
about collecting into `Option`.
Clarify that for `Result`, `or` and `or_else` can also produce a
`Result` having a different type.
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.
Fix an error in `map_or_else`. Use more descriptive text for
"don't care" in truth tables. Make minor corrections to truth tables.
Rename `makeiter` to `make_iter` in examples.
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
