Improve documentation for `core::fmt` internals
The public interface of `core::fmt` is well-documented, but the internals have very minimal documentation.
More intra-doc links, add explicit exception list to linkchecker
Fixes the broken links behind #32553
Progress on #32130 and #32129 except for a small number of links. Instead of whitelisting entire files, I've changed the code to whitelist specific links in specific files, and added a comment requesting people explain the reasons they add exceptions. I'm not sure if we should close those issues in favor of the already filed intra-doc link issues.
Generating the coverage map
@tmandry @wesleywiser
rustc now generates the coverage map and can support (limited)
coverage report generation, at the function level.
Example commands to generate a coverage report:
```shell
$ BUILD=$HOME/rust/build/x86_64-unknown-linux-gnu
$ $BUILD/stage1/bin/rustc -Zinstrument-coverage \
$HOME/rust/src/test/run-make-fulldeps/instrument-coverage/main.rs
$ LLVM_PROFILE_FILE="main.profraw" ./main
called
$ $BUILD/llvm/bin/llvm-profdata merge -sparse main.profraw -o main.profdata
$ $BUILD/llvm/bin/llvm-cov show --instr-profile=main.profdata main
```
r? @wesleywiser
Rust compiler MCP rust-lang/compiler-team#278
Relevant issue: #34701 - Implement support for LLVMs code coverage instrumentation
Make unreachable_unchecked a const fn
This PR makes `std::hint::unreachable_unchecked` a const fn so we can use it inside a const function.
r? @RalfJung
Fixes#53188.
Add core::task::ready! macro
This PR adds `ready!` as a top-level macro to `libcore` following the implementation of `futures_core::ready`, tracking issue https://github.com/rust-lang/rust/issues/70922. This macro is commonly used when implementing `Future`, `AsyncRead`, `AsyncWrite` and `Stream`. And being only 5 lines, it seems like a useful and straight forward addition to std.
## Example
```rust
use core::task::{Context, Poll};
use core::future::Future;
use core::pin::Pin;
async fn get_num() -> usize {
42
}
pub fn do_poll(cx: &mut Context<'_>) -> Poll<()> {
let mut f = get_num();
let f = unsafe { Pin::new_unchecked(&mut f) };
let num = ready!(f.poll(cx));
// ... use num
Poll::Ready(())
}
```
## Naming
In `async-std` we chose to nest the macro under the `task` module instead of having the macro at the top-level. This is a pattern that currently does not occur in std, mostly due to this not being possible prior to Rust 2018.
This PR proposes to add the `ready` macro as `core::ready`. But another option would be to introduce it as `core::task::ready` since it's really only useful when used in conjunction with `task::{Context, Poll}`.
## Implementation questions
I tried rendering the documentation locally but the macro didn't show up under `core`. I'm not sure if I quite got this right. I used the [`todo!` macro PR](https://github.com/rust-lang/rust/pull/56348/files) as a reference, and our approaches look similar.
## References
- [`futures::ready`](https://docs.rs/futures/0.3.4/futures/macro.ready.html)
- [`async_std::task::ready`](https://docs.rs/async-std/1.5.0/async_std/task/index.html)
- [`futures_core::ready`](https://docs.rs/futures-core/0.3.4/futures_core/macro.ready.html)
Use intra-doc links in `str` and `BTreeSet`
Fixes#32129, fixes #32130
A _slight_ degradation in quality is that the `#method.foo` links would previously link to the same page on `String`'s documentation, and now they will navigate to `str`. Not a big deal IMO, and we can also try to improve that.
Fix `Safety` docs for `from_raw_parts_mut`
This aligns the wording more with the documentation of e.g. `drop_in_place`, `replace`, `swap` and `swap_nonoverlapping` from `core::ptr`.
Also if the pointer were really only valid for writes, it would be trivial to introduce UB from safe code, after calling `core::slice::from_raw_parts_mut`.
Add lazy initialization primitives to std
Follow-up to #68198
Current RFC: https://github.com/rust-lang/rfcs/pull/2788
Rebased and fixed up a few of the dangling comments. Some notes carried over from the previous PR:
- [ ] Naming. I'm ok to just roll with the `Sync` prefix like `SyncLazy` for now, but [have a personal preference for `Atomic`](https://github.com/rust-lang/rfcs/pull/2788#issuecomment-574466983) like `AtomicLazy`.
- [x] [Poisoning](https://github.com/rust-lang/rfcs/pull/2788#discussion_r366725768). It seems like there's [some regret around poisoning in other `std::sync` types that we might want to just avoid upfront for `std::lazy`, especially if that would align with a future `std::mutex` that doesn't poison](https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs/topic/parking_lot.3A.3AMutex.20in.20std/near/190331199). Personally, if we're adding these types to `std::lazy` instead of `std::sync`, I'd be on-board with not worrying about poisoning in `std::lazy`, and potentially deprecating `std::sync::Once` and `lazy_static` in favour of `std::lazy` down the track if it's possible, rather than attempting to replicate their behavior. cc @Amanieu @sfackler.
- [ ] [Consider making`SyncOnceCell::get` blocking](https://github.com/matklad/once_cell/pull/92). There doesn't seem to be consensus in the linked PR on whether or not that's strictly better than the non-blocking variant.
In general, none of these seem to be really blocking an initial unstable merge, so we could possibly kick off a FCP if y'all are happy?
cc @matklad @pitdicker have I missed anything, or were there any other considerations that have come up since we last looked at this?
Add Arguments::as_str().
There exist quite a few macros in the Rust ecosystem which use `format_args!()` for formatting, but special case the one-argument case for optimization:
```rust
#[macro_export]
macro_rules! some_macro {
($s:expr) => { /* print &str directly, no formatting, no buffers */ };
($s:expr, $($tt:tt)*) => { /* use format_args to write to a buffer first */ }
}
```
E.g. [here](7a961f0fbe/src/macros.rs (L48-L58)), [here](20f9a9e223/src/macros.rs (L9-L17)), and [here](7b679cd6da/px4/src/logging.rs (L45-L52)).
The problem with these is that a forgotten argument such as in `some_macro!("{}")` will not be diagnosed, but just prints `"{}"`.
With this PR, it is possible to handle the no-arguments case separately *after* `format_args!()`, while simplifying the macro. Then these macros can give the proper error about a missing argument, just like `print!("{}")` does, while still using the same optimized implementation as before.
This is even more important with [RFC 2795](https://github.com/rust-lang/rfcs/pull/2795), to make sure `some_macro!("{some_variable}")` works as expected.
Make some Option methods const
Tracking issue: #67441
Constantify the following methods of `Option`:
- `as_ref`
- `is_some`
- `is_none`
- `iter` (not sure about this one, but it is possible, and will be useful when const traits are a thing)
cc @rust-lang/wg-const-eval @rust-lang/libs
Bump version to 1.47
This also bumps to a more recent rustfmt version, just to keep us relatively up to date (though almost nothing has changed in rustfmt we use beyond bumps to the parser infra). No formatting changes as a result of this.
r? @pietroalbini
This commit refactors the initial implementation to fit into std and
makes some other changes:
- use MaybeUninit internally in SyncOnceCell
- correctly impl Drop for lazy::Once
- port Lazy::take from once_cell from: https://github.com/matklad/once_cell/pull/100
Co-Authored-By: Paul Dicker <pitdicker@users.noreply.github.com>
Fix typo in std::mem::transmute documentation
`u32::from_ge_bytes` function does not exist; replace with `u32::from_be_bytes`.
It is clear that `u32::from_le_bytes` is not meant from the context; the latter is used correctly while `from_be_bytes` is misspelled.
Constify most non-trait `Duration` methods as described in #72440
The remaining methods could probably be made const once https://github.com/rust-lang/rust/pull/72449 lands with support for `f<32|64>::is_finite()`.
Update docs for str::as_bytes_mut.
* Add "Safety" section describing UTF-8 invariant.
* Remove mention of `from_utf8_mut`. It is not necessary to call
a function to convert the byte slice back to a string slice. The
original string becomes accessible again after the byte slice is
no longer used (as shown in the example code).
Clarify effect of orphan rule changes on From/Into
Updated documentation for `std::convert` and `std::convert::From` to reflect changes to orphan rule in Rust 1.41. It should no longer be necessary to implement `Into` directly, unless targeting an older version.
r? @steveklabnik
* Add "Safety" section describing UTF-8 invariant.
* Remove mention of `from_utf8_mut`. It is not necessary to call
a function to convert the byte slice back to a string slice. The
original string becomes accessible again after the byte slice is
no longer used (as shown in the example code).
Updated documentation for `std::convert` and `std::convert::From` to
reflect changes to orphan rule in Rust 1.41. It should no longer be
necessary to implement Into directly, unless targeting an older version.
This now reuses `fn discriminant_ty` in project, removing
some code duplication. Doing so made me realize that
we previously had a disagreement about the discriminant
type of generators, with MIR using `u32` and codegen and
trait selection using `i32`.
We now always use `u32`.
