Auto merge of #103046 - JanBeh:PR_clarify_cmp_terminology, r=workingj… · rust-lang/rust@3bcad65 (original) (raw)

`@@ -3,14 +3,17 @@

3

`//! This module contains various tools for comparing and ordering values. In

4

`//! summary:

5

`//!

6

`` -

//! * [Eq] and [PartialEq] are traits that allow you to define total and

7

//! partial equality between values, respectively. Implementing them overloads

8

`` -

//! the == and != operators.

6

`` +

//! * [PartialEq<Rhs>] overloads the == and != operators. In cases where

7

`` +

//! Rhs (the right hand side's type) is Self, this trait corresponds to a

8

//! partial equivalence relation.

9

`` +

//! * [Eq] indicates that the overloaded == operator corresponds to an

10

//! equivalence relation.

9

11

`` //! * [Ord] and [PartialOrd] are traits that allow you to define total and

10

12

`//! partial orderings between values, respectively. Implementing them overloads

11

13

`` //! the <, <=, >, and >= operators.

12

14

`` //! * [Ordering] is an enum returned by the main functions of [Ord] and

13

`` -

//! [PartialOrd], and describes an ordering.

15

`` +

//! [PartialOrd], and describes an ordering of two values (less, equal, or

16

//! greater).

14

17

`` //! * [Reverse] is a struct that allows you to easily reverse an ordering.

15

18

`` //! * [max] and [min] are functions that build off of [Ord] and allow you

16

19

`//! to find the maximum or minimum of two values.

`@@ -27,16 +30,21 @@ pub(crate) use bytewise::BytewiseEq;

27

30

28

31

`use self::Ordering::*;

29

32

30

/// Trait for equality comparisons.

33

/// Trait for comparisons using the equality operator.

34

///

35

`` +

/// Implementing this trait for types provides the == and != operators for

36

/// those types.

31

37

`///

32

38

`` /// x.eq(y) can also be written x == y, and x.ne(y) can be written x != y.

33

39

`/// We use the easier-to-read infix notation in the remainder of this documentation.

34

40

`///

35

/// This trait allows for partial equality, for types that do not have a full

36

`` -

/// equivalence relation. For example, in floating point numbers NaN != NaN,

37

`` -

/// so floating point types implement PartialEq but not [trait@Eq].

38

`` -

/// Formally speaking, when Rhs == Self, this trait corresponds to a [partial equivalence

39

/// relation](https://en.wikipedia.org/wiki/Partial_equivalence_relation).

41

/// This trait allows for comparisons using the equality operator, for types

42

/// that do not have a full equivalence relation. For example, in floating point

43

`` +

/// numbers NaN != NaN, so floating point types implement PartialEq but not

44

`` +

/// [trait@Eq]. Formally speaking, when Rhs == Self, this trait corresponds

45

/// to a [partial equivalence relation].

46

///

47

/// [partial equivalence relation]: https://en.wikipedia.org/wiki/Partial_equivalence_relation

40

48

`///

41

49

`` /// Implementations must ensure that eq and ne are consistent with each other:

42

50

`///

`@@ -242,15 +250,15 @@ pub macro PartialEq($item:item) {

242

250

`/* compiler built-in */

243

251

244

252

245

/// Trait for equality comparisons which are [equivalence relations](

253

/// Trait for comparisons corresponding to [equivalence relations](

246

254

`/// https://en.wikipedia.org/wiki/Equivalence_relation).

247

255

`///

248

`` -

/// This means, that in addition to a == b and a != b being strict inverses, the equality must

249

`` -

/// be (for all a, b and c):

256

`` +

/// This means, that in addition to a == b and a != b being strict inverses,

257

`` +

/// the relation must be (for all a, b and c):

250

258

`///

251

259

`` /// - reflexive: a == a;

252

`` -

/// - symmetric: a == b implies b == a; and

253

`` -

/// - transitive: a == b and b == c implies a == c.

260

`` +

/// - symmetric: a == b implies b == a (required by PartialEq as well); and

261

`` +

/// - transitive: a == b and b == c implies a == c (required by PartialEq as well).

254

262

`///

255

263

`` /// This property cannot be checked by the compiler, and therefore Eq implies

256

264

`` /// [PartialEq], and has no extra methods.

`@@ -260,6 +268,10 @@ pub macro PartialEq($item:item) {

260

268

`` /// undefined behavior. This means that unsafe code must not rely on the correctness of these

261

269

`/// methods.

262

270

`///

271

`` +

/// Implement Eq in addition to PartialEq if it's guaranteed that

272

`` +

/// PartialEq::eq(a, a) always returns true (reflexivity), in addition to

273

`` +

/// the symmetric and transitive properties already required by PartialEq.

274

///

263

275

`/// ## Derivable

264

276

`///

265

277

`` /// This trait can be used with #[derive]. When derived, because Eq has

`@@ -676,12 +688,19 @@ impl<T: Clone> Clone for Reverse {

676

688

`///

677

689

`/// ## Corollaries

678

690

`///

679

`` -

/// From the above and the requirements of PartialOrd, it follows that < defines a strict total order.

680

`` -

/// This means that for all a, b and c:

691

`` +

/// From the above and the requirements of PartialOrd, it follows that for

692

`` +

/// all a, b and c:

681

693

`///

682

694

`` /// - exactly one of a < b, a == b or a > b is true; and

683

695

`` /// - < is transitive: a < b and b < c implies a < c. The same must hold for both == and >.

684

696

`///

697

`` +

/// Mathematically speaking, the < operator defines a strict [weak order]. In

698

`` +

/// cases where == conforms to mathematical equality, it also defines a

699

/// strict [total order].

700

///

701

/// [weak order]: https://en.wikipedia.org/wiki/Weak_ordering

702

/// [total order]: https://en.wikipedia.org/wiki/Total_order

703

///

685

704

`/// ## Derivable

686

705

`///

687

706

`` /// This trait can be used with #[derive].

`@@ -920,6 +939,20 @@ pub macro Ord($item:item) {

920

939

`` /// - transitivity of >: if a > b and b > c then a > c

921

940

`` /// - duality of partial_cmp: partial_cmp(a, b) == partial_cmp(b, a).map(Ordering::reverse)

922

941

`///

942

/// ## Strict and non-strict partial orders

943

///

944

`` +

/// The < and > operators behave according to a strict partial order.

945

`` +

/// However, <= and >= do not behave according to a non-strict

946

/// partial order.

947

/// That is because mathematically, a non-strict partial order would require

948

`` +

/// reflexivity, i.e. a <= a would need to be true for every a. This isn't

949

`` +

/// always the case for types that implement PartialOrd, for example:

950

///

951


/// ```

952

/// let a = f64::sqrt(-1.0);

953

/// assert_eq!(a <= a, false);

954


/// ```

955

///

923

956

`/// ## Derivable

924

957

`///

925

958

`` /// This trait can be used with #[derive].