Skip to content

Better docs for PartialEq (includes macro rename) #156144

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rust-bors merged 1 commit into from
Jul 9, 2026
+36 −16
Merged

Better docs for PartialEq (includes macro rename) #156144

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 28 additions & 8 deletions library/core/src/cmp.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -248,14 +248,26 @@ use crate::ops::ControlFlow;
#[rustc_diagnostic_item = "PartialEq"]
#[rustc_const_unstable(feature = "const_cmp", issue = "143800")]
pub const trait PartialEq<Rhs: PointeeSized = Self>: 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.

@nia-e nia-e May 4, 2026 •
edited by rustbot
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This warning should probably remain in some form

View changes since the review

@hkBst hkBst May 4, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've now tried to reword to mention the few cases where it could make sense to override (line 269).

/// 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")]
Expand Down Expand Up @@ -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 () {
Expand All @@ -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")]
Expand Down
2 changes: 1 addition & 1 deletion tests/ui/type-alias-impl-trait/self-referential-2.current.stderr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ help: the trait `PartialEq<Foo>` 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

Expand Down
2 changes: 1 addition & 1 deletion tests/ui/type-alias-impl-trait/self-referential-3.stderr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 3 additions & 3 deletions tests/ui/type-alias-impl-trait/self-referential-4.stderr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down
6 changes: 3 additions & 3 deletions tests/ui/type-alias-impl-trait/self-referential.stderr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down
Loading