From 62111145b719c9b2a6d88b0bdcfab0f9b7e19ba8 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Wed, 6 Sep 2023 16:10:22 +0200 Subject: [PATCH] clarify that unsafe code must not rely on our safe traits --- library/core/src/cmp.rs | 20 ++++++++++++++++++++ library/core/src/hash/mod.rs | 5 +++++ library/core/src/ops/deref.rs | 10 ++++++++++ 3 files changed, 35 insertions(+) diff --git a/library/core/src/cmp.rs b/library/core/src/cmp.rs index 3c127efb390..adc5dc92205 100644 --- a/library/core/src/cmp.rs +++ b/library/core/src/cmp.rs @@ -63,6 +63,11 @@ /// (transitive) impls are not forced to exist, but these requirements apply /// whenever they do exist. /// +/// Violating these requirements 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. +/// /// ## Derivable /// /// This trait can be used with `#[derive]`. When `derive`d on structs, two @@ -250,6 +255,11 @@ fn ne(&self, other: &Rhs) -> bool { /// This property cannot be checked by the compiler, and therefore `Eq` implies /// [`PartialEq`], and has no extra methods. /// +/// 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. +/// /// ## Derivable /// /// This trait can be used with `#[derive]`. When `derive`d, because `Eq` has @@ -656,6 +666,11 @@ fn clone_from(&mut self, other: &Self) { /// It's easy to accidentally make `cmp` and `partial_cmp` disagree by /// deriving some of the traits and manually implementing others. /// +/// Violating these requirements 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. +/// /// ## Corollaries /// /// From the above and the requirements of `PartialOrd`, it follows that `<` defines a strict total order. @@ -889,6 +904,11 @@ fn clamp(self, min: Self, max: Self) -> Self /// transitively: if `T: PartialOrd` and `U: PartialOrd` then `U: PartialOrd` and `T: /// PartialOrd`. /// +/// Violating these requirements 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. +/// /// ## Corollaries /// /// The following corollaries follow from the above requirements: diff --git a/library/core/src/hash/mod.rs b/library/core/src/hash/mod.rs index 794a57f0922..35b757dc1ee 100644 --- a/library/core/src/hash/mod.rs +++ b/library/core/src/hash/mod.rs @@ -153,6 +153,11 @@ /// Thankfully, you won't need to worry about upholding this property when /// deriving both [`Eq`] and `Hash` with `#[derive(PartialEq, Eq, Hash)]`. /// +/// 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. +/// /// ## Prefix collisions /// /// Implementations of `hash` should ensure that the data they diff --git a/library/core/src/ops/deref.rs b/library/core/src/ops/deref.rs index 08c35b6dac3..911761c6edd 100644 --- a/library/core/src/ops/deref.rs +++ b/library/core/src/ops/deref.rs @@ -14,6 +14,11 @@ /// For similar reasons, **this trait should never fail**. Failure during /// dereferencing can be extremely confusing when `Deref` is invoked implicitly. /// +/// Violating these requirements 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 this +/// method. +/// /// # More on `Deref` coercion /// /// If `T` implements `Deref`, and `x` is a value of type `T`, then: @@ -114,6 +119,11 @@ fn deref(&self) -> &T { /// dereferencing can be extremely confusing when `DerefMut` is invoked /// implicitly. /// +/// Violating these requirements 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 this +/// method. +/// /// # More on `Deref` coercion /// /// If `T` implements `DerefMut`, and `x` is a value of type `T`,