Skip to content

Commit aa95fef

Browse files
syvbsyvb
committed
Add more documentation of out-of-range logs
1 parent d4e13ac commit aa95fef

File tree

4 files changed

+138
-0
lines changed

4 files changed

+138
-0
lines changed

‎library/std/src/f128.rs

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -491,6 +491,13 @@ impl f128 {
491491
/// assert!(abs_difference <= f128::EPSILON);
492492
/// # }
493493
/// ```
494+
///
495+
/// Non-positive values:
496+
/// ```
497+
/// #![feature(f128)]
498+
/// assert_eq!(0_f128.ln(), f128::NEG_INFINITY);
499+
/// assert!((-42_f128).ln().is_nan());
500+
/// ```
494501
#[inline]
495502
#[rustc_allow_incoherent_impl]
496503
#[unstable(feature = "f128", issue = "116909")]
@@ -526,6 +533,13 @@ impl f128 {
526533
/// assert!(abs_difference <= f128::EPSILON);
527534
/// # }
528535
/// ```
536+
///
537+
/// Non-positive values:
538+
/// ```
539+
/// #![feature(f128)]
540+
/// assert_eq!(0_f128.log(10.0), f128::NEG_INFINITY);
541+
/// assert!((-42_f128).log(10.0).is_nan());
542+
/// ```
529543
#[inline]
530544
#[rustc_allow_incoherent_impl]
531545
#[unstable(feature = "f128", issue = "116909")]
@@ -557,6 +571,13 @@ impl f128 {
557571
/// assert!(abs_difference <= f128::EPSILON);
558572
/// # }
559573
/// ```
574+
///
575+
/// Non-positive values:
576+
/// ```
577+
/// #![feature(f128)]
578+
/// assert_eq!(0_f128.log2(), f128::NEG_INFINITY);
579+
/// assert!((-42_f128).log2().is_nan());
580+
/// ```
560581
#[inline]
561582
#[rustc_allow_incoherent_impl]
562583
#[unstable(feature = "f128", issue = "116909")]
@@ -588,6 +609,13 @@ impl f128 {
588609
/// assert!(abs_difference <= f128::EPSILON);
589610
/// # }
590611
/// ```
612+
///
613+
/// Non-positive values:
614+
/// ```
615+
/// #![feature(f128)]
616+
/// assert_eq!(0_f128.log10(), f128::NEG_INFINITY);
617+
/// assert!((-42_f128).log10().is_nan());
618+
/// ```
591619
#[inline]
592620
#[rustc_allow_incoherent_impl]
593621
#[unstable(feature = "f128", issue = "116909")]
@@ -974,6 +1002,8 @@ impl f128 {
9741002
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
9751003
/// the operations were performed separately.
9761004
///
1005+
/// This returns NaN when `n < -1.0`, and negative infinity when `n == -1.0`.
1006+
///
9771007
/// # Unspecified precision
9781008
///
9791009
/// The precision of this function is non-deterministic. This means it varies by platform,
@@ -997,6 +1027,13 @@ impl f128 {
9971027
/// assert!(abs_difference < 1e-10);
9981028
/// # }
9991029
/// ```
1030+
///
1031+
/// Out-of-range values:
1032+
/// ```
1033+
/// #![feature(f128)]
1034+
/// assert_eq!((-1.0_f128).ln_1p(), f128::NEG_INFINITY);
1035+
/// assert!((-2.0_f128).ln_1p().is_nan());
1036+
/// ```
10001037
#[inline]
10011038
#[doc(alias = "log1p")]
10021039
#[must_use = "method returns a new number and does not mutate the original value"]

‎library/std/src/f16.rs

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -491,6 +491,13 @@ impl f16 {
491491
/// assert!(abs_difference <= f16::EPSILON);
492492
/// # }
493493
/// ```
494+
///
495+
/// Non-positive values:
496+
/// ```
497+
/// #![feature(f16)]
498+
/// assert_eq!(0_f16.ln(), f16::NEG_INFINITY);
499+
/// assert!((-42_f16).ln().is_nan());
500+
/// ```
494501
#[inline]
495502
#[rustc_allow_incoherent_impl]
496503
#[unstable(feature = "f16", issue = "116909")]
@@ -526,6 +533,13 @@ impl f16 {
526533
/// assert!(abs_difference <= f16::EPSILON);
527534
/// # }
528535
/// ```
536+
///
537+
/// Non-positive values:
538+
/// ```
539+
/// #![feature(f16)]
540+
/// assert_eq!(0_f16.log(10.0), f16::NEG_INFINITY);
541+
/// assert!((-42_f16).log(10.0).is_nan());
542+
/// ```
529543
#[inline]
530544
#[rustc_allow_incoherent_impl]
531545
#[unstable(feature = "f16", issue = "116909")]
@@ -557,6 +571,13 @@ impl f16 {
557571
/// assert!(abs_difference <= f16::EPSILON);
558572
/// # }
559573
/// ```
574+
///
575+
/// Non-positive values:
576+
/// ```
577+
/// #![feature(f16)]
578+
/// assert_eq!(0_f16.log2(), f16::NEG_INFINITY);
579+
/// assert!((-42_f16).log2().is_nan());
580+
/// ```
560581
#[inline]
561582
#[rustc_allow_incoherent_impl]
562583
#[unstable(feature = "f16", issue = "116909")]
@@ -588,6 +609,13 @@ impl f16 {
588609
/// assert!(abs_difference <= f16::EPSILON);
589610
/// # }
590611
/// ```
612+
///
613+
/// Non-positive values:
614+
/// ```
615+
/// #![feature(f16)]
616+
/// assert_eq!(0_f16.log10(), f16::NEG_INFINITY);
617+
/// assert!((-42_f16).log10().is_nan());
618+
/// ```
591619
#[inline]
592620
#[rustc_allow_incoherent_impl]
593621
#[unstable(feature = "f16", issue = "116909")]
@@ -972,6 +1000,8 @@ impl f16 {
9721000
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
9731001
/// the operations were performed separately.
9741002
///
1003+
/// This returns NaN when `n < -1.0`, and negative infinity when `n == -1.0`.
1004+
///
9751005
/// # Unspecified precision
9761006
///
9771007
/// The precision of this function is non-deterministic. This means it varies by platform,
@@ -995,6 +1025,13 @@ impl f16 {
9951025
/// assert!(abs_difference < 1e-4);
9961026
/// # }
9971027
/// ```
1028+
///
1029+
/// Out-of-range values:
1030+
/// ```
1031+
/// #![feature(f16)]
1032+
/// assert_eq!((-1.0_f16).ln_1p(), f16::NEG_INFINITY);
1033+
/// assert!((-2.0_f16).ln_1p().is_nan());
1034+
/// ```
9981035
#[inline]
9991036
#[doc(alias = "log1p")]
10001037
#[rustc_allow_incoherent_impl]

‎library/std/src/f32.rs

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -443,6 +443,12 @@ impl f32 {
443443
///
444444
/// assert!(abs_difference <= f32::EPSILON);
445445
/// ```
446+
///
447+
/// Non-positive values:
448+
/// ```
449+
/// assert_eq!(0_f32.ln(), f32::NEG_INFINITY);
450+
/// assert!((-42_f32).ln().is_nan());
451+
/// ```
446452
#[rustc_allow_incoherent_impl]
447453
#[must_use = "method returns a new number and does not mutate the original value"]
448454
#[stable(feature = "rust1", since = "1.0.0")]
@@ -474,6 +480,12 @@ impl f32 {
474480
///
475481
/// assert!(abs_difference <= f32::EPSILON);
476482
/// ```
483+
///
484+
/// Non-positive values:
485+
/// ```
486+
/// assert_eq!(0_f32.log(10.0), f32::NEG_INFINITY);
487+
/// assert!((-42_f32).log(10.0).is_nan());
488+
/// ```
477489
#[rustc_allow_incoherent_impl]
478490
#[must_use = "method returns a new number and does not mutate the original value"]
479491
#[stable(feature = "rust1", since = "1.0.0")]
@@ -501,6 +513,12 @@ impl f32 {
501513
///
502514
/// assert!(abs_difference <= f32::EPSILON);
503515
/// ```
516+
///
517+
/// Non-positive values:
518+
/// ```
519+
/// assert_eq!(0_f32.log2(), f32::NEG_INFINITY);
520+
/// assert!((-42_f32).log2().is_nan());
521+
/// ```
504522
#[rustc_allow_incoherent_impl]
505523
#[must_use = "method returns a new number and does not mutate the original value"]
506524
#[stable(feature = "rust1", since = "1.0.0")]
@@ -528,6 +546,12 @@ impl f32 {
528546
///
529547
/// assert!(abs_difference <= f32::EPSILON);
530548
/// ```
549+
///
550+
/// Non-positive values:
551+
/// ```
552+
/// assert_eq!(0_f32.log10(), f32::NEG_INFINITY);
553+
/// assert!((-42_f32).log10().is_nan());
554+
/// ```
531555
#[rustc_allow_incoherent_impl]
532556
#[must_use = "method returns a new number and does not mutate the original value"]
533557
#[stable(feature = "rust1", since = "1.0.0")]
@@ -901,6 +925,8 @@ impl f32 {
901925
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
902926
/// the operations were performed separately.
903927
///
928+
/// This returns NaN when `n < -1.0`, and negative infinity when `n == -1.0`.
929+
///
904930
/// # Unspecified precision
905931
///
906932
/// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
@@ -919,6 +945,12 @@ impl f32 {
919945
///
920946
/// assert!(abs_difference < 1e-10);
921947
/// ```
948+
///
949+
/// Out-of-range values:
950+
/// ```
951+
/// assert_eq!((-1.0_f32).ln_1p(), f32::NEG_INFINITY);
952+
/// assert!((-2.0_f32).ln_1p().is_nan());
953+
/// ```
922954
#[doc(alias = "log1p")]
923955
#[rustc_allow_incoherent_impl]
924956
#[must_use = "method returns a new number and does not mutate the original value"]

‎library/std/src/f64.rs

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -443,6 +443,12 @@ impl f64 {
443443
///
444444
/// assert!(abs_difference < 1e-10);
445445
/// ```
446+
///
447+
/// Non-positive values:
448+
/// ```
449+
/// assert_eq!(0_f64.ln(), f64::NEG_INFINITY);
450+
/// assert!((-42_f64).ln().is_nan());
451+
/// ```
446452
#[rustc_allow_incoherent_impl]
447453
#[must_use = "method returns a new number and does not mutate the original value"]
448454
#[stable(feature = "rust1", since = "1.0.0")]
@@ -474,6 +480,12 @@ impl f64 {
474480
///
475481
/// assert!(abs_difference < 1e-10);
476482
/// ```
483+
///
484+
/// Non-positive values:
485+
/// ```
486+
/// assert_eq!(0_f64.log(10.0), f64::NEG_INFINITY);
487+
/// assert!((-42_f64).log(10.0).is_nan());
488+
/// ```
477489
#[rustc_allow_incoherent_impl]
478490
#[must_use = "method returns a new number and does not mutate the original value"]
479491
#[stable(feature = "rust1", since = "1.0.0")]
@@ -501,6 +513,12 @@ impl f64 {
501513
///
502514
/// assert!(abs_difference < 1e-10);
503515
/// ```
516+
///
517+
/// Non-positive values:
518+
/// ```
519+
/// assert_eq!(0_f64.log2(), f64::NEG_INFINITY);
520+
/// assert!((-42_f64).log2().is_nan());
521+
/// ```
504522
#[rustc_allow_incoherent_impl]
505523
#[must_use = "method returns a new number and does not mutate the original value"]
506524
#[stable(feature = "rust1", since = "1.0.0")]
@@ -528,6 +546,12 @@ impl f64 {
528546
///
529547
/// assert!(abs_difference < 1e-10);
530548
/// ```
549+
///
550+
/// Non-positive values:
551+
/// ```
552+
/// assert_eq!(0_f64.log10(), f64::NEG_INFINITY);
553+
/// assert!((-42_f64).log10().is_nan());
554+
/// ```
531555
#[rustc_allow_incoherent_impl]
532556
#[must_use = "method returns a new number and does not mutate the original value"]
533557
#[stable(feature = "rust1", since = "1.0.0")]
@@ -901,6 +925,8 @@ impl f64 {
901925
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
902926
/// the operations were performed separately.
903927
///
928+
/// This returns NaN when `n < -1.0`, and negative infinity when `n == -1.0`.
929+
///
904930
/// # Unspecified precision
905931
///
906932
/// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
@@ -919,6 +945,12 @@ impl f64 {
919945
///
920946
/// assert!(abs_difference < 1e-20);
921947
/// ```
948+
///
949+
/// Out-of-range values:
950+
/// ```
951+
/// assert_eq!((-1.0_f64).ln_1p(), f64::NEG_INFINITY);
952+
/// assert!((-2.0_f64).ln_1p().is_nan());
953+
/// ```
922954
#[doc(alias = "log1p")]
923955
#[rustc_allow_incoherent_impl]
924956
#[must_use = "method returns a new number and does not mutate the original value"]

0 commit comments

Comments
 (0)