diff --git a/src/lib.rs b/src/lib.rs index 38790b5..f383c8d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -70,12 +70,26 @@ fn canonicalize_signed_zero(x: T) -> T { /// # use ordered_float::OrderedFloat; /// # use std::collections::HashSet; /// # use std::f32::NAN; -/// /// let mut s: HashSet> = HashSet::new(); /// s.insert(OrderedFloat(NAN)); /// assert!(s.contains(&OrderedFloat(NAN))); /// ``` /// +/// Some non-identical values are still considered equal by the [`PartialEq`] implementation, +/// and will therefore also be considered equal by maps, sets, and the `==` operator: +/// +/// * `-0.0` and `+0.0` are considered equal. +/// This different sign may show up in printing, or when dividing by zero (the sign of the zero +/// becomes the sign of the resulting infinity). +/// * All NaN values are considered equal, even though they may have different +/// [bits](https://doc.rust-lang.org/std/primitive.f64.html#method.to_bits), and therefore +/// different [sign](https://doc.rust-lang.org/std/primitive.f64.html#method.is_sign_positive), +/// signaling/quiet status, and NaN payload bits. +/// +/// Therefore, `OrderedFloat` may be unsuitable for use as a key in interning and memoization +/// applications which require equal results from equal inputs, unless these cases make no +/// difference or are canonicalized before insertion. +/// /// # Representation /// /// `OrderedFloat` has `#[repr(transparent)]` and permits any value, so it is sound to use @@ -1152,13 +1166,18 @@ impl Num for OrderedFloat { /// ``` /// # use ordered_float::NotNan; /// # use std::collections::HashSet; -/// /// let mut s: HashSet> = HashSet::new(); /// let key = NotNan::new(1.0).unwrap(); /// s.insert(key); /// assert!(s.contains(&key)); /// ``` /// +/// `-0.0` and `+0.0` are still considered equal. This different sign may show up in printing, +/// or when dividing by zero (the sign of the zero becomes the sign of the resulting infinity). +/// Therefore, `NotNan` may be unsuitable for use as a key in interning and memoization +/// applications which require equal results from equal inputs, unless signed zeros make no +/// difference or are canonicalized before insertion. +/// /// Arithmetic on NotNan values will panic if it produces a NaN value: /// /// ```should_panic