Trait for comparisons using the equality operator.

Implementing this trait for types provides the== and!= operators forthose types.

x.eq(y) can also be writtenx == y, andx.ne(y) can be writtenx != y.We use the easier-to-read infix notation in the remainder of this documentation.

This trait allows for comparisons using the equality operator, for typesthat do not have a full equivalence relation. For example, in floating pointnumbersNaN != NaN, so floating point types implementPartialEq but notEq. Formally speaking, whenRhs == Self, this trait correspondsto apartial equivalence relation.

Implementations must ensure thateq andne are consistent with each other:

• a != b if and only if!(a == b).

The default implementation ofne provides this consistency and is almostalways sufficient. It should not be overridden without very good reason.

IfPartialOrd orOrd are also implemented forSelf andRhs, their methods must alsobe consistent withPartialEq (see the documentation of those traits for the exactrequirements). It’s easy to accidentally make them disagree by deriving some of the traits andmanually implementing others.

The equality relation== must satisfy the following conditions(for alla,b,c of typeA,B,C):

• Symmetry: ifA: PartialEq<B> andB: PartialEq<A>, thena == bimpliesb == a; and

• Transitivity: ifA: PartialEq<B> andB: PartialEq<C> andA: PartialEq<C>, thena == b andb == c impliesa == c.This must also work for longer chains, such as whenA: PartialEq<B>,B: PartialEq<C>,C: PartialEq<D>, andA: PartialEq<D> all exist.

Note that theB: PartialEq<A> (symmetric) andA: PartialEq<C>(transitive) impls are not forced to exist, but these requirements applywhenever they do exist.

Violating these requirements is a logic error. The behavior resulting from a logic error is notspecified, but users of the trait must ensure that such logic errors donot result inundefined behavior. This means thatunsafe codemust not rely on the correctness of thesemethods.

§Cross-crate considerations

Upholding the requirements stated above can become tricky when one crate implementsPartialEqfor a type of another crate (i.e., to allow comparing one of its own types with a type from thestandard library). The recommendation is to never implement this trait for a foreign type. Inother words, such a crate should doimpl PartialEq<ForeignType> for LocalType, but it shouldnot doimpl PartialEq<LocalType> for ForeignType.

This avoids the problem of transitive chains that criss-cross crate boundaries: for all localtypesT, you may assume that no other crate will addimpls that allow comparingT == U. Inother words, if other crates addimpls that allow building longer transitive chainsU1 == ... == T == V1 == ..., then all the types that appear to the right ofT must be types that thecrate definingT already knows about. This rules out transitive chains where downstream cratescan add newimpls that “stitch together” comparisons of foreign types in ways that violatetransitivity.

Not having such foreignimpls also avoids forward compatibility issues where one crate addingmorePartialEq implementations can cause build failures in downstream crates.

§Derivable

This trait can be used with#[derive]. Whenderived on structs, twoinstances are equal if all fields are equal, and not equal if any fieldsare not equal. Whenderived on enums, two instances are equal if theyare the same variant and all fields are equal.

§How can I implementPartialEq?

An example implementation for a domain in which two books are consideredthe same book if their ISBN matches, even if the formats differ:

enumBookFormat {    Paperback,    Hardback,    Ebook,}structBook {    isbn: i32,    format: BookFormat,}implPartialEqforBook {fneq(&self, other:&Self) -> bool {self.isbn == other.isbn    }}letb1 = Book { isbn:3, format: BookFormat::Paperback };letb2 = Book { isbn:3, format: BookFormat::Ebook };letb3 = Book { isbn:10, format: BookFormat::Paperback };assert!(b1 == b2);assert!(b1 != b3);

§How can I compare two different types?

The type you can compare with is controlled byPartialEq’s type parameter.For example, let’s tweak our previous code a bit:

// The derive implements <BookFormat> == <BookFormat> comparisons#[derive(PartialEq)]enumBookFormat {    Paperback,    Hardback,    Ebook,}structBook {    isbn: i32,    format: BookFormat,}// Implement <Book> == <BookFormat> comparisonsimplPartialEq<BookFormat>forBook {fneq(&self, other:&BookFormat) -> bool {self.format ==*other    }}// Implement <BookFormat> == <Book> comparisonsimplPartialEq<Book>forBookFormat {fneq(&self, other:&Book) -> bool {*self== other.format    }}letb1 = Book { isbn:3, format: BookFormat::Paperback };assert!(b1 == BookFormat::Paperback);assert!(BookFormat::Ebook != b1);

By changingimpl PartialEq for Book toimpl PartialEq<BookFormat> for Book,we allowBookFormats to be compared withBooks.

A comparison like the one above, which ignores some fields of the struct,can be dangerous. It can easily lead to an unintended violation of therequirements for a partial equivalence relation. For example, if we keptthe above implementation ofPartialEq<Book> forBookFormat and added animplementation ofPartialEq<Book> forBook (either via a#[derive] orvia the manual implementation from the first example) then the result wouldviolate transitivity:

#[derive(PartialEq)]enumBookFormat {    Paperback,    Hardback,    Ebook,}#[derive(PartialEq)]structBook {    isbn: i32,    format: BookFormat,}implPartialEq<BookFormat>forBook {fneq(&self, other:&BookFormat) -> bool {self.format ==*other    }}implPartialEq<Book>forBookFormat {fneq(&self, other:&Book) -> bool {*self== other.format    }}fnmain() {letb1 = Book { isbn:1, format: BookFormat::Paperback };letb2 = Book { isbn:2, format: BookFormat::Paperback };assert!(b1 == BookFormat::Paperback);assert!(BookFormat::Paperback == b2);// The following should hold by transitivity but doesn't.assert!(b1 == b2);// <-- PANICS}

§Examples

letx: u32 =0;lety: u32 =1;assert_eq!(x == y,false);assert_eq!(x.eq(&y),false);