Skip to content

Commit 0199d04

Browse files
syvbsyvb
committed
Document results of non-positive logarithms
1 parent f04bbc6 commit 0199d04

File tree

4 files changed

+200
-0
lines changed

4 files changed

+200
-0
lines changed

‎library/std/src/f128.rs‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -468,6 +468,8 @@ impl f128 {
468468

469469
/// Returns the natural logarithm of the number.
470470
///
471+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
472+
///
471473
/// # Unspecified precision
472474
///
473475
/// The precision of this function is non-deterministic. This means it varies by platform,
@@ -489,6 +491,16 @@ impl f128 {
489491
/// assert!(abs_difference <= f128::EPSILON);
490492
/// # }
491493
/// ```
494+
///
495+
/// Non-positive values:
496+
/// ```
497+
/// #![feature(f128)]
498+
/// # #[cfg(reliable_f128_math)] {
499+
///
500+
/// assert_eq!(0_f128.ln(), f128::NEG_INFINITY);
501+
/// assert!((-42_f128).ln().is_nan());
502+
/// # }
503+
/// ```
492504
#[inline]
493505
#[rustc_allow_incoherent_impl]
494506
#[unstable(feature = "f128", issue = "116909")]
@@ -499,6 +511,8 @@ impl f128 {
499511

500512
/// Returns the logarithm of the number with respect to an arbitrary base.
501513
///
514+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
515+
///
502516
/// The result might not be correctly rounded owing to implementation details;
503517
/// `self.log2()` can produce more accurate results for base 2, and
504518
/// `self.log10()` can produce more accurate results for base 10.
@@ -522,6 +536,16 @@ impl f128 {
522536
/// assert!(abs_difference <= f128::EPSILON);
523537
/// # }
524538
/// ```
539+
///
540+
/// Non-positive values:
541+
/// ```
542+
/// #![feature(f128)]
543+
/// # #[cfg(reliable_f128_math)] {
544+
///
545+
/// assert_eq!(0_f128.log(10.0), f128::NEG_INFINITY);
546+
/// assert!((-42_f128).log(10.0).is_nan());
547+
/// # }
548+
/// ```
525549
#[inline]
526550
#[rustc_allow_incoherent_impl]
527551
#[unstable(feature = "f128", issue = "116909")]
@@ -532,6 +556,8 @@ impl f128 {
532556

533557
/// Returns the base 2 logarithm of the number.
534558
///
559+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
560+
///
535561
/// # Unspecified precision
536562
///
537563
/// The precision of this function is non-deterministic. This means it varies by platform,
@@ -551,6 +577,16 @@ impl f128 {
551577
/// assert!(abs_difference <= f128::EPSILON);
552578
/// # }
553579
/// ```
580+
///
581+
/// Non-positive values:
582+
/// ```
583+
/// #![feature(f128)]
584+
/// # #[cfg(reliable_f128_math)] {
585+
///
586+
/// assert_eq!(0_f128.log2(), f128::NEG_INFINITY);
587+
/// assert!((-42_f128).log2().is_nan());
588+
/// # }
589+
/// ```
554590
#[inline]
555591
#[rustc_allow_incoherent_impl]
556592
#[unstable(feature = "f128", issue = "116909")]
@@ -561,6 +597,8 @@ impl f128 {
561597

562598
/// Returns the base 10 logarithm of the number.
563599
///
600+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
601+
///
564602
/// # Unspecified precision
565603
///
566604
/// The precision of this function is non-deterministic. This means it varies by platform,
@@ -580,6 +618,16 @@ impl f128 {
580618
/// assert!(abs_difference <= f128::EPSILON);
581619
/// # }
582620
/// ```
621+
///
622+
/// Non-positive values:
623+
/// ```
624+
/// #![feature(f128)]
625+
/// # #[cfg(reliable_f128_math)] {
626+
///
627+
/// assert_eq!(0_f128.log10(), f128::NEG_INFINITY);
628+
/// assert!((-42_f128).log10().is_nan());
629+
/// # }
630+
/// ```
583631
#[inline]
584632
#[rustc_allow_incoherent_impl]
585633
#[unstable(feature = "f128", issue = "116909")]
@@ -966,6 +1014,8 @@ impl f128 {
9661014
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
9671015
/// the operations were performed separately.
9681016
///
1017+
/// This returns NaN when `n < -1.0`, and negative infinity when `n == -1.0`.
1018+
///
9691019
/// # Unspecified precision
9701020
///
9711021
/// The precision of this function is non-deterministic. This means it varies by platform,
@@ -989,6 +1039,16 @@ impl f128 {
9891039
/// assert!(abs_difference < 1e-10);
9901040
/// # }
9911041
/// ```
1042+
///
1043+
/// Out-of-range values:
1044+
/// ```
1045+
/// #![feature(f128)]
1046+
/// # #[cfg(reliable_f128_math)] {
1047+
///
1048+
/// assert_eq!((-1.0_f128).ln_1p(), f128::NEG_INFINITY);
1049+
/// assert!((-2.0_f128).ln_1p().is_nan());
1050+
/// # }
1051+
/// ```
9921052
#[inline]
9931053
#[doc(alias = "log1p")]
9941054
#[must_use = "method returns a new number and does not mutate the original value"]

‎library/std/src/f16.rs‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -468,6 +468,8 @@ impl f16 {
468468

469469
/// Returns the natural logarithm of the number.
470470
///
471+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
472+
///
471473
/// # Unspecified precision
472474
///
473475
/// The precision of this function is non-deterministic. This means it varies by platform,
@@ -489,6 +491,16 @@ impl f16 {
489491
/// assert!(abs_difference <= f16::EPSILON);
490492
/// # }
491493
/// ```
494+
///
495+
/// Non-positive values:
496+
/// ```
497+
/// #![feature(f16)]
498+
/// # #[cfg(reliable_f16_math)] {
499+
///
500+
/// assert_eq!(0_f16.ln(), f16::NEG_INFINITY);
501+
/// assert!((-42_f16).ln().is_nan());
502+
/// # }
503+
/// ```
492504
#[inline]
493505
#[rustc_allow_incoherent_impl]
494506
#[unstable(feature = "f16", issue = "116909")]
@@ -499,6 +511,8 @@ impl f16 {
499511

500512
/// Returns the logarithm of the number with respect to an arbitrary base.
501513
///
514+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
515+
///
502516
/// The result might not be correctly rounded owing to implementation details;
503517
/// `self.log2()` can produce more accurate results for base 2, and
504518
/// `self.log10()` can produce more accurate results for base 10.
@@ -522,6 +536,16 @@ impl f16 {
522536
/// assert!(abs_difference <= f16::EPSILON);
523537
/// # }
524538
/// ```
539+
///
540+
/// Non-positive values:
541+
/// ```
542+
/// #![feature(f16)]
543+
/// # #[cfg(reliable_f16_math)] {
544+
///
545+
/// assert_eq!(0_f16.log(10.0), f16::NEG_INFINITY);
546+
/// assert!((-42_f16).log(10.0).is_nan());
547+
/// # }
548+
/// ```
525549
#[inline]
526550
#[rustc_allow_incoherent_impl]
527551
#[unstable(feature = "f16", issue = "116909")]
@@ -532,6 +556,8 @@ impl f16 {
532556

533557
/// Returns the base 2 logarithm of the number.
534558
///
559+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
560+
///
535561
/// # Unspecified precision
536562
///
537563
/// The precision of this function is non-deterministic. This means it varies by platform,
@@ -551,6 +577,16 @@ impl f16 {
551577
/// assert!(abs_difference <= f16::EPSILON);
552578
/// # }
553579
/// ```
580+
///
581+
/// Non-positive values:
582+
/// ```
583+
/// #![feature(f16)]
584+
/// # #[cfg(reliable_f16_math)] {
585+
///
586+
/// assert_eq!(0_f16.log2(), f16::NEG_INFINITY);
587+
/// assert!((-42_f16).log2().is_nan());
588+
/// # }
589+
/// ```
554590
#[inline]
555591
#[rustc_allow_incoherent_impl]
556592
#[unstable(feature = "f16", issue = "116909")]
@@ -561,6 +597,8 @@ impl f16 {
561597

562598
/// Returns the base 10 logarithm of the number.
563599
///
600+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
601+
///
564602
/// # Unspecified precision
565603
///
566604
/// The precision of this function is non-deterministic. This means it varies by platform,
@@ -580,6 +618,16 @@ impl f16 {
580618
/// assert!(abs_difference <= f16::EPSILON);
581619
/// # }
582620
/// ```
621+
///
622+
/// Non-positive values:
623+
/// ```
624+
/// #![feature(f16)]
625+
/// # #[cfg(reliable_f16_math)] {
626+
///
627+
/// assert_eq!(0_f16.log10(), f16::NEG_INFINITY);
628+
/// assert!((-42_f16).log10().is_nan());
629+
/// # }
630+
/// ```
583631
#[inline]
584632
#[rustc_allow_incoherent_impl]
585633
#[unstable(feature = "f16", issue = "116909")]
@@ -964,6 +1012,8 @@ impl f16 {
9641012
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
9651013
/// the operations were performed separately.
9661014
///
1015+
/// This returns NaN when `n < -1.0`, and negative infinity when `n == -1.0`.
1016+
///
9671017
/// # Unspecified precision
9681018
///
9691019
/// The precision of this function is non-deterministic. This means it varies by platform,
@@ -987,6 +1037,16 @@ impl f16 {
9871037
/// assert!(abs_difference < 1e-4);
9881038
/// # }
9891039
/// ```
1040+
///
1041+
/// Out-of-range values:
1042+
/// ```
1043+
/// #![feature(f16)]
1044+
/// # #[cfg(reliable_f16_math)] {
1045+
///
1046+
/// assert_eq!((-1.0_f16).ln_1p(), f16::NEG_INFINITY);
1047+
/// assert!((-2.0_f16).ln_1p().is_nan());
1048+
/// # }
1049+
/// ```
9901050
#[inline]
9911051
#[doc(alias = "log1p")]
9921052
#[rustc_allow_incoherent_impl]

‎library/std/src/f32.rs‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -424,6 +424,8 @@ impl f32 {
424424

425425
/// Returns the natural logarithm of the number.
426426
///
427+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
428+
///
427429
/// # Unspecified precision
428430
///
429431
/// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
@@ -441,6 +443,12 @@ impl f32 {
441443
///
442444
/// assert!(abs_difference <= f32::EPSILON);
443445
/// ```
446+
///
447+
/// Non-positive values:
448+
/// ```
449+
/// assert_eq!(0_f32.ln(), f32::NEG_INFINITY);
450+
/// assert!((-42_f32).ln().is_nan());
451+
/// ```
444452
#[rustc_allow_incoherent_impl]
445453
#[must_use = "method returns a new number and does not mutate the original value"]
446454
#[stable(feature = "rust1", since = "1.0.0")]
@@ -451,6 +459,8 @@ impl f32 {
451459

452460
/// Returns the logarithm of the number with respect to an arbitrary base.
453461
///
462+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
463+
///
454464
/// The result might not be correctly rounded owing to implementation details;
455465
/// `self.log2()` can produce more accurate results for base 2, and
456466
/// `self.log10()` can produce more accurate results for base 10.
@@ -470,6 +480,12 @@ impl f32 {
470480
///
471481
/// assert!(abs_difference <= f32::EPSILON);
472482
/// ```
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+
/// ```
473489
#[rustc_allow_incoherent_impl]
474490
#[must_use = "method returns a new number and does not mutate the original value"]
475491
#[stable(feature = "rust1", since = "1.0.0")]
@@ -480,6 +496,8 @@ impl f32 {
480496

481497
/// Returns the base 2 logarithm of the number.
482498
///
499+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
500+
///
483501
/// # Unspecified precision
484502
///
485503
/// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
@@ -495,6 +513,12 @@ impl f32 {
495513
///
496514
/// assert!(abs_difference <= f32::EPSILON);
497515
/// ```
516+
///
517+
/// Non-positive values:
518+
/// ```
519+
/// assert_eq!(0_f32.log2(), f32::NEG_INFINITY);
520+
/// assert!((-42_f32).log2().is_nan());
521+
/// ```
498522
#[rustc_allow_incoherent_impl]
499523
#[must_use = "method returns a new number and does not mutate the original value"]
500524
#[stable(feature = "rust1", since = "1.0.0")]
@@ -505,6 +529,8 @@ impl f32 {
505529

506530
/// Returns the base 10 logarithm of the number.
507531
///
532+
/// This returns NaN when the number is negative, and negative infinity when number is zero.
533+
///
508534
/// # Unspecified precision
509535
///
510536
/// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
@@ -520,6 +546,12 @@ impl f32 {
520546
///
521547
/// assert!(abs_difference <= f32::EPSILON);
522548
/// ```
549+
///
550+
/// Non-positive values:
551+
/// ```
552+
/// assert_eq!(0_f32.log10(), f32::NEG_INFINITY);
553+
/// assert!((-42_f32).log10().is_nan());
554+
/// ```
523555
#[rustc_allow_incoherent_impl]
524556
#[must_use = "method returns a new number and does not mutate the original value"]
525557
#[stable(feature = "rust1", since = "1.0.0")]
@@ -893,6 +925,8 @@ impl f32 {
893925
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
894926
/// the operations were performed separately.
895927
///
928+
/// This returns NaN when `n < -1.0`, and negative infinity when `n == -1.0`.
929+
///
896930
/// # Unspecified precision
897931
///
898932
/// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
@@ -911,6 +945,12 @@ impl f32 {
911945
///
912946
/// assert!(abs_difference < 1e-10);
913947
/// ```
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+
/// ```
914954
#[doc(alias = "log1p")]
915955
#[rustc_allow_incoherent_impl]
916956
#[must_use = "method returns a new number and does not mutate the original value"]

0 commit comments

Comments
 (0)