From ebe31bf115ce0b27d73d2f694f696d2b7b809813 Mon Sep 17 00:00:00 2001 From: Marijn Schouten Date: Fri, 10 Oct 2025 09:40:38 +0000 Subject: [PATCH] Better docs for PartialEq --- library/core/src/cmp.rs | 36 ++++++++++++++----- .../self-referential-2.current.stderr | 2 +- .../self-referential-3.stderr | 2 +- .../self-referential-4.stderr | 6 ++-- .../self-referential.stderr | 6 ++-- 5 files changed, 36 insertions(+), 16 deletions(-) diff --git a/library/core/src/cmp.rs b/library/core/src/cmp.rs index 3371b2cecbd79..328e9b47966c9 100644 --- a/library/core/src/cmp.rs +++ b/library/core/src/cmp.rs @@ -248,14 +248,26 @@ use crate::ops::ControlFlow; #[rustc_diagnostic_item = "PartialEq"] #[rustc_const_unstable(feature = "const_cmp", issue = "143800")] pub const trait PartialEq: PointeeSized { - /// Tests for `self` and `other` values to be equal, and is used by `==`. + /// Equality operator `==`. + /// + /// Implementation of the "is equal to" operator `==`: + /// tests whether its arguments are equal. #[must_use] #[stable(feature = "rust1", since = "1.0.0")] #[rustc_diagnostic_item = "cmp_partialeq_eq"] fn eq(&self, other: &Rhs) -> bool; - /// Tests for `!=`. The default implementation is almost always sufficient, - /// and should not be overridden without very good reason. + /// Inequality operator `!=`. + /// + /// Implementation of the "is not equal to" or "is different from" operator `!=`: + /// tests whether its arguments are different. + /// + /// # Default implementation + /// The default implementation of the inequality operator simply calls + /// the implementation of the equality operator and negates the result. + /// + /// This default shouldn't be overridden without good reason, + /// such as when forwarding to another PartialEq implementation. #[inline] #[must_use] #[stable(feature = "rust1", since = "1.0.0")] @@ -1869,19 +1881,31 @@ mod impls { use crate::ops::ControlFlow::{self, Break, Continue}; use crate::panic::const_assert; - macro_rules! partial_eq_impl { + /// Implements `PartialEq` for primitive types. + /// + /// Primitive types have a compiler-defined primitive implementation of `==` and `!=`. + /// This implements the `PartialEq` trait in terms of those primitive implementations. + /// + /// NOTE: Calling this on a non-primitive type (such as `()`) + /// leads to an infinitely-looping self-recursive implementation. + macro_rules! impl_partial_eq_for_primitive { ($($t:ty)*) => ($( #[stable(feature = "rust1", since = "1.0.0")] #[rustc_const_unstable(feature = "const_cmp", issue = "143800")] const impl PartialEq for $t { #[inline] fn eq(&self, other: &Self) -> bool { *self == *other } + // Override the default to use the primitive implementation for `!=`. #[inline] fn ne(&self, other: &Self) -> bool { *self != *other } } )*) } + impl_partial_eq_for_primitive! { + bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 + } + #[stable(feature = "rust1", since = "1.0.0")] #[rustc_const_unstable(feature = "const_cmp", issue = "143800")] const impl PartialEq for () { @@ -1895,10 +1919,6 @@ mod impls { } } - partial_eq_impl! { - bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 - } - macro_rules! eq_impl { ($($t:ty)*) => ($( #[stable(feature = "rust1", since = "1.0.0")] diff --git a/tests/ui/type-alias-impl-trait/self-referential-2.current.stderr b/tests/ui/type-alias-impl-trait/self-referential-2.current.stderr index ca26e3dd03f35..f656a274703ee 100644 --- a/tests/ui/type-alias-impl-trait/self-referential-2.current.stderr +++ b/tests/ui/type-alias-impl-trait/self-referential-2.current.stderr @@ -12,7 +12,7 @@ help: the trait `PartialEq` is not implemented for `i32` ::: $SRC_DIR/core/src/cmp.rs:LL:COL | = note: in this macro invocation - = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info) + = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info) error: aborting due to 1 previous error diff --git a/tests/ui/type-alias-impl-trait/self-referential-3.stderr b/tests/ui/type-alias-impl-trait/self-referential-3.stderr index 8592de243adac..7bc4c6def624d 100644 --- a/tests/ui/type-alias-impl-trait/self-referential-3.stderr +++ b/tests/ui/type-alias-impl-trait/self-referential-3.stderr @@ -13,7 +13,7 @@ help: the trait `PartialEq` is implemented for `i32` ::: $SRC_DIR/core/src/cmp.rs:LL:COL | = note: in this macro invocation - = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info) + = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info) error: aborting due to 1 previous error diff --git a/tests/ui/type-alias-impl-trait/self-referential-4.stderr b/tests/ui/type-alias-impl-trait/self-referential-4.stderr index c6bf1973fcbb1..76c5611906d34 100644 --- a/tests/ui/type-alias-impl-trait/self-referential-4.stderr +++ b/tests/ui/type-alias-impl-trait/self-referential-4.stderr @@ -12,7 +12,7 @@ help: the trait `PartialEq` is implemented for `i32` ::: $SRC_DIR/core/src/cmp.rs:LL:COL | = note: in this macro invocation - = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info) + = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info) error[E0277]: can't compare `&i32` with `Foo<'static, 'b>` --> $DIR/self-referential-4.rs:13:31 @@ -28,7 +28,7 @@ help: the trait `PartialEq` is implemented for `i32` ::: $SRC_DIR/core/src/cmp.rs:LL:COL | = note: in this macro invocation - = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info) + = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info) error[E0277]: can't compare `&i32` with `Moo<'static, 'a>` --> $DIR/self-referential-4.rs:20:31 @@ -44,7 +44,7 @@ help: the trait `PartialEq` is implemented for `i32` ::: $SRC_DIR/core/src/cmp.rs:LL:COL | = note: in this macro invocation - = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info) + = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info) error: aborting due to 3 previous errors diff --git a/tests/ui/type-alias-impl-trait/self-referential.stderr b/tests/ui/type-alias-impl-trait/self-referential.stderr index 7b4e6e9cac528..62d85466cde1a 100644 --- a/tests/ui/type-alias-impl-trait/self-referential.stderr +++ b/tests/ui/type-alias-impl-trait/self-referential.stderr @@ -13,7 +13,7 @@ help: the trait `PartialEq` is implemented for `i32` ::: $SRC_DIR/core/src/cmp.rs:LL:COL | = note: in this macro invocation - = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info) + = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info) error[E0277]: can't compare `&i32` with `(i32, Foo<'a, 'b>::{opaque#0}<'a, 'b>)` --> $DIR/self-referential.rs:14:31 @@ -30,7 +30,7 @@ help: the trait `PartialEq` is implemented for `i32` ::: $SRC_DIR/core/src/cmp.rs:LL:COL | = note: in this macro invocation - = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info) + = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info) error[E0277]: can't compare `&i32` with `(i32, Moo<'b, 'a>::{opaque#0}<'b, 'a>)` --> $DIR/self-referential.rs:22:31 @@ -47,7 +47,7 @@ help: the trait `PartialEq` is implemented for `i32` ::: $SRC_DIR/core/src/cmp.rs:LL:COL | = note: in this macro invocation - = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info) + = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info) error: aborting due to 3 previous errors