mirror of
https://github.com/rust-lang/rust.git
synced 2024-11-22 14:55:26 +00:00
3bcad65fbf
docs: Correct terminology in std::cmp This PR is the result of some discussions on URLO: * [Traits in `std::cmp` and mathematical terminology](https://users.rust-lang.org/t/traits-in-std-cmp-and-mathematical-terminology/69887) * [Are poker hands `Ord` or `PartialOrd`?](https://users.rust-lang.org/t/are-poker-hands-ord-or-partialord/82644) Arguably, the documentation currently isn't very precise regarding mathematical terminology. This can lead to misunderstandings of what `PartialEq`, `Eq`, `PartialOrd`, and `Ord` actually do. While I believe this PR doesn't give any new API guarantees, it expliclitly mentions that `PartialEq::eq(a, b)` may return `true` for two distinct values `a` and `b` (i.e. where `a` and `b` are not equal in the mathematical sense). This leads to the consequence that `Ord` may describe a weak ordering instead of a total ordering. In either case, I believe this PR should be thoroughly reviewed, ideally by someone with mathematical background to make sure the terminology is correct now, and also to ensure that no unwanted new API guarantees are made. In particular, the following problems are addressed: * Some clarifications regarding used (mathematical) terminology: * Avoid using the terms "total equality" and "partial equality" in favor of "equivalence relation" and "partial equivalence relation", which are well-defined and unambiguous. * Clarify that `Ordering` is an ordering between two values (and not an order in the mathematical sense). * Avoid saying that `PartialEq` and `Eq` are "equality comparisons" because the terminology "equality comparison" could be misleading: it's possible to implement `PartialEq` and `Eq` for other (partial) equivalence relations, in particular for relations where `a == b` for some `a` and `b` even when `a` and `b` are not the same value. * Added a section "Strict and non-strict partial orders" to document that the `<=` and `>=` operators do not correspond to non-strict partial orders. * Corrected section "Corollaries" in documenation of `Ord` in regard to `<` only describing a strict total order in cases where `==` conforms to mathematical equality. * ~~Added a section "Weak orders" to explain that `Ord` may also describe a weak order or total preorder, depending on how `PartialEq::eq` has been implemented.~~ (Removed, see [comment](https://github.com/rust-lang/rust/pull/103046#issuecomment-1279929676)) * Made documentation easier to understand: * Explicitly state at the beginning of `PartialEq`'s documentation comment that implementing the trait will provide the `==` and `!=` operators. * Added an easier to understand rule when to implement `Eq` in addition to `PartialEq`: "if it’s guaranteed that `PartialEq::eq(a, a)` always returns `true`." * Explicitly mention in documentation of `Eq` that the properties "symmetric" and "transitive" are already required by `PartialEq`. |
||
|---|---|---|
| .. | ||
| alloc | ||
| backtrace@99faef833f | ||
| core | ||
| panic_abort | ||
| panic_unwind | ||
| portable-simd | ||
| proc_macro | ||
| profiler_builtins | ||
| rtstartup | ||
| rustc-std-workspace-alloc | ||
| rustc-std-workspace-core | ||
| rustc-std-workspace-std | ||
| std | ||
| stdarch@333e9e9977 | ||
| sysroot | ||
| test | ||
| unwind | ||