Rollup merge of #97233 - c410-f3r:assert-lib, r=scottmcm

[RFC 2011] Library code

CC https://github.com/rust-lang/rust/pull/96496

Based on https://github.com/dtolnay/case-studies/tree/master/autoref-specialization.

Basically creates two traits with the same method name. One trait is generic over any `T` and the other is specialized to any `T: Printable`.

The compiler will then call the corresponding trait method through auto reference.

```rust
fn main() {
    let mut a = Capture::new();
    let mut b = Capture::new();

    (&Wrapper(&1i32)).try_capture(&mut a); // `try_capture` from `TryCapturePrintable`
    (&Wrapper(&vec![1i32])).try_capture(&mut b); // `try_capture` from `TryCaptureGeneric`

    assert_eq!(format!("{:?}", a), "1");
    assert_eq!(format!("{:?}", b), "N/A");
}
```

r? `@scottmcm`

library/core/src/asserting.rs

+// Contains the machinery necessary to print useful `assert!` messages. Not intended for public
+// usage, not even nightly use-cases.
+//
+// Based on https://github.com/dtolnay/case-studies/tree/master/autoref-specialization. When
+// 'specialization' is robust enough (5 years? 10 years? Never?), `Capture` can be specialized
+// to [Printable].
+
+#![allow(missing_debug_implementations)]
+#![doc(hidden)]
+#![unstable(feature = "generic_assert_internals", issue = "44838")]
+
+use crate::{
+    fmt::{Debug, Formatter},
+    marker::PhantomData,
+};
+
+// ***** TryCapture - Generic *****
+
+/// Marker used by [Capture]
+#[unstable(feature = "generic_assert_internals", issue = "44838")]
+pub struct TryCaptureWithoutDebug;
+
+/// Catches an arbitrary `E` and modifies `to` accordingly
+#[unstable(feature = "generic_assert_internals", issue = "44838")]
+pub trait TryCaptureGeneric<E, M> {
+    /// Similar to [TryCapturePrintable] but generic to any `E`.
+    fn try_capture(&self, to: &mut Capture<E, M>);
+}
+
+impl<E> TryCaptureGeneric<E, TryCaptureWithoutDebug> for &Wrapper<&E> {
+    #[inline]
+    fn try_capture(&self, _: &mut Capture<E, TryCaptureWithoutDebug>) {}
+}
+
+impl<E> Debug for Capture<E, TryCaptureWithoutDebug> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), core::fmt::Error> {
+        f.write_str("N/A")
+    }
+}
+
+// ***** TryCapture - Printable *****
+
+/// Marker used by [Capture]
+#[unstable(feature = "generic_assert_internals", issue = "44838")]
+pub struct TryCaptureWithDebug;
+
+/// Catches an arbitrary `E: Printable` and modifies `to` accordingly
+#[unstable(feature = "generic_assert_internals", issue = "44838")]
+pub trait TryCapturePrintable<E, M> {
+    /// Similar as [TryCaptureGeneric] but specialized to any `E: Printable`.
+    fn try_capture(&self, to: &mut Capture<E, M>);
+}
+
+impl<E> TryCapturePrintable<E, TryCaptureWithDebug> for Wrapper<&E>
+where
+    E: Printable,
+{
+    #[inline]
+    fn try_capture(&self, to: &mut Capture<E, TryCaptureWithDebug>) {
+        to.elem = Some(*self.0);
+    }
+}
+
+impl<E> Debug for Capture<E, TryCaptureWithDebug>
+where
+    E: Printable,
+{
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), core::fmt::Error> {
+        match self.elem {
+            None => f.write_str("N/A"),
+            Some(ref value) => Debug::fmt(value, f),
+        }
+    }
+}
+
+// ***** Others *****
+
+/// All possible captured `assert!` elements
+///
+/// # Types
+///
+/// * `E`: **E**lement that is going to be displayed.
+/// * `M`: **M**arker used to differentiate [Capture]s in regards to [Debug].
+#[unstable(feature = "generic_assert_internals", issue = "44838")]
+pub struct Capture<E, M> {
+    // If None, then `E` does not implements [Printable] or `E` wasn't evaluated (`assert!( ... )`
+    // short-circuited).
+    //
+    // If Some, then `E` implements [Printable] and was evaluated.
+    pub elem: Option<E>,
+    phantom: PhantomData<M>,
+}
+
+impl<M, T> Capture<M, T> {
+    #[inline]
+    pub const fn new() -> Self {
+        Self { elem: None, phantom: PhantomData }
+    }
+}
+
+/// Necessary for the implementations of `TryCapture*`
+#[unstable(feature = "generic_assert_internals", issue = "44838")]
+pub struct Wrapper<T>(pub T);
+
+/// Tells which elements can be copied and displayed
+#[unstable(feature = "generic_assert_internals", issue = "44838")]
+pub trait Printable: Copy + Debug {}
+
+impl<T> Printable for T where T: Copy + Debug {}

library/core/src/lib.rs

@@ -310,6 +310,7 @@ pub mod assert_matches {
 pub mod any;
 pub mod array;
 pub mod ascii;
+pub mod asserting;
 #[unstable(feature = "async_iterator", issue = "79024")]
 pub mod async_iter;
 pub mod cell;

library/core/tests/asserting.rs

+use core::asserting::{Capture, TryCaptureGeneric, TryCapturePrintable, Wrapper};
+
+macro_rules! test {
+    ($test_name:ident, $elem:expr, $captured_elem:expr, $output:literal) => {
+        #[test]
+        fn $test_name() {
+            let elem = $elem;
+            let mut capture = Capture::new();
+            assert!(capture.elem == None);
+            (&Wrapper(&elem)).try_capture(&mut capture);
+            assert!(capture.elem == $captured_elem);
+            assert_eq!(format!("{:?}", capture), $output);
+        }
+    };
+}
+
+#[derive(Debug, PartialEq)]
+struct NoCopy;
+
+#[derive(PartialEq)]
+struct NoCopyNoDebug;
+
+#[derive(Clone, Copy, PartialEq)]
+struct NoDebug;
+
+test!(
+    capture_with_non_copyable_and_non_debugabble_elem_has_correct_params,
+    NoCopyNoDebug,
+    None,
+    "N/A"
+);
+
+test!(capture_with_non_copyable_elem_has_correct_params, NoCopy, None, "N/A");
+
+test!(capture_with_non_debugabble_elem_has_correct_params, NoDebug, None, "N/A");
+
+test!(capture_with_copyable_and_debugabble_elem_has_correct_params, 1i32, Some(1i32), "1");

library/core/tests/lib.rs

@@ -35,6 +35,7 @@
 #![feature(float_minimum_maximum)]
 #![feature(future_join)]
 #![feature(future_poll_fn)]
+#![feature(generic_assert_internals)]
 #![feature(array_try_from_fn)]
 #![feature(hasher_prefixfree_extras)]
 #![feature(hashmap_internals)]
@@ -104,6 +105,7 @@
 mod any;
 mod array;
 mod ascii;
+mod asserting;
 mod atomic;
 mod bool;
 mod cell;