The wording is copied from `std::sync::atomic::AtomicPtr`, with
additional advice on how to `#[cfg]` for it.

In particular, be clear that it is sound to specify memory not
originating from a previous `Vec` allocation. That is already suggested
in other parts of the documentation about zero-alloc conversions to Box<[T]>.

Incorporate a constraint from `slice::from_raw_parts` that was missing
but needs to be fulfilled, since a `Vec` can be converted into a slice.

- Explicitly mention that `AsRef` and `AsMut` do not auto-dereference
  generally for all dereferencable types (but only if inner type is a
  shared and/or mutable reference)
- Give advice to not use `AsRef` or `AsMut` for the sole purpose of
  dereferencing
- Suggest providing a transitive `AsRef` or `AsMut` implementation for
  types which implement `Deref`
- Add new section "Reflexivity" in documentation comments for `AsRef`
  and `AsMut`
- Provide better example for `AsMut`
- Added heading "Relation to `Borrow`" in `AsRef`'s docs to improve
  structure

Issue rust-lang#45742 and a corresponding FIXME in the libcore suggest that
`AsRef` and `AsMut` should provide a blanket implementation over
`Deref`. As that is difficult to realize at the moment, this commit
updates the documentation to better describe the status-quo and to give
advice on how to use `AsRef` and `AsMut`.

Fixed examples in sections "Generic Implementations" of `AsRef`'s and
`AsMut`'s doc comments, which failed tests.

Better conform to Rust API Documentation Conventions

Changed wording in sections on "Reflexivity":
replaced "that is there is" with "i.e. there would be" and removed comma
before "with"

Reason: "there is" somewhat contradicted the "would be" hypothetical.
A slightly redundant wording has now been chosen for better clarity.
The comma seemed to be superfluous.

…ssary `Default` bounds

Co-Authored-By: Mark Rousskov <mark.simulacrum@gmail.com>

Co-authored-by: Michael Goulet <michael@errs.io>

…triplett

Add `Option::owned`

This PR adds the following public library APIs:
```rust
impl<T: ?Sized> Option<&T> {
    pub const fn owned(self) -> Option<T::Owned>
    where
        T: ~const ToOwned;
}

impl<T: ?Sized> Option<&mut T> {
    pub fn owned(self) -> Option<T::Owned>
    where
        T: ~const ToOwned;
}
```

`Option::owned` is similar to `Option::cloned` and `Option::copied`, but uses the `ToOwned` trait.

---

I thought that would be easier, but since `ToOwned` is defined in the alloc crate this becomes incoherent :')

Document the conditional existence of `alloc::sync` and `alloc::task`.

`alloc` declares

```rust
#[cfg(target_has_atomic = "ptr")]
pub mod sync;
```

but there is no public documentation of this condition. This PR fixes that, so that users of `alloc` can understand how to make their code compile everywhere `alloc` does, if they are writing a library with impls for `Arc`.

The wording is copied from `std::sync::atomic::AtomicPtr`, with additional advice on how to `#[cfg]` for it.

I feel quite uncertain about whether the paragraph I added to `Arc`'s documentation should actually be there, as it is a distraction for anyone using `std`. On the other hand, maybe more reminders that no_std exists would benefit the ecosystem.

Note: `target_has_atomic` is [stabilized](rust-lang#32976) but [not yet documented in the reference](rust-lang/reference#1171).

docs: be less harsh in wording for Vec::from_raw_parts

In particular, be clear that it is sound to specify memory not
originating from a previous `Vec` allocation. That is already suggested
in other parts of the documentation about zero-alloc conversions to Box<[T]>.

Incorporate a constraint from `slice::from_raw_parts` that was missing
but needs to be fulfilled, since a `Vec` can be converted into a slice.

Fixes rust-lang#98780.

…riplett

docs: Improve AsRef / AsMut docs on blanket impls

There are several issues with the current state of `AsRef` and `AsMut` as [discussed here on IRLO](https://internals.rust-lang.org/t/semantics-of-asref/17016). See also rust-lang#39397, rust-lang#45742, rust-lang#73390, rust-lang#98905, and the FIXMEs [here](https://github.com/rust-lang/rust/blob/1.62.0/library/core/src/convert/mod.rs#L509-L515) and [here](https://github.com/rust-lang/rust/blob/1.62.0/library/core/src/convert/mod.rs#L530-L536). These issues are difficult to fix. This PR aims to update the documentation to better reflect the status-quo and to give advice on how `AsRef` and `AsMut` should be used.

In particular:

- Explicitly mention that `AsRef` and `AsMut` do not auto-dereference generally for all dereferencable types (but only if inner type is a shared and/or mutable reference)
- Give advice to not use `AsRef` or `AsMut` for the sole purpose of dereferencing
- Suggest providing a transitive `AsRef` or `AsMut` implementation for types which implement `Deref`
- Add new section "Reflexivity" in documentation comments for `AsRef` and `AsMut`
- Provide better example for `AsMut`
- Added heading "Relation to `Borrow`" in `AsRef`'s docs to improve structure

Tweak `FpCategory` example order.

Follow same order for variable declarations and assertions.

…default-annotated-derive, r=joshtriplett

Fix `#[derive(Default)]` on a generic `#[default]` enum adding unnecessary `Default` bounds

That is, given something like:

```rs
// #[default] on a generic enum does not add `Default` bounds to the type params.
#[derive(Default)]
enum MyOption<T> {
    #[default]
    None,
    Some(T),
}
```

then `MyOption<T> : Default`_as currently implemented_ only holds when `T : Default`, as reported by ``@5225225`` [over Zulip](https://rust-lang.zulipchat.com/#narrow/stream/122651-general/topic/.23.5Bderive.28Default.29.5D.20for.20enums.20with.20fields).

This is contrary to [what the accepted RFC proposes](https://rust-lang.github.io/rfcs/3107-derive-default-enum.html#generated-bounds) (_i.e._, that `T` be allowed not to be itself `Default`), and indeed seems to be a rather unnecessary limitation.

…git, r=joshtriplett

introduce `{char, u8}::is_ascii_octdigit`

This feature adds two new APIs: `char::is_ascii_octdigit` and `u8::is_ascii_octdigit`, under the feature gate `is_ascii_octdigit`. These methods are shorthands for `char::is_digit(self, 8)` and `u8::is_digit(self, 8)`:

```rust
// core::char

impl char {
    pub fn is_ascii_octdigit(self) -> bool;
}

// core::num

impl u8 {
    pub fn is_ascii_octdigit(self) -> bool;
}
```

---

Couple of things I need help understanding:

- `const`ness: have I used the right attribute in this case?
- is there a way to run the tests for `core::char` alone, instead of `./x.py test library/core`?

…compiler-errors

Add diagnostic struct for const eval error in `rustc_middle`

Part of rust-lang#100717.

r? `@ghost`