Due to the std/alloc split, it is not possible to make
`alloc::collections::TryReserveError::AllocError` non-exhaustive without
having an unstable, doc-hidden method to construct (which negates the
benefits from `#[non_exhaustive]`.
Document associativity of iterator folds.
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.
Better errors for Debug and Display traits
Currently, if someone tries to pass value that does not implement `Debug` or `Display` to a formatting macro, they get a very verbose and confusing error message. This PR changes the error messages for missing `Debug` and `Display` impls to be less overwhelming in this case, as suggested by #85844. I was a little less aggressive in changing the error message than that issue proposed. Still, this implementation would be enough to reduce the number of messages to be much more manageable.
After this PR, information on the cause of an error involving a `Debug` or `Display` implementation would suppressed if the requirement originated within a standard library macro. My reasoning was that errors originating from within a macro are confusing when they mention details that the programmer can't see, and this is particularly problematic for `Debug` and `Display`, which are most often used via macros. It is possible that either a broader or a narrower criterion would be better. I'm quite open to any feedback.
Fixes#85844.
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.
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
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".
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
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.
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``
Update standard library for IntoIterator implementation of arrays
This PR partially resolves issue #84513 of updating the standard library part.
I haven't found any remaining doctest examples which are using iterators over e.g. &i32 instead of just i32 in the standard library. Can anyone point me to them if there's remaining any?
Thanks!
r? ```@m-ou-se```
Add a map method to Bound
Add a map method to std::ops::range::Bound, patterned off of the method
of the same name on Option.
Have left off creating a tracking issue initially, but as soon as I get the go-ahead from a reviewer I'll make that right away 😄
Remove `doc(include)`
This nightly feature is redundant now that `extended_key_value_attributes` is stable (https://github.com/rust-lang/rust/pull/83366). `@rust-lang/rustdoc` not sure if you think this needs FCP; there was already an FCP in #82539, but technically it was for deprecating, not removing the feature altogether.
This should not be merged before #83366.
cc `@petrochenkov`
## User-facing changes
- Intra-doc links to primitives that currently go to rust-lang.org/nightly/std/primitive.x.html will start going to channel that rustdoc was built with. Nightly will continue going to /nightly; Beta will link to /beta; stable compilers will link to /1.52.1 (or whatever version they were built as).
- Cross-crate links from std to core currently go to /nightly unconditionally. They will start going to /1.52.0 on stable channels (but remain the same on nightly channels).
- Intra-crate links from std to std (or core to core) currently go to the same URL they are hosted at; they will continue to do so. Notably, this is different from everything else because it can preserve the distinction between /stable and /1.52.0 by using relative links.
Note that "links" includes both intra-doc links and rustdoc's own
automatically generated hyperlinks.
## Implementation changes
- Update the testsuite to allow linking to /beta and /1.52.1 in docs
- Use an html_root_url for the standard library that's dependent on the channel
This avoids linking to nightly docs on stable.
- Update rustdoc to use channel-dependent links for primitives from an
unknown crate
- Set DOC_RUST_LANG_ORG_CHANNEL from bootstrap to ensure it's in sync
- Include doc.rust-lang.org in the channel
Mention "null pointer optimization" in option docs.
I had seen people discuss "null pointer optimization," but when I tried to find official documentation (using Google), the `std::option` page didn't show up, because it doesn't use that term. Hopefully adding the term will help others find it in the future.
Revert "Auto merge of #83770 - the8472:tra-extend, r=Mark-Simulacrum"
Due to a performance regression that didn't show up in the original perf run
this reverts commit 9111b8ae97 (#83770), reversing
changes made to 9a700d2947.
Since since is expected to have the inverse impact it should probably be rollup=never.
r? `@Mark-Simulacrum`
Make `Step` trait safe to implement
This PR makes a few modifications to the `Step` trait that I believe better position it for stabilization in the short term. In particular,
1. `unsafe trait TrustedStep` is introduced, indicating that the implementation of `Step` for a given type upholds all stated invariants (which have remained unchanged). This is gated behind a new `trusted_step` feature, as stabilization is realistically blocked on min_specialization.
2. The `Step` trait is internally specialized on the `TrustedStep` trait, which avoids a serious performance regression.
3. `TrustedLen` is implemented for `T: TrustedStep` as the latter's invariants subsume the former's.
4. The `Step` trait is no longer `unsafe`, as the invariants must not be relied upon by unsafe code (unless the type implements `TrustedStep`).
5. `TrustedStep` is implemented for all types that implement `Step` in the standard library and compiler.
6. The `step_trait_ext` feature is merged into the `step_trait` feature. I was unable to find any reasoning for the features being split; the `_unchecked` methods need not necessarily be stabilized at the same time, but I think it is useful to have them under the same feature flag.
All existing implementations of `Step` will be broken, as it is not possible to `unsafe impl` a safe trait. Given this trait only exists on nightly, I feel this breakage is acceptable. The blanket `impl<T: Step> TrustedLen for T` will likely cause some minor breakage, but this should be covered by the equivalent impl for `TrustedStep`.
Hopefully these changes are sufficient to place `Step` in decent position for stabilization, which would allow user-defined types to be used with `a..b` syntax.
Mention workaround for floats in Iterator::{min, max}
`Iterator::{min, max}` can't be used with iterators of floats due to NaN issues. This suggests a workaround in the documentation of those functions.
Forwarding `clone_from` to the inner value changes the observable
behavior, as previously the inner value would *not* be dropped by the
default implementation.
Remove Iterator #[rustc_on_unimplemented]s that no longer apply.
Now that `IntoIterator` is implemented for arrays, all the `rustc_on_unimplemented` for arrays of ranges (e.g. `for _ in [1..3] {}`) no longer apply, since they are now valid Rust.
Separated these from #85670, because we should discuss a potential new (clippy?) lint for these.
Until Rust 1.52, `for _ in [1..3] {}` produced:
```
error[E0277]: `[std::ops::Range<{integer}>; 1]` is not an iterator
--> src/main.rs:2:14
|
2 | for _ in [1..3] {}
| ^^^^^^ if you meant to iterate between two values, remove the square brackets
|
= help: the trait `std::iter::Iterator` is not implemented for `[std::ops::Range<{integer}>; 1]`
= note: `[start..end]` is an array of one `Range`; you might have meant to have a `Range` without the brackets: `start..end`
= note: required by `std::iter::IntoIterator::into_iter`
```
But in Rust 1.53 and later, it compiles fine. It iterates over the array by value, for one iteration with the element `1..3`.
This is probably a mistake, which is no longer caught. Should we have a lint for it? Should Clippy have a lint for it?
cc ```@estebank``` ```@flip1995```
cc https://github.com/rust-lang/rust/issues/84513
While stdlib implementations of the unchecked methods require unchecked
math, there is no reason to gate it behind this for external users. The
reasoning for a separate `step_trait_ext` feature is unclear, and as
such has been merged as well.
Add `TrustedRandomAccess` specialization for `Vec::extend()`
This should do roughly the same as the `TrustedLen` specialization but result in less IR by using `__iterator_get_unchecked`
instead of `Iterator::for_each`
Conflicting specializations are manually prioritized by grouping them under yet another helper trait.
Fix typo in core::array::IntoIter comment
Saw a small typo reading some internal comments and decided to just throw this up to fix it for future readers.
Remove num_as_ne_bytes feature
From the discussion in #76976, it is determined that eventual results of the safe transmute work as a more general mechanism will let these conversions happen in safe code without needing specialized methods.
Merging this PR closes#76976 and resolves#64464. Several T-libs members have raised their opinion that it doesn't pull its weight as a standalone method, and so we should not track it as a specific thing to add.
fix `matches!` and `assert_matches!` on edition 2021
Previously this code failed to compile on edition 2021. [(Playground)](https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=53960f2f051f641777b9e458da747707)
```rust
fn main() {
matches!((), ());
}
```
```
Compiling playground v0.0.1 (/playground)
error: `$pattern:pat` may be followed by `|`, which is not allowed for `pat` fragments
|
= note: allowed there are: `=>`, `,`, `=`, `if` or `in`
error: aborting due to previous error
error: could not compile `playground`
To learn more, run the command again with --verbose.
```
Demote `ControlFlow::{from|into}_try` to `pub(crate)`
They have mediocre names and non-obvious semantics, so personally I don't think they're worth trying to stabilize, and thus might as well just be internal (they're used for convenience in iterator adapters), not something shown in the rustdocs.
I don't think anyone actually wanted to use them outside `core` -- they just got made public-but-unstable along with the whole type in https://github.com/rust-lang/rust/pull/76204 that promoted `LoopState` from an internal type to the exposed `ControlFlow` type.
cc https://github.com/rust-lang/rust/issues/75744, the tracking issue they mention.
cc https://github.com/rust-lang/rust/pull/85608, the PR where I'm proposing stabilizing the type.
Fix pointer provenance in <[T]>::copy_within
Previously the `self.as_mut_ptr()` invalidated the pointer created by the first `self.as_ptr()`. This also triggered miri when run with `-Zmiri-track-raw-pointers`
Better English for documenting when to use unimplemented!()
I don't think "plan of using" is correct here. I considered "plan on using" but eventually decided "plan to use" is better.
Bump bootstrap compiler to beta 1.53.0
This PR bumps the bootstrap compiler to version 1.53.0 beta, as part of our usual release process (this was supposed to be Wednesday's step, but creating the beta release took longer than expected).
The PR also includes the "Bootstrap: skip rustdoc fingerprint for building docs" commit, see the reasoning [on Zulip](https://zulip-archive.rust-lang.org/241545trelease/88450153betabootstrap.html).
r? `@Mark-Simulacrum`
Extend `rustc_on_implemented` to improve more `?` error messages
`_Self` could match the generic definition; this adds that functionality for matching the generic definition of type parameters too.
Your advice welcome on the wording of all these messages, and which things belong in the message/label/note.
r? `@estebank`
fix pad_integral example
pad_integral's parameter `is_nonnegative - whether the original integer was either positive or zero`, but in example it checked as `self.nb > 0`, so it previously printed `-0` for `format!("{}", Foo::new(0)`, what is wrong.
Extremely outdated; not only are traits implemented on arrays of arbitrary length, those implementations are documented on the primitive type, not in this module.
Rollup of 8 pull requests
Successful merges:
- #84717 (impl FromStr for proc_macro::Literal)
- #85169 (Add method-toggle to <details> for methods)
- #85287 (Expose `Concurrent` (private type in public i'face))
- #85315 (adding time complexity for partition_in_place iter method)
- #85439 (Add diagnostic item to `CStr`)
- #85464 (Fix UB in documented example for `ptr::swap`)
- #85470 (Fix invalid CSS rules for a:hover)
- #85472 (CTFE Machine: do not expose Allocation)
Failed merges:
r? `@ghost`
`@rustbot` modify labels: rollup
Avoid zero-length memcpy in formatting
This has two separate and somewhat orthogonal commits. The first change adjusts the ToString general impl for all types that implement Display; it no longer uses the full format machinery, rather directly falling onto a `std::fmt::Display::fmt` call. The second change directly adjusts the general core::fmt::write function which handles the production of format_args! to avoid zero-length push_str calls.
Both changes target the fact that push_str will still call memmove internally (or a similar function), as it doesn't know the length of the passed string. For zero-length strings in particular, this is quite expensive, and even for very short (several bytes long) strings, this is also expensive. Future work in this area may wish to have us fallback to write_char or similar, which may be cheaper on the (typically) short strings between the interpolated pieces in format_args!.
adding time complexity for partition_in_place iter method
I feel that one thing missing from rust docs compared to cpp references is existence of time complexity for all methods and functions. While it would be humongous task to include it for everything in single go, it is still doable if we as community keep on adding it in relevant places as and when we find them.
This PR adds the time complexity for partition_in_place method in iter.
remove InPlaceIterable marker from Peekable due to unsoundness
The unsoundness is not in Peekable per se, it rather is due to the
interaction between Peekable being able to hold an extra item
and vec::IntoIter's clone implementation shortening the allocation.
An alternative solution would be to change IntoIter's clone implementation
to keep enough spare capacity available.
fixes#85322
Override `clone_from` for some types
Override `clone_from` method of the `Clone` trait for:
- `cell::RefCell`
- `cmp::Reverse`
- `io::Cursor`
- `mem::ManuallyDrop`
This can bring performance improvements.
The unsoundness is not in Peekable per se, it rather is due to the
interaction between Peekable being able to hold an extra item
and vec::IntoIter's clone implementation shortening the allocation.
An alternative solution would be to change IntoIter's clone implementation
to keep enough spare capacity available.
Implement the new desugaring from `try_trait_v2`
~~Currently blocked on https://github.com/rust-lang/rust/issues/84782, which has a PR in https://github.com/rust-lang/rust/pull/84811~~ Rebased atop that fix.
`try_trait_v2` tracking issue: https://github.com/rust-lang/rust/issues/84277
Unfortunately this is already touching a ton of things, so if you have suggestions for good ways to split it up, I'd be happy to hear them. (The combination between the use in the library, the compiler changes, the corresponding diagnostic differences, even MIR tests mean that I don't really have a great plan for it other than trying to have decently-readable commits.
r? `@ghost`
~~(This probably shouldn't go in during the last week before the fork anyway.)~~ Fork happened.
Implement more Iterator methods on core::iter::Repeat
`core::iter::Repeat` always returns the same element, which means we can
do better than implementing most `Iterator` methods in terms of
`Iterator::next`.
Fixes#81292.
#81292 raises the question of whether these changes violate the contract of `core::iter::Repeat`, but as far as I can tell `core::iter::repeat` doesn't make any guarantees around how it calls `Clone::clone`.
# Stabilization report
## Summary
This stabilizes using macro expansion in key-value attributes, like so:
```rust
#[doc = include_str!("my_doc.md")]
struct S;
#[path = concat!(env!("OUT_DIR"), "/generated.rs")]
mod m;
```
See the changes to the reference for details on what macros are allowed;
see Petrochenkov's excellent blog post [on internals](https://internals.rust-lang.org/t/macro-expansion-points-in-attributes/11455)
for alternatives that were considered and rejected ("why accept no more
and no less?")
This has been available on nightly since 1.50 with no major issues.
## Notes
### Accepted syntax
The parser accepts arbitrary Rust expressions in this position, but any expression other than a macro invocation will ultimately lead to an error because it is not expected by the built-in expression forms (e.g., `#[doc]`). Note that decorators and the like may be able to observe other expression forms.
### Expansion ordering
Expansion of macro expressions in "inert" attributes occurs after decorators have executed, analogously to macro expressions appearing in the function body or other parts of decorator input.
There is currently no way for decorators to accept macros in key-value position if macro expansion must be performed before the decorator executes (if the macro can simply be copied into the output for later expansion, that can work).
## Test cases
- https://github.com/rust-lang/rust/blob/master/src/test/ui/attributes/key-value-expansion-on-mac.rs
- https://github.com/rust-lang/rust/blob/master/src/test/rustdoc/external-doc.rs
The feature has also been dogfooded extensively in the compiler and
standard library:
- https://github.com/rust-lang/rust/pull/83329
- https://github.com/rust-lang/rust/pull/83230
- https://github.com/rust-lang/rust/pull/82641
- https://github.com/rust-lang/rust/pull/80534
## Implementation history
- Initial proposal: https://github.com/rust-lang/rust/issues/55414#issuecomment-554005412
- Experiment to see how much code it would break: https://github.com/rust-lang/rust/pull/67121
- Preliminary work to restrict expansion that would conflict with this
feature: https://github.com/rust-lang/rust/pull/77271
- Initial implementation: https://github.com/rust-lang/rust/pull/78837
- Fix for an ICE: https://github.com/rust-lang/rust/pull/80563
## Unresolved Questions
~~https://github.com/rust-lang/rust/pull/83366#issuecomment-805180738 listed some concerns, but they have been resolved as of this final report.~~
## Additional Information
There are two workarounds that have a similar effect for `#[doc]`
attributes on nightly. One is to emulate this behavior by using a limited version of this feature that was stabilized for historical reasons:
```rust
macro_rules! forward_inner_docs {
($e:expr => $i:item) => {
#[doc = $e]
$i
};
}
forward_inner_docs!(include_str!("lib.rs") => struct S {});
```
This also works for other attributes (like `#[path = concat!(...)]`).
The other is to use `doc(include)`:
```rust
#![feature(external_doc)]
#[doc(include = "lib.rs")]
struct S {}
```
The first works, but is non-trivial for people to discover, and
difficult to read and maintain. The second is a strange special-case for
a particular use of the macro. This generalizes it to work for any use
case, not just including files.
I plan to remove `doc(include)` when this is stabilized. The
`forward_inner_docs` workaround will still compile without warnings, but
I expect it to be used less once it's no longer necessary.
This avoids a zero-length write_str call, which boils down to a zero-length
memmove and ultimately costs quite a few instructions on some workloads.
This is approximately a 0.33% instruction count win on diesel-check.
`core::iter::Repeat` always returns the same element, which means we can
do better than implementing most `Iterator` methods in terms of
`Iterator::next`.
Fixes#81292.
add BITS associated constant to core::num::Wrapping
This keeps `Wrapping` synchronized with the primitives it wraps as for the #32463 `wrapping_int_impl` feature.
#[inline(always)] on basic pointer methods
Retryng #85201 with only inlining pointer methods. The goal is to make pointers behave just like pointers in O0, mainly to reduce overhead in debug builds.
cc `@scottmcm`
Add auto traits and clone trait migrations for RFC2229
This PR
- renames the existent RFC2229 migration `disjoint_capture_drop_reorder` to `disjoint_capture_migration`
- add additional migrations for auto traits and clone trait
Closesrust-lang/project-rfc-2229#29Closesrust-lang/project-rfc-2229#28
r? `@nikomatsakis`
Make unchecked_{add,sub,mul} inherent methods unstably const
The intrinsics are marked as being stably const (even though they're not stable by nature of being intrinsics), but the currently-unstable inherent versions are not marked as const. This fixes this inconsistency. Split out of #85017,
r? `@oli-obk`
Disallows `#![feature(no_coverage)]` on stable and beta (using standard crate-level gating)
Fixes: #84836
Removes the function-level feature gating solution originally implemented, and solves the same problem using `allow_internal_unstable`, so normal crate-level feature gating mechanism can still be used (which disallows the feature on stable and beta).
I tested this, building the compiler with and without `CFG_DISABLE_UNSTABLE_FEATURES=1`
With unstable features disabled, I get the expected result as shown here:
```shell
$ ./build/x86_64-unknown-linux-gnu/stage1/bin/rustc src/test/run-make-fulldeps/coverage/no_cov_crate.rs
error[E0554]: `#![feature]` may not be used on the dev release channel
--> src/test/run-make-fulldeps/coverage/no_cov_crate.rs:2:1
|
2 | #![feature(no_coverage)]
| ^^^^^^^^^^^^^^^^^^^^^^^^
error: aborting due to previous error
For more information about this error, try `rustc --explain E0554`.
```
r? ````@Mark-Simulacrum````
cc: ````@tmandry```` ````@wesleywiser````
Allow using `core::` in intra-doc links within core itself
I came up with this idea ages ago, but rustdoc used to ICE on it. Now it doesn't.
Helps with https://github.com/rust-lang/rust/issues/73445. Doesn't fix it completely since `extern crate self as std;` in std still gives strange errors.
Clarify documentation for `[T]::contains`
Change the documentation to correctly characterize when the suggested alternative to `contains` applies, and correctly explain why it works.
Fixes#84877
Update `ptr` docs with regards to `ptr::addr_of!`
This updates the documentation since `ptr::addr_of!` and `ptr::addr_of_mut!` are now stable. One might remove the distinction between the sections `# On packed structs` and `# Examples`, as the old section on packed structs was primarily to prevent users of doing undefined behavior, which is not necessary anymore.
Technically there is now wrong/outdated documentation on stable, but I don't think this is worth a point release 😉Fixes#83509.
``````````@rustbot`````````` modify labels: T-doc
using allow_internal_unstable (as recommended)
Fixes: #84836
```shell
$ ./build/x86_64-unknown-linux-gnu/stage1/bin/rustc src/test/run-make-fulldeps/coverage/no_cov_crate.rs
error[E0554]: `#![feature]` may not be used on the dev release channel
--> src/test/run-make-fulldeps/coverage/no_cov_crate.rs:2:1
|
2 | #![feature(no_coverage)]
| ^^^^^^^^^^^^^^^^^^^^^^^^
error: aborting due to previous error
For more information about this error, try `rustc --explain E0554`.
```
This updates the documentation since `ptr::addr_of!` and
`ptr::addr_of_mut!` are now stable. One might remove the distinction
between the sections `# On packed structs` and `# Examples`, as the old
section on packed structs was primarily to prevent users of doing unde-
fined behavior, which is not necessary anymore.
There is also a new section in "how to obtain a pointer", which referen-
ces the `ptr::addr_of!` macros.
This commit contains squashed commits from code review.
Co-authored-by: Joshua Nelson <joshua@yottadb.com>
Co-authored-by: Mara Bos <m-ou.se@m-ou.se>
Co-authored-by: Soveu <marx.tomasz@gmail.com>
Co-authored-by: Ralf Jung <post@ralfj.de>
[Arm64] use isb instruction instead of yield in spin loops
On arm64 we have seen on several databases that ISB (instruction synchronization
barrier) is better to use than yield in a spin loop. The yield instruction is a
nop. The isb instruction puts the processor to sleep for some short time. isb
is a good equivalent to the pause instruction on x86.
Below is an experiment that shows the effects of yield and isb on Arm64 and the
time of a pause instruction on x86 Intel processors. The micro-benchmarks use
https://github.com/google/benchmark.git
```
$ cat a.cc
static void BM_scalar_increment(benchmark::State& state) {
int i = 0;
for (auto _ : state)
benchmark::DoNotOptimize(i++);
}
BENCHMARK(BM_scalar_increment);
static void BM_yield(benchmark::State& state) {
for (auto _ : state)
asm volatile("yield"::);
}
BENCHMARK(BM_yield);
static void BM_isb(benchmark::State& state) {
for (auto _ : state)
asm volatile("isb"::);
}
BENCHMARK(BM_isb);
BENCHMARK_MAIN();
$ g++ -o run a.cc -O2 -lbenchmark -lpthread
$ ./run
--------------------------------------------------------------
Benchmark Time CPU Iterations
--------------------------------------------------------------
AWS Graviton2 (Neoverse-N1) processor:
BM_scalar_increment 0.485 ns 0.485 ns 1000000000
BM_yield 0.400 ns 0.400 ns 1000000000
BM_isb 13.2 ns 13.2 ns 52993304
AWS Graviton (A-72) processor:
BM_scalar_increment 0.897 ns 0.874 ns 801558633
BM_yield 0.877 ns 0.875 ns 800002377
BM_isb 13.0 ns 12.7 ns 55169412
Apple Arm64 M1 processor:
BM_scalar_increment 0.315 ns 0.315 ns 1000000000
BM_yield 0.313 ns 0.313 ns 1000000000
BM_isb 9.06 ns 9.06 ns 77259282
```
```
static void BM_pause(benchmark::State& state) {
for (auto _ : state)
asm volatile("pause"::);
}
BENCHMARK(BM_pause);
Intel Skylake processor:
BM_scalar_increment 0.295 ns 0.295 ns 1000000000
BM_pause 41.7 ns 41.7 ns 16780553
```
Tested on Graviton2 aarch64-linux with `./x.py test`.
On arm64 we have seen on several databases that ISB (instruction synchronization
barrier) is better to use than yield in a spin loop. The yield instruction is a
nop. The isb instruction puts the processor to sleep for some short time. isb
is a good equivalent to the pause instruction on x86.
Below is an experiment that shows the effects of yield and isb on Arm64 and the
time of a pause instruction on x86 Intel processors. The micro-benchmarks use
https://github.com/google/benchmark.git
$ cat a.cc
static void BM_scalar_increment(benchmark::State& state) {
int i = 0;
for (auto _ : state)
benchmark::DoNotOptimize(i++);
}
BENCHMARK(BM_scalar_increment);
static void BM_yield(benchmark::State& state) {
for (auto _ : state)
asm volatile("yield"::);
}
BENCHMARK(BM_yield);
static void BM_isb(benchmark::State& state) {
for (auto _ : state)
asm volatile("isb"::);
}
BENCHMARK(BM_isb);
BENCHMARK_MAIN();
$ g++ -o run a.cc -O2 -lbenchmark -lpthread
$ ./run
--------------------------------------------------------------
Benchmark Time CPU Iterations
--------------------------------------------------------------
AWS Graviton2 (Neoverse-N1) processor:
BM_scalar_increment 0.485 ns 0.485 ns 1000000000
BM_yield 0.400 ns 0.400 ns 1000000000
BM_isb 13.2 ns 13.2 ns 52993304
AWS Graviton (A-72) processor:
BM_scalar_increment 0.897 ns 0.874 ns 801558633
BM_yield 0.877 ns 0.875 ns 800002377
BM_isb 13.0 ns 12.7 ns 55169412
Apple Arm64 M1 processor:
BM_scalar_increment 0.315 ns 0.315 ns 1000000000
BM_yield 0.313 ns 0.313 ns 1000000000
BM_isb 9.06 ns 9.06 ns 77259282
static void BM_pause(benchmark::State& state) {
for (auto _ : state)
asm volatile("pause"::);
}
BENCHMARK(BM_pause);
Intel Skylake processor:
BM_scalar_increment 0.295 ns 0.295 ns 1000000000
BM_pause 41.7 ns 41.7 ns 16780553
Tested on Graviton2 aarch64-linux with `./x.py test`.
Searching for "reduce" currently puts the `reduce` alias for `fold`
above the actual `reduce` function. The `reduce` function already has a
cross-reference for `fold`, and vice versa.
The Eq trait has a special hidden function. MIR `InstrumentCoverage`
would add this function to the coverage map, but it is never called, so
the `Eq` trait would always appear uncovered.
Fixes: #83601
The fix required creating a new function attribute `no_coverage` to mark
functions that should be ignored by `InstrumentCoverage` and the
coverage `mapgen` (during codegen).
While testing, I also noticed two other issues:
* spanview debug file output ICEd on a function with no body. The
workaround for this is included in this PR.
* `assert_*!()` macro coverage can appear covered if followed by another
`assert_*!()` macro. Normally they appear uncovered. I submitted a new
Issue #84561, and added a coverage test to demonstrate this issue.
Add the `try_trait_v2` library basics
No compiler changes as part of this -- just new unstable traits and impls thereof.
The goal here is to add the things that aren't going to break anything, to keep the feature implementation simpler in the next PR.
(Draft since the FCP won't end until Saturday, but I was feeling optimistic today -- and had forgotten that FCP was 10 days, not 7 days.)
Stabilize Duration::MAX
Following the suggested direction from https://github.com/rust-lang/rust/issues/76416#issuecomment-817278338, this PR proposes that `Duration::MAX` should have been part of the `duration_saturating_ops` feature flag all along, having been
0. heavily referenced by that feature flag
1. an odd duck next to most of `duration_constants`, as I expressed in https://github.com/rust-lang/rust/issues/57391#issuecomment-717681193
2. introduced in #76114 which added `duration_saturating_ops`
and accordingly should be folded into `duration_saturating_ops` and therefore stabilized.
r? `@m-ou-se`
move core::hint::black_box under its own feature gate
The `black_box` function had its own RFC and is tracked separately from the `test` feature at https://github.com/rust-lang/rust/issues/64102. Let's reflect this in the feature gate.
To avoid breaking all the benchmarks, libtest's `test::black_box` is a wrapping definition, not a reexport -- this means it is still under the `test` feature gate.
Cautiously add IntoIterator for arrays by value
Add the attribute described in #84133, `#[rustc_skip_array_during_method_dispatch]`, which effectively hides a trait from method dispatch when the receiver type is an array.
Then cherry-pick `IntoIterator for [T; N]` from #65819 and gate it with that attribute. Arrays can now be used as `IntoIterator` normally, but `array.into_iter()` has edition-dependent behavior, returning `slice::Iter` for 2015 and 2018 editions, or `array::IntoIter` for 2021 and later.
r? `@nikomatsakis`
cc `@LukasKalbertodt` `@rust-lang/libs`
Duration is used in std to represent a difference between two Instants.
As such, it has to at least contain that span of time in it. However,
Instant can vary by platform. Thus, we should explain the impl of
Duration::MAX is sensitive to these vagaries of the platform.
further split up const_fn feature flag
This continues the work on splitting up `const_fn` into separate feature flags:
* `const_fn_trait_bound` for `const fn` with trait bounds
* `const_fn_unsize` for unsizing coercions in `const fn` (looks like only `dyn` unsizing is still guarded here)
I don't know if there are even any things left that `const_fn` guards... at least libcore and liballoc do not need it any more.
`@oli-obk` are you currently able to do reviews?
Mention FusedIterator case in Iterator::fuse doc
Using `fuse` on an iterator that incorrectly implements
`FusedIterator` does not fuse the iterator. This commit adds a
note about this in the documentation of this method to increase
awareness about this potential issue (esp. when relying on fuse
in unsafe code).
Closes#83969
implement `TrustedRandomAccess` for `Take` iterator adapter
`TrustedRandomAccess` requires the iterator length to fit within `usize`. `take(n)` only constrains the upper bound of an iterator. So if the inner is `TrustedRandomAccess` (which already implies a finite length) then so can be `Take`.
```````@rustbot``````` label T-libs-impl
Improve `Iterator::by_ref` example
I split the example into two: one that fails to compile, and one that
works. I also made them identical except for the addition of `by_ref`
so we don't confuse readers with random differences.
cc `@steveklabnik,` who is the one that added the previous version of this example
Using `fuse` on an iterator that incorrectly implements
`FusedIterator` does not fuse the iterator. This commit adds a
note about this in the documentation of this method to increase
awareness about this potential issue (esp. when relying on fuse
in unsafe code).
