Rollup merge of #149475 - RalfJung:min-max-nan, r=tgross35

float::min/max: reference NaN bit pattern rules Also, the "in particular" transition to the signed zero handling was odd, so I rearranged things a bit: first a self-contained description of the semantics, then an explanation of which operations in other standards/libraries this most closely corresponds to. r? `@tgross35`

Author: matthiaskrgr

library/core/src/num/f128.rs

@@ -694,11 +694,14 @@ impl f128 {
 
  /// Returns the maximum of the two numbers, ignoring NaN.
  ///
- /// If one of the arguments is NaN, then the other argument is returned.
+ /// If exactly one of the arguments is NaN, then the other argument is returned. If both
+ /// arguments are NaN, the return value is NaN, with the bit pattern picked using the usual
+ /// [rules for arithmetic operations](f32#nan-bit-patterns). If the inputs compare equal (such
+ /// as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ ///
  /// This follows the IEEE 754-2008 semantics for `maxNum`, except for handling of signaling NaNs;
  /// this function handles all NaNs the same way and avoids `maxNum`'s problems with associativity.
- /// This also matches the behavior of libm’s fmax. In particular, if the inputs compare equal
- /// (such as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ /// This also matches the behavior of libm’s `fmax`.
  ///
  /// ```
  /// #![feature(f128)]
@@ -722,11 +725,14 @@ impl f128 {
 
  /// Returns the minimum of the two numbers, ignoring NaN.
  ///
- /// If one of the arguments is NaN, then the other argument is returned.
+ /// If exactly one of the arguments is NaN, then the other argument is returned. If both
+ /// arguments are NaN, the return value is NaN, with the bit pattern picked using the usual
+ /// [rules for arithmetic operations](f32#nan-bit-patterns). If the inputs compare equal (such
+ /// as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ ///
  /// This follows the IEEE 754-2008 semantics for `minNum`, except for handling of signaling NaNs;
  /// this function handles all NaNs the same way and avoids `minNum`'s problems with associativity.
- /// This also matches the behavior of libm’s fmin. In particular, if the inputs compare equal
- /// (such as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ /// This also matches the behavior of libm’s `fmin`.
  ///
  /// ```
  /// #![feature(f128)]

library/core/src/num/f16.rs

@@ -687,11 +687,14 @@ impl f16 {
 
  /// Returns the maximum of the two numbers, ignoring NaN.
  ///
- /// If one of the arguments is NaN, then the other argument is returned.
+ /// If exactly one of the arguments is NaN, then the other argument is returned. If both
+ /// arguments are NaN, the return value is NaN, with the bit pattern picked using the usual
+ /// [rules for arithmetic operations](f32#nan-bit-patterns). If the inputs compare equal (such
+ /// as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ ///
  /// This follows the IEEE 754-2008 semantics for `maxNum`, except for handling of signaling NaNs;
  /// this function handles all NaNs the same way and avoids `maxNum`'s problems with associativity.
- /// This also matches the behavior of libm’s fmax. In particular, if the inputs compare equal
- /// (such as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ /// This also matches the behavior of libm’s `fmax`.
  ///
  /// ```
  /// #![feature(f16)]
@@ -714,11 +717,14 @@ impl f16 {
 
  /// Returns the minimum of the two numbers, ignoring NaN.
  ///
- /// If one of the arguments is NaN, then the other argument is returned.
+ /// If exactly one of the arguments is NaN, then the other argument is returned. If both
+ /// arguments are NaN, the return value is NaN, with the bit pattern picked using the usual
+ /// [rules for arithmetic operations](f32#nan-bit-patterns). If the inputs compare equal (such
+ /// as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ ///
  /// This follows the IEEE 754-2008 semantics for `minNum`, except for handling of signaling NaNs;
  /// this function handles all NaNs the same way and avoids `minNum`'s problems with associativity.
- /// This also matches the behavior of libm’s fmin. In particular, if the inputs compare equal
- /// (such as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ /// This also matches the behavior of libm’s `fmin`.
  ///
  /// ```
  /// #![feature(f16)]

library/core/src/num/f32.rs

@@ -897,11 +897,14 @@ impl f32 {
 
  /// Returns the maximum of the two numbers, ignoring NaN.
  ///
- /// If one of the arguments is NaN, then the other argument is returned.
+ /// If exactly one of the arguments is NaN, then the other argument is returned. If both
+ /// arguments are NaN, the return value is NaN, with the bit pattern picked using the usual
+ /// [rules for arithmetic operations](f32#nan-bit-patterns). If the inputs compare equal (such
+ /// as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ ///
  /// This follows the IEEE 754-2008 semantics for `maxNum`, except for handling of signaling NaNs;
  /// this function handles all NaNs the same way and avoids `maxNum`'s problems with associativity.
- /// This also matches the behavior of libm’s fmax. In particular, if the inputs compare equal
- /// (such as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ /// This also matches the behavior of libm’s `fmax`.
  ///
  /// ```
  /// let x = 1.0f32;
@@ -920,11 +923,14 @@ impl f32 {
 
  /// Returns the minimum of the two numbers, ignoring NaN.
  ///
- /// If one of the arguments is NaN, then the other argument is returned.
+ /// If exactly one of the arguments is NaN, then the other argument is returned. If both
+ /// arguments are NaN, the return value is NaN, with the bit pattern picked using the usual
+ /// [rules for arithmetic operations](f32#nan-bit-patterns). If the inputs compare equal (such
+ /// as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ ///
  /// This follows the IEEE 754-2008 semantics for `minNum`, except for handling of signaling NaNs;
  /// this function handles all NaNs the same way and avoids `minNum`'s problems with associativity.
- /// This also matches the behavior of libm’s fmin. In particular, if the inputs compare equal
- /// (such as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ /// This also matches the behavior of libm’s `fmin`.
  ///
  /// ```
  /// let x = 1.0f32;

library/core/src/num/f64.rs

@@ -915,11 +915,14 @@ impl f64 {
 
  /// Returns the maximum of the two numbers, ignoring NaN.
  ///
- /// If one of the arguments is NaN, then the other argument is returned.
+ /// If exactly one of the arguments is NaN, then the other argument is returned. If both
+ /// arguments are NaN, the return value is NaN, with the bit pattern picked using the usual
+ /// [rules for arithmetic operations](f32#nan-bit-patterns). If the inputs compare equal (such
+ /// as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ ///
  /// This follows the IEEE 754-2008 semantics for `maxNum`, except for handling of signaling NaNs;
  /// this function handles all NaNs the same way and avoids `maxNum`'s problems with associativity.
- /// This also matches the behavior of libm’s fmax. In particular, if the inputs compare equal
- /// (such as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ /// This also matches the behavior of libm’s `fmax`.
  ///
  /// ```
  /// let x = 1.0_f64;
@@ -938,11 +941,14 @@ impl f64 {
 
  /// Returns the minimum of the two numbers, ignoring NaN.
  ///
- /// If one of the arguments is NaN, then the other argument is returned.
+ /// If exactly one of the arguments is NaN, then the other argument is returned. If both
+ /// arguments are NaN, the return value is NaN, with the bit pattern picked using the usual
+ /// [rules for arithmetic operations](f32#nan-bit-patterns). If the inputs compare equal (such
+ /// as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ ///
  /// This follows the IEEE 754-2008 semantics for `minNum`, except for handling of signaling NaNs;
  /// this function handles all NaNs the same way and avoids `minNum`'s problems with associativity.
- /// This also matches the behavior of libm’s fmin. In particular, if the inputs compare equal
- /// (such as for the case of `+0.0` and `-0.0`), either input may be returned non-deterministically.
+ /// This also matches the behavior of libm’s `fmin`.
  ///
  /// ```
  /// let x = 1.0_f64;