Skip to content

document assumptions about Clone and Eq traits #144330

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
merged 5 commits into from
Aug 11, 2025
+33 −0
Merged

document assumptions about Clone and Eq traits #144330

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
30033b4
document assumptions about `Clone` and `Eq` traits
gewitternacht Jul 22, 2025
cdbcd72
remove trailing whitespace
gewitternacht Jul 22, 2025
623317e
add links to collections
gewitternacht Jul 22, 2025
c72bb70
clearer wording for `unsafe` code
gewitternacht Jul 29, 2025
fadc961
mention `Hash` and `Ord`; refine description of `derive`
gewitternacht Aug 10, 2025
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
29 changes: 29 additions & 0 deletions library/core/src/clone.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,30 @@ mod uninit;
/// // Note: With the manual implementations the above line will compile.
/// ```
///
/// ## `Clone` and `PartialEq`/`Eq`
Copy link
Member

Choose a reason for hiding this comment

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

It's unclear whether this should apply to PartialEq.

However this definitely needs to be extended to include Hash and Ord since HashMap and BTreeMap rely on this. It could also have vague wording that this may extend to other traits as well.

Copy link
Contributor Author

@gewitternacht gewitternacht Aug 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

It's unclear whether this should apply to PartialEq.

Do you mean this in the sense that the property cannot be required of PartialEq and Clone as we might have to deliberalty break it in some contexts? Or in the sense that we just don't know of anything that depends on this property for PartialEq?
In case of the latter, I would argue that the documentation of Clone – "creation of a duplicate value" – very strongly suggests that I get the "same" thing by cloning, and PartialEq defines "sameness" of objects. E.g., if f == 1.0_f64, I expect that f.clone() == 1.0_f64, too. But without the property x == x -> x.clone() == x, this is never explicitly guaranteed anywhere.

However this definitely needs to be extended to include Hash and Ord since HashMap and BTreeMap rely on this. It could also have vague wording that this may extend to other traits as well.

I only wrote about PartialEq/Eq because x.clone() == x already ensures that clone preserves the hash and ordering of elements, when put together with the guarantees that are required of Hash (see "Hash and Eq") and Ord (due to the conditions for PartialOrd). But I could make this interaction explicit.

Copy link
Member

Choose a reason for hiding this comment

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

Now that I think about it, you are correct and PartialEq is the right place to introduce this requirement.

/// `Clone` is intended for the duplication of objects. Consequently, when implementing
/// both `Clone` and [`PartialEq`], the following property is expected to hold:
/// ```text
/// x == x -> x.clone() == x
/// ```
/// In other words, if an object compares equal to itself,
/// its clone must also compare equal to the original.
///
/// For types that also implement [`Eq`] – for which `x == x` always holds –
/// this implies that `x.clone() == x` must always be true.
/// Standard library collections such as
/// [`HashMap`], [`HashSet`], [`BTreeMap`], [`BTreeSet`] and [`BinaryHeap`]
/// rely on their keys respecting this property for correct behavior.
///
/// This property is automatically satisfied when deriving both `Clone` and [`PartialEq`]
/// using `#[derive(Clone, PartialEq)]` or when additionally deriving [`Eq`]
/// using `#[derive(Clone, PartialEq, Eq)]`.
///
/// Violating this property is a logic error. The behavior resulting from a logic error is not
/// specified, but users of the trait must ensure that such logic errors do *not* result in
/// undefined behavior. This means that `unsafe` code **must not** rely on the correctness of these
/// methods.
Copy link
Member

Choose a reason for hiding this comment

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

It's a bit confusing to say "these methods" here IMO - maybe "this property"?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I agree, I could change it to "... rely on this property being satisfied."

The reason behind the "correctness of these methods" wording is that it is phrased like this in the documentation on Hash and Eq, as well as the Eq and PartialEq trait documentation. I found it confusing there, too, but I thought it was just because I lacked experience with the terminology.
So, would you say the wording in these other places is confusing, too? And if so, should I make it part of this PR to change it there, too? (my first time doing a PR like this, so I'm still learning best practices)

///
/// ## Additional implementors
///
/// In addition to the [implementors listed below][impls],
Expand All @@ -152,6 +176,11 @@ mod uninit;
/// (even if the referent doesn't),
/// while variables captured by mutable reference never implement `Clone`.
///
/// [`HashMap`]: ../../std/collections/struct.HashMap.html
/// [`HashSet`]: ../../std/collections/struct.HashSet.html
/// [`BTreeMap`]: ../../std/collections/struct.BTreeMap.html
/// [`BTreeSet`]: ../../std/collections/struct.BTreeSet.html
/// [`BinaryHeap`]: ../../std/collections/struct.BinaryHeap.html
/// [impls]: #implementors
#[stable(feature = "rust1", since = "1.0.0")]
#[lang = "clone"]
Expand Down
Loading