Skip to content

Commit 9d7dea6

Browse files
RalfJungRalfJung
committed
float::maximum/minimum: make docs more streamlined
1 parent 91ab308 commit 9d7dea6

File tree

4 files changed

+80
-72
lines changed

4 files changed

+80
-72
lines changed

‎library/core/src/num/f128.rs‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -750,8 +750,16 @@ impl f128 {
750750

751751
/// Returns the maximum of the two numbers, propagating NaN.
752752
///
753-
/// This returns NaN when *either* argument is NaN, as opposed to
754-
/// [`f128::max`] which only returns NaN when *both* arguments are NaN.
753+
/// If at least one of the arguments is NaN, the return value is NaN, with the bit pattern
754+
/// picked using the usual [rules for arithmetic operations](f32#nan-bit-patterns). Furthermore,
755+
/// `-0.0` is considered to be less than `+0.0`, making this function fully deterministic for
756+
/// non-NaN inputs.
757+
///
758+
/// This is in contrast to [`f128::max`] which only returns NaN when *both* arguments are NaN,
759+
/// and which does not reliably order `-0.0` and `0.0`.
760+
///
761+
/// This follows the IEEE 754-2019 semantics for `maximum`, and also matches the behavior
762+
/// of libm’s `fmaximum`.
755763
///
756764
/// ```
757765
/// #![feature(f128)]
@@ -766,13 +774,6 @@ impl f128 {
766774
/// assert!(x.maximum(f128::NAN).is_nan());
767775
/// # }
768776
/// ```
769-
///
770-
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the greater
771-
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
772-
/// Note that this follows the IEEE 754-2019 semantics for `maximum`.
773-
///
774-
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
775-
/// operand is conserved; see the [specification of NaN bit patterns](f32#nan-bit-patterns) for more info.
776777
#[inline]
777778
#[unstable(feature = "f128", issue = "116909")]
778779
// #[unstable(feature = "float_minimum_maximum", issue = "91079")]
@@ -783,8 +784,16 @@ impl f128 {
783784

784785
/// Returns the minimum of the two numbers, propagating NaN.
785786
///
786-
/// This returns NaN when *either* argument is NaN, as opposed to
787-
/// [`f128::min`] which only returns NaN when *both* arguments are NaN.
787+
/// If at least one of the arguments is NaN, the return value is NaN, with the bit pattern
788+
/// picked using the usual [rules for arithmetic operations](f32#nan-bit-patterns). Furthermore,
789+
/// `-0.0` is considered to be less than `+0.0`, making this function fully deterministic for
790+
/// non-NaN inputs.
791+
///
792+
/// This is in contrast to [`f128::min`] which only returns NaN when *both* arguments are NaN,
793+
/// and which does not reliably order `-0.0` and `0.0`.
794+
///
795+
/// This follows the IEEE 754-2019 semantics for `minimum`, and also matches the behavior
796+
/// of libm’s `fminimum`.
788797
///
789798
/// ```
790799
/// #![feature(f128)]
@@ -799,13 +808,6 @@ impl f128 {
799808
/// assert!(x.minimum(f128::NAN).is_nan());
800809
/// # }
801810
/// ```
802-
///
803-
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the lesser
804-
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
805-
/// Note that this follows the IEEE 754-2019 semantics for `minimum`.
806-
///
807-
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
808-
/// operand is conserved; see the [specification of NaN bit patterns](f32#nan-bit-patterns) for more info.
809811
#[inline]
810812
#[unstable(feature = "f128", issue = "116909")]
811813
// #[unstable(feature = "float_minimum_maximum", issue = "91079")]

‎library/core/src/num/f16.rs‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -741,8 +741,16 @@ impl f16 {
741741

742742
/// Returns the maximum of the two numbers, propagating NaN.
743743
///
744-
/// This returns NaN when *either* argument is NaN, as opposed to
745-
/// [`f16::max`] which only returns NaN when *both* arguments are NaN.
744+
/// If at least one of the arguments is NaN, the return value is NaN, with the bit pattern
745+
/// picked using the usual [rules for arithmetic operations](f32#nan-bit-patterns). Furthermore,
746+
/// `-0.0` is considered to be less than `+0.0`, making this function fully deterministic for
747+
/// non-NaN inputs.
748+
///
749+
/// This is in contrast to [`f16::max`] which only returns NaN when *both* arguments are NaN,
750+
/// and which does not reliably order `-0.0` and `0.0`.
751+
///
752+
/// This follows the IEEE 754-2019 semantics for `maximum`, and also matches the behavior
753+
/// of libm’s `fmaximum`.
746754
///
747755
/// ```
748756
/// #![feature(f16)]
@@ -756,13 +764,6 @@ impl f16 {
756764
/// assert!(x.maximum(f16::NAN).is_nan());
757765
/// # }
758766
/// ```
759-
///
760-
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the greater
761-
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
762-
/// Note that this follows the IEEE 754-2019 semantics for `maximum`.
763-
///
764-
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
765-
/// operand is conserved; see the [specification of NaN bit patterns](f32#nan-bit-patterns) for more info.
766767
#[inline]
767768
#[unstable(feature = "f16", issue = "116909")]
768769
// #[unstable(feature = "float_minimum_maximum", issue = "91079")]
@@ -773,8 +774,16 @@ impl f16 {
773774

774775
/// Returns the minimum of the two numbers, propagating NaN.
775776
///
776-
/// This returns NaN when *either* argument is NaN, as opposed to
777-
/// [`f16::min`] which only returns NaN when *both* arguments are NaN.
777+
/// If at least one of the arguments is NaN, the return value is NaN, with the bit pattern
778+
/// picked using the usual [rules for arithmetic operations](f32#nan-bit-patterns). Furthermore,
779+
/// `-0.0` is considered to be less than `+0.0`, making this function fully deterministic for
780+
/// non-NaN inputs.
781+
///
782+
/// This is in contrast to [`f16::min`] which only returns NaN when *both* arguments are NaN,
783+
/// and which does not reliably order `-0.0` and `0.0`.
784+
///
785+
/// This follows the IEEE 754-2019 semantics for `minimum`, and also matches the behavior
786+
/// of libm’s `fminimum`.
778787
///
779788
/// ```
780789
/// #![feature(f16)]
@@ -788,13 +797,6 @@ impl f16 {
788797
/// assert!(x.minimum(f16::NAN).is_nan());
789798
/// # }
790799
/// ```
791-
///
792-
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the lesser
793-
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
794-
/// Note that this follows the IEEE 754-2019 semantics for `minimum`.
795-
///
796-
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
797-
/// operand is conserved; see the [specification of NaN bit patterns](f32#nan-bit-patterns) for more info.
798800
#[inline]
799801
#[unstable(feature = "f16", issue = "116909")]
800802
// #[unstable(feature = "float_minimum_maximum", issue = "91079")]

‎library/core/src/num/f32.rs‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -943,8 +943,16 @@ impl f32 {
943943

944944
/// Returns the maximum of the two numbers, propagating NaN.
945945
///
946-
/// This returns NaN when *either* argument is NaN, as opposed to
947-
/// [`f32::max`] which only returns NaN when *both* arguments are NaN.
946+
/// If at least one of the arguments is NaN, the return value is NaN, with the bit pattern
947+
/// picked using the usual [rules for arithmetic operations](f32#nan-bit-patterns). Furthermore,
948+
/// `-0.0` is considered to be less than `+0.0`, making this function fully deterministic for
949+
/// non-NaN inputs.
950+
///
951+
/// This is in contrast to [`f32::max`] which only returns NaN when *both* arguments are NaN,
952+
/// and which does not reliably order `-0.0` and `0.0`.
953+
///
954+
/// This follows the IEEE 754-2019 semantics for `maximum`, and also matches the behavior
955+
/// of libm’s `fmaximum`.
948956
///
949957
/// ```
950958
/// #![feature(float_minimum_maximum)]
@@ -954,13 +962,6 @@ impl f32 {
954962
/// assert_eq!(x.maximum(y), y);
955963
/// assert!(x.maximum(f32::NAN).is_nan());
956964
/// ```
957-
///
958-
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the greater
959-
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
960-
/// Note that this follows the IEEE 754-2019 semantics for `maximum`.
961-
///
962-
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
963-
/// operand is conserved; see the [specification of NaN bit patterns](f32#nan-bit-patterns) for more info.
964965
#[must_use = "this returns the result of the comparison, without modifying either input"]
965966
#[unstable(feature = "float_minimum_maximum", issue = "91079")]
966967
#[inline]
@@ -970,8 +971,16 @@ impl f32 {
970971

971972
/// Returns the minimum of the two numbers, propagating NaN.
972973
///
973-
/// This returns NaN when *either* argument is NaN, as opposed to
974-
/// [`f32::min`] which only returns NaN when *both* arguments are NaN.
974+
/// If at least one of the arguments is NaN, the return value is NaN, with the bit pattern
975+
/// picked using the usual [rules for arithmetic operations](f32#nan-bit-patterns). Furthermore,
976+
/// `-0.0` is considered to be less than `+0.0`, making this function fully deterministic for
977+
/// non-NaN inputs.
978+
///
979+
/// This is in contrast to [`f32::min`] which only returns NaN when *both* arguments are NaN,
980+
/// and which does not reliably order `-0.0` and `0.0`.
981+
///
982+
/// This follows the IEEE 754-2019 semantics for `minimum`, and also matches the behavior
983+
/// of libm’s `fminimum`.
975984
///
976985
/// ```
977986
/// #![feature(float_minimum_maximum)]
@@ -981,13 +990,6 @@ impl f32 {
981990
/// assert_eq!(x.minimum(y), x);
982991
/// assert!(x.minimum(f32::NAN).is_nan());
983992
/// ```
984-
///
985-
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the lesser
986-
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
987-
/// Note that this follows the IEEE 754-2019 semantics for `minimum`.
988-
///
989-
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
990-
/// operand is conserved; see the [specification of NaN bit patterns](f32#nan-bit-patterns) for more info.
991993
#[must_use = "this returns the result of the comparison, without modifying either input"]
992994
#[unstable(feature = "float_minimum_maximum", issue = "91079")]
993995
#[inline]

‎library/core/src/num/f64.rs‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -961,8 +961,16 @@ impl f64 {
961961

962962
/// Returns the maximum of the two numbers, propagating NaN.
963963
///
964-
/// This returns NaN when *either* argument is NaN, as opposed to
965-
/// [`f64::max`] which only returns NaN when *both* arguments are NaN.
964+
/// If at least one of the arguments is NaN, the return value is NaN, with the bit pattern
965+
/// picked using the usual [rules for arithmetic operations](f32#nan-bit-patterns). Furthermore,
966+
/// `-0.0` is considered to be less than `+0.0`, making this function fully deterministic for
967+
/// non-NaN inputs.
968+
///
969+
/// This is in contrast to [`f64::max`] which only returns NaN when *both* arguments are NaN,
970+
/// and which does not reliably order `-0.0` and `0.0`.
971+
///
972+
/// This follows the IEEE 754-2019 semantics for `maximum`, and also matches the behavior
973+
/// of libm’s `fmaximum`.
966974
///
967975
/// ```
968976
/// #![feature(float_minimum_maximum)]
@@ -972,13 +980,6 @@ impl f64 {
972980
/// assert_eq!(x.maximum(y), y);
973981
/// assert!(x.maximum(f64::NAN).is_nan());
974982
/// ```
975-
///
976-
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the greater
977-
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
978-
/// Note that this follows the IEEE 754-2019 semantics for `maximum`.
979-
///
980-
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
981-
/// operand is conserved; see the [specification of NaN bit patterns](f32#nan-bit-patterns) for more info.
982983
#[must_use = "this returns the result of the comparison, without modifying either input"]
983984
#[unstable(feature = "float_minimum_maximum", issue = "91079")]
984985
#[inline]
@@ -988,8 +989,16 @@ impl f64 {
988989

989990
/// Returns the minimum of the two numbers, propagating NaN.
990991
///
991-
/// This returns NaN when *either* argument is NaN, as opposed to
992-
/// [`f64::min`] which only returns NaN when *both* arguments are NaN.
992+
/// If at least one of the arguments is NaN, the return value is NaN, with the bit pattern
993+
/// picked using the usual [rules for arithmetic operations](f32#nan-bit-patterns). Furthermore,
994+
/// `-0.0` is considered to be less than `+0.0`, making this function fully deterministic for
995+
/// non-NaN inputs.
996+
///
997+
/// This is in contrast to [`f64::min`] which only returns NaN when *both* arguments are NaN,
998+
/// and which does not reliably order `-0.0` and `0.0`.
999+
///
1000+
/// This follows the IEEE 754-2019 semantics for `minimum`, and also matches the behavior
1001+
/// of libm’s `fminimum`.
9931002
///
9941003
/// ```
9951004
/// #![feature(float_minimum_maximum)]
@@ -999,13 +1008,6 @@ impl f64 {
9991008
/// assert_eq!(x.minimum(y), x);
10001009
/// assert!(x.minimum(f64::NAN).is_nan());
10011010
/// ```
1002-
///
1003-
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the lesser
1004-
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
1005-
/// Note that this follows the IEEE 754-2019 semantics for `minimum`.
1006-
///
1007-
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
1008-
/// operand is conserved; see the [specification of NaN bit patterns](f32#nan-bit-patterns) for more info.
10091011
#[must_use = "this returns the result of the comparison, without modifying either input"]
10101012
#[unstable(feature = "float_minimum_maximum", issue = "91079")]
10111013
#[inline]

0 commit comments

Comments
 (0)