Auto merge of #77224 - RalfJung:rollup-hdvb96c, r=RalfJung

Rollup of 12 pull requests

Successful merges:

 - #75454 (Explicitly document the size guarantees that Option makes.)
 - #76631 (Add `x.py setup`)
 - #77076 (Add missing code examples on slice iter types)
 - #77093 (merge `need_type_info_err(_const)`)
 - #77122 (Add `#![feature(const_fn_floating_point_arithmetic)]`)
 - #77127 (Update mdBook)
 - #77161 (Remove TrustedLen requirement from BuilderMethods::switch)
 - #77166 (update Miri)
 - #77181 (Add doc alias for pointer primitive)
 - #77204 (Remove stray word from `ClosureKind::extends` docs)
 - #77207 (Rename `whence` to `span`)
 - #77211 (Remove unused #[allow(...)] statements from compiler/)

Failed merges:

 - #77170 (Remove `#[rustc_allow_const_fn_ptr]` and add `#![feature(const_fn_fn_ptr_basics)]`)

r? `@ghost`

3 files changed, 182 insertions, 4 deletions

diff --git a/library/core/src/lib.rs b/library/core/src/lib.rs
index 63ca6e517d2..30fb87b0226 100644
--- a/library/core/src/lib.rs
+++ b/library/core/src/lib.rs
@@ -82,6 +82,7 @@
 #![feature(const_pin)]
 #![feature(const_fn_union)]
 #![feature(const_fn)]
+#![cfg_attr(not(bootstrap), feature(const_fn_floating_point_arithmetic))]
 #![feature(const_generics)]
 #![feature(const_option)]
 #![feature(const_precise_live_drops)]
diff --git a/library/core/src/option.rs b/library/core/src/option.rs
index b1589008be0..0cfb4af59b9 100644
--- a/library/core/src/option.rs
+++ b/library/core/src/option.rs
@@ -70,10 +70,23 @@
 //! }
 //! ```
 //!
-//! This usage of [`Option`] to create safe nullable pointers is so
-//! common that Rust does special optimizations to make the
-//! representation of [`Option`]`<`[`Box<T>`]`>` a single pointer. Optional pointers
-//! in Rust are stored as efficiently as any other pointer type.
+//! # Representation
+//!
+//! Rust guarantees to optimize the following types `T` such that
+//! [`Option<T>`] has the same size as `T`:
+//!
+//! * [`Box<U>`]
+//! * `&U`
+//! * `&mut U`
+//! * `fn`, `extern "C" fn`
+//! * [`num::NonZero*`]
+//! * [`ptr::NonNull<U>`]
+//! * `#[repr(transparent)]` struct around one of the types in this list.
+//!
+//! It is further guaranteed that, for the cases above, one can
+//! [`mem::transmute`] from all valid values of `T` to `Option<T>` and
+//! from `Some::<T>(_)` to `T` (but transmuting `None::<T>` to `T`
+//! is undefined behaviour).
 //!
 //! # Examples
 //!
diff --git a/library/core/src/slice/iter.rs b/library/core/src/slice/iter.rs
index 76b8aa7d821..793cbf99495 100644
--- a/library/core/src/slice/iter.rs
+++ b/library/core/src/slice/iter.rs
@@ -319,6 +319,13 @@ pub(super) trait SplitIter: DoubleEndedIterator {
 ///
 /// This struct is created by the [`split`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let slice = [10, 40, 33, 20];
+/// let mut iter = slice.split(|num| num % 3 == 0);
+/// ```
+///
 /// [`split`]: ../../std/primitive.slice.html#method.split
 /// [slices]: ../../std/primitive.slice.html
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -434,6 +441,15 @@ impl<T, P> FusedIterator for Split<'_, T, P> where P: FnMut(&T) -> bool {}
 ///
 /// This struct is created by the [`split_inclusive`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// #![feature(split_inclusive)]
+///
+/// let slice = [10, 40, 33, 20];
+/// let mut iter = slice.split_inclusive(|num| num % 3 == 0);
+/// ```
+///
 /// [`split_inclusive`]: ../../std/primitive.slice.html#method.split_inclusive
 /// [slices]: ../../std/primitive.slice.html
 #[unstable(feature = "split_inclusive", issue = "72360")]
@@ -539,6 +555,13 @@ impl<T, P> FusedIterator for SplitInclusive<'_, T, P> where P: FnMut(&T) -> bool
 ///
 /// This struct is created by the [`split_mut`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let mut v = [10, 40, 30, 20, 60, 50];
+/// let iter = v.split_mut(|num| *num % 3 == 0);
+/// ```
+///
 /// [`split_mut`]: ../../std/primitive.slice.html#method.split_mut
 /// [slices]: ../../std/primitive.slice.html
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -661,6 +684,15 @@ impl<T, P> FusedIterator for SplitMut<'_, T, P> where P: FnMut(&T) -> bool {}
 ///
 /// This struct is created by the [`split_inclusive_mut`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// #![feature(split_inclusive)]
+///
+/// let mut v = [10, 40, 30, 20, 60, 50];
+/// let iter = v.split_inclusive_mut(|num| *num % 3 == 0);
+/// ```
+///
 /// [`split_inclusive_mut`]: ../../std/primitive.slice.html#method.split_inclusive_mut
 /// [slices]: ../../std/primitive.slice.html
 #[unstable(feature = "split_inclusive", issue = "72360")]
@@ -775,6 +807,13 @@ impl<T, P> FusedIterator for SplitInclusiveMut<'_, T, P> where P: FnMut(&T) -> b
 ///
 /// This struct is created by the [`rsplit`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let slice = [11, 22, 33, 0, 44, 55];
+/// let iter = slice.rsplit(|num| *num == 0);
+/// ```
+///
 /// [`rsplit`]: ../../std/primitive.slice.html#method.rsplit
 /// [slices]: ../../std/primitive.slice.html
 #[stable(feature = "slice_rsplit", since = "1.27.0")]
@@ -854,6 +893,13 @@ impl<T, P> FusedIterator for RSplit<'_, T, P> where P: FnMut(&T) -> bool {}
 ///
 /// This struct is created by the [`rsplit_mut`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let mut slice = [11, 22, 33, 0, 44, 55];
+/// let iter = slice.rsplit_mut(|num| *num == 0);
+/// ```
+///
 /// [`rsplit_mut`]: ../../std/primitive.slice.html#method.rsplit_mut
 /// [slices]: ../../std/primitive.slice.html
 #[stable(feature = "slice_rsplit", since = "1.27.0")]
@@ -966,6 +1012,13 @@ impl<T, I: SplitIter<Item = T>> Iterator for GenericSplitN<I> {
 ///
 /// This struct is created by the [`splitn`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let slice = [10, 40, 30, 20, 60, 50];
+/// let iter = slice.splitn(2, |num| *num % 3 == 0);
+/// ```
+///
 /// [`splitn`]: ../../std/primitive.slice.html#method.splitn
 /// [slices]: ../../std/primitive.slice.html
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -999,6 +1052,13 @@ where
 ///
 /// This struct is created by the [`rsplitn`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let slice = [10, 40, 30, 20, 60, 50];
+/// let iter = slice.rsplitn(2, |num| *num % 3 == 0);
+/// ```
+///
 /// [`rsplitn`]: ../../std/primitive.slice.html#method.rsplitn
 /// [slices]: ../../std/primitive.slice.html
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -1031,6 +1091,13 @@ where
 ///
 /// This struct is created by the [`splitn_mut`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let mut slice = [10, 40, 30, 20, 60, 50];
+/// let iter = slice.splitn_mut(2, |num| *num % 3 == 0);
+/// ```
+///
 /// [`splitn_mut`]: ../../std/primitive.slice.html#method.splitn_mut
 /// [slices]: ../../std/primitive.slice.html
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -1064,6 +1131,13 @@ where
 ///
 /// This struct is created by the [`rsplitn_mut`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let mut slice = [10, 40, 30, 20, 60, 50];
+/// let iter = slice.rsplitn_mut(2, |num| *num % 3 == 0);
+/// ```
+///
 /// [`rsplitn_mut`]: ../../std/primitive.slice.html#method.rsplitn_mut
 /// [slices]: ../../std/primitive.slice.html
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -1100,6 +1174,13 @@ forward_iterator! { RSplitNMut: T, &'a mut [T] }
 ///
 /// This struct is created by the [`windows`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let slice = ['r', 'u', 's', 't'];
+/// let iter = slice.windows(2);
+/// ```
+///
 /// [`windows`]: ../../std/primitive.slice.html#method.windows
 /// [slices]: ../../std/primitive.slice.html
 #[derive(Debug)]
@@ -1239,6 +1320,13 @@ unsafe impl<'a, T> TrustedRandomAccess for Windows<'a, T> {
 ///
 /// This struct is created by the [`chunks`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let slice = ['l', 'o', 'r', 'e', 'm'];
+/// let iter = slice.chunks(2);
+/// ```
+///
 /// [`chunks`]: ../../std/primitive.slice.html#method.chunks
 /// [slices]: ../../std/primitive.slice.html
 #[derive(Debug)]
@@ -1400,6 +1488,13 @@ unsafe impl<'a, T> TrustedRandomAccess for Chunks<'a, T> {
 ///
 /// This struct is created by the [`chunks_mut`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let mut slice = ['l', 'o', 'r', 'e', 'm'];
+/// let iter = slice.chunks_mut(2);
+/// ```
+///
 /// [`chunks_mut`]: ../../std/primitive.slice.html#method.chunks_mut
 /// [slices]: ../../std/primitive.slice.html
 #[derive(Debug)]
@@ -1559,6 +1654,13 @@ unsafe impl<'a, T> TrustedRandomAccess for ChunksMut<'a, T> {
 ///
 /// This struct is created by the [`chunks_exact`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let slice = ['l', 'o', 'r', 'e', 'm'];
+/// let iter = slice.chunks_exact(2);
+/// ```
+///
 /// [`chunks_exact`]: ../../std/primitive.slice.html#method.chunks_exact
 /// [`remainder`]: ChunksExact::remainder
 /// [slices]: ../../std/primitive.slice.html
@@ -1708,6 +1810,13 @@ unsafe impl<'a, T> TrustedRandomAccess for ChunksExact<'a, T> {
 ///
 /// This struct is created by the [`chunks_exact_mut`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let mut slice = ['l', 'o', 'r', 'e', 'm'];
+/// let iter = slice.chunks_exact_mut(2);
+/// ```
+///
 /// [`chunks_exact_mut`]: ../../std/primitive.slice.html#method.chunks_exact_mut
 /// [`into_remainder`]: ChunksExactMut::into_remainder
 /// [slices]: ../../std/primitive.slice.html
@@ -1850,6 +1959,15 @@ unsafe impl<'a, T> TrustedRandomAccess for ChunksExactMut<'a, T> {
 ///
 /// This struct is created by the [`array_windows`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// #![feature(array_windows)]
+///
+/// let slice = [0, 1, 2, 3];
+/// let iter = slice.array_windows::<2>();
+/// ```
+///
 /// [`array_windows`]: ../../std/primitive.slice.html#method.array_windows
 /// [slices]: ../../std/primitive.slice.html
 #[derive(Debug, Clone, Copy)]
@@ -1962,6 +2080,15 @@ impl<T, const N: usize> ExactSizeIterator for ArrayWindows<'_, T, N> {
 ///
 /// This struct is created by the [`array_chunks`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// #![feature(array_chunks)]
+///
+/// let slice = ['l', 'o', 'r', 'e', 'm'];
+/// let iter = slice.array_chunks::<2>();
+/// ```
+///
 /// [`array_chunks`]: ../../std/primitive.slice.html#method.array_chunks
 /// [`remainder`]: ArrayChunks::remainder
 /// [slices]: ../../std/primitive.slice.html
@@ -2080,6 +2207,15 @@ unsafe impl<'a, T, const N: usize> TrustedRandomAccess for ArrayChunks<'a, T, N>
 ///
 /// This struct is created by the [`array_chunks_mut`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// #![feature(array_chunks)]
+///
+/// let mut slice = ['l', 'o', 'r', 'e', 'm'];
+/// let iter = slice.array_chunks_mut::<2>();
+/// ```
+///
 /// [`array_chunks_mut`]: ../../std/primitive.slice.html#method.array_chunks_mut
 /// [`into_remainder`]: ../../std/slice/struct.ArrayChunksMut.html#method.into_remainder
 /// [slices]: ../../std/primitive.slice.html
@@ -2190,6 +2326,13 @@ unsafe impl<'a, T, const N: usize> TrustedRandomAccess for ArrayChunksMut<'a, T,
 ///
 /// This struct is created by the [`rchunks`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let slice = ['l', 'o', 'r', 'e', 'm'];
+/// let iter = slice.rchunks(2);
+/// ```
+///
 /// [`rchunks`]: ../../std/primitive.slice.html#method.rchunks
 /// [slices]: ../../std/primitive.slice.html
 #[derive(Debug)]
@@ -2347,6 +2490,13 @@ unsafe impl<'a, T> TrustedRandomAccess for RChunks<'a, T> {
 ///
 /// This struct is created by the [`rchunks_mut`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let mut slice = ['l', 'o', 'r', 'e', 'm'];
+/// let iter = slice.rchunks_mut(2);
+/// ```
+///
 /// [`rchunks_mut`]: ../../std/primitive.slice.html#method.rchunks_mut
 /// [slices]: ../../std/primitive.slice.html
 #[derive(Debug)]
@@ -2504,6 +2654,13 @@ unsafe impl<'a, T> TrustedRandomAccess for RChunksMut<'a, T> {
 ///
 /// This struct is created by the [`rchunks_exact`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let slice = ['l', 'o', 'r', 'e', 'm'];
+/// let iter = slice.rchunks_exact(2);
+/// ```
+///
 /// [`rchunks_exact`]: ../../std/primitive.slice.html#method.rchunks_exact
 /// [`remainder`]: ChunksExact::remainder
 /// [slices]: ../../std/primitive.slice.html
@@ -2657,6 +2814,13 @@ unsafe impl<'a, T> TrustedRandomAccess for RChunksExact<'a, T> {
 ///
 /// This struct is created by the [`rchunks_exact_mut`] method on [slices].
 ///
+/// # Example
+///
+/// ```
+/// let mut slice = ['l', 'o', 'r', 'e', 'm'];
+/// let iter = slice.rchunks_exact_mut(2);
+/// ```
+///
 /// [`rchunks_exact_mut`]: ../../std/primitive.slice.html#method.rchunks_exact_mut
 /// [`into_remainder`]: ChunksExactMut::into_remainder
 /// [slices]: ../../std/primitive.slice.html