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`.
Link reference in `dyn` keyword documentation
The "read more" sentence formatted "object safety" as inline code
instead of providing a link to more information. This PR adds a link
to the Reference about this matter, as well as the page regarding trait
objects.
---
We could also put these links in the very first line (instead of the link to the
Book) and in the first paragraph which mentions the "object safe" requirement.
Personally, I think it's good to keep the link to the Book up-front as it's more
accessible than the Reference.
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.
optimize Eq implementation for paths
Filesystems generally have a tree-ish structure which means paths are more likely to share a prefix than a suffix. Absolute paths are especially prone to share long prefixes.
quick benchmark consisting of a search through through a vec containing the absolute paths of all (1850) files in `compiler/`:
```
# old
test path::tests::bench_path_cmp ... bench: 227,407 ns/iter (+/- 2,162)
# new
test path::tests::bench_path_cmp ... bench: 64,976 ns/iter (+/- 1,142)
```
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.
Remove `Ipv6Addr::is_unicast_site_local`
Removes the unstable method `Ipv6Addr::is_unicast_site_local`, see also #85604 where I have tried to summarize related discussion so far.
Unicast site-local addresses (`fec0::/10`) were deprecated in [IETF RFC #3879](https://datatracker.ietf.org/doc/html/rfc3879), see also [RFC #4291 Section 2.5.7](https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.7). Any new implementation must no longer support the special behaviour of site-local addresses. This is mentioned in the docs of `is_unicast_site_local` and already implemented in `is_unicast_global`, which considers addresses in `fec0::/10` to have global scope, thus overlapping with `is_unicast_site_local`.
Given that RFC #3879 was published in 2004, long before Rust existed, and it is specified that any new implementation must no longer support the special behaviour of site-local addresses, I don't see how a user would ever have a need for `is_unicast_site_local`. It is also confusing that currently both `is_unicast_site_local` and `is_unicast_global` can be `true` for an address, but an address can actually only have a single scope. The deprecating RFC mentions that Site-Local scope was confusing to work with and that the classification of an address as either Link-Local or Global better matches the mental model of users.
There has been earlier discussion of removing `is_unicast_site_local` (https://github.com/rust-lang/rust/pull/60145#issuecomment-485970669) which decided against it, but that had the incorrect assumption that the method was already stable; it is not. (This confusion arose from the placement of the unstable attribute on the entire module, instead of on individual methods, resolved in #85672)
r? `@joshtriplett` as reviewer of all the related PRs
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
Explain non-dropped sender recv in docs
Original senders that are still hanging around could cause
Receiver::recv to not block since this is a potential footgun
for beginners, clarify more on this in the docs for readers to
be aware about it.
Maybe it would be better to show an example of the pattern where `drop(tx)` is used when it is being cloned multiple times? Although I have seen it in quite a few articles but I am surprised that this part is not very clear with the current words without careful reading.
> If the corresponding Sender has disconnected, or it disconnects while this call is blocking, this call will wake up and return Err to indicate that no more messages can ever be received on this channel. However, since channels are buffered, messages sent before the disconnect will still be properly received.
Some words there may seemed similar if I carefully read and relate it but if I am new, I probably does not know "drop" makes it "disconnected". So I mention the words "drop" and "alive" to make it more relatable to lifetime.
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.
Original senders that are still hanging around could cause
Receiver::recv to not block since this is a potential footgun
for beginners, clarify more on this in the docs for readers to
be aware about it.
Fix minor tidbits in sender recv doc
Co-authored-by: Dylan DPC <dylan.dpc@gmail.com>
Add example for unbounded receive loops in doc
Show the drop(tx) pattern, based on tokio docs
https://tokio-rs.github.io/tokio/doc/tokio/sync/index.html
Fix example code for drop sender recv
Fix wording in sender docs
Co-authored-by: Josh Triplett <josh@joshtriplett.org>
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".
Updated code examples and wording in move keyword documentation
Had a conversation with someone on the Rust Discord who was confused by the move keyword documentation. Some of the wording is odd sounding ("owned by value" - what else can something be owned by?). Also, some of the examples used Copy types when demonstrating move, leading to variables still being accessible in the outer scope after the move, contradicting the examples' comments.
I changed the move keyword documentation a bit, removing that odd wording and changing all the examples to use non-Copy types
Multiple improvements to RwLocks
This PR replicates #77147, #77380 and #84650 on RWLocks :
- Split `sys_common::RWLock` in `StaticRWLock` and `MovableRWLock`
- Unbox rwlocks on some platforms (Windows, Wasm and unsupported)
- Simplify `RwLock::into_inner`
Notes to reviewers :
- For each target, I copied `MovableMutex` to guess if `MovableRWLock` should be boxed.
- ~A comment says that `StaticMutex` is not re-entrant, I don't understand why and I don't know whether it applies to `StaticRWLock`.~
r? `@m-ou-se`
Filesystems generally have a tree-ish structure which means
paths are more likely to share a prefix than a suffix. Absolute paths
are especially prone to share long prefixes.
Make copy/copy_nonoverlapping fn's again
Make copy/copy_nonoverlapping fn's again, rather than intrinsics.
This a short-term change to address issue #84297.
It effectively reverts PRs #81167#81238 (and part of #82967), #83091, and parts of #79684.
Revert "implement TrustedRandomAccess for Take iterator adapter"
This reverts commit 37a5b515e9 (#83990).
The original change unintentionally caused side-effects from certain iterator chains combining `take`, `zip` and `next_back()` to be omitted which is observable by user code and thus likely a breaking change
Technically one could declare it not a breaking change since `Zip`'s API contract is silent about about its backwards iteration behavior but on the other hand there is nothing in the stable Iterator API that could justify the currently observable behavior. And either way, this impact wasn't noticed or discussed in the original PR.
Fixes#85969
Forwarding implementation for Seek trait's stream_position method
Forwarding implementations for `Seek` trait's `stream_position` were missed when it was stabilized in `1.51.0`
Add `Ipv6Addr::is_unicast`
Adds an unstable utility method `Ipv6Addr::is_unicast` under the feature flag `ip` (tracking issue: #27709).
Added for completeness with the other unicast methods (see also https://github.com/rust-lang/rust/issues/85604#issuecomment-848220455) and opposite of `is_multicast`.
Fix documentation style inconsistencies for IP addresses
Pulled out of #85655 as it is unrelated. Fixes some inconsistencies in the docs for IP addresses:
- Currently some addresses are backticked, some are not, this PR backticks everything consistently. (looks better imo)
- Lowercase hex-literals are used when writing addresses.
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.
The "read more" sentence formatted "object safety" as inline code
instead of providing a link to more information. This PR adds a link
to the Reference about this matter, as well as the page regarding trait
objects.
Default panic message should print Box<dyn Any>
Closes#86039
Prior to this patch, the panic message from running the following code would be `thread 'main' panicked at 'Box<Any>'...`
```rust
use std::panic::panic_any;
fn main() {
panic_any(42);
}
```
This patch updates the phrasing to be more consistent. It now instead shows the following panic message:
```
thread 'main' panicked at 'Box<dyn Any>', ...
```
It's a very small fix 😄
Clarify documentation of slice sorting methods
After reading about [this](https://polkadot.network/a-polkadot-postmortem-24-05-2021/), I realized that although the documentation of these methods is not ambiguous in its current state, it is very easy to read it and erroneously assume that their exact behaviour can be relied upon to be deterministic. Although the docs make no guarantees about which index is returned when there are multiple matches, being more explicit about when and how their determinism can be relied upon should help prevent people from making this mistake in the future.
r? ``@steveklabnik``
String::remove_matches O(n^2) -> O(n)
Copy only non-matching bytes. Replace collection of matches into a
vector with iteration over rejections, exploiting the guarantee that we
mutate parts of the haystack that have already been searched over.
r? `@joshtriplett`
Prior to this patch, the default panic message (resulting from calling
`panic_any(42);` for example), would print the following error message:
```
thread 'main' panicked at 'Box<Any>', ...
```
However, this should be `Box<dyn Any>` instead.
