From 138ebd19c696996a8f4c99586d207bf02f7eeaf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Falk=20H=C3=BCffner?= Date: Tue, 7 Sep 2021 08:49:47 +0200 Subject: [PATCH] Improve docs for int_log * Clarify rounding. * Avoid "wrapping" wording. * Omit wrong claim on 0 only being returned in error cases. * Typo fix for one_less_than_next_power_of_two. --- library/core/src/num/int_macros.rs | 24 ++++++++++++------------ library/core/src/num/uint_macros.rs | 25 ++++++++++++------------- 2 files changed, 24 insertions(+), 25 deletions(-) diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs index 77643290cc4..6fc188a2772 100644 --- a/library/core/src/num/int_macros.rs +++ b/library/core/src/num/int_macros.rs @@ -2001,7 +2001,8 @@ macro_rules! int_impl { } } - /// Returns the logarithm of the number with respect to an arbitrary base. + /// Returns the logarithm of the number with respect to an arbitrary base, + /// rounded down. /// /// This method might not be optimized owing to implementation details; /// `log2` can produce results more efficiently for base 2, and `log10` @@ -2010,8 +2011,8 @@ macro_rules! int_impl { /// # Panics /// /// When the number is zero, or if the base is not at least 2; it - /// panics in debug mode and the return value is wrapped to 0 in release - /// mode (the only situation in which the method can return 0). + /// panics in debug mode and the return value is 0 in release + /// mode. /// /// # Examples /// @@ -2039,13 +2040,12 @@ macro_rules! int_impl { } } - /// Returns the base 2 logarithm of the number. + /// Returns the base 2 logarithm of the number, rounded down. /// /// # Panics /// /// When the number is zero it panics in debug mode and the return value - /// is wrapped to 0 in release mode (the only situation in which the - /// method can return 0). + /// is 0 in release mode. /// /// # Examples /// @@ -2073,13 +2073,12 @@ macro_rules! int_impl { } } - /// Returns the base 10 logarithm of the number. + /// Returns the base 10 logarithm of the number, rounded down. /// /// # Panics /// /// When the number is zero it panics in debug mode and the return value - /// is wrapped to 0 in release mode (the only situation in which the - /// method can return 0). + /// is 0 in release mode. /// /// # Example /// @@ -2107,7 +2106,8 @@ macro_rules! int_impl { } } - /// Returns the logarithm of the number with respect to an arbitrary base. + /// Returns the logarithm of the number with respect to an arbitrary base, + /// rounded down. /// /// Returns `None` if the number is negative or zero, or if the base is not at least 2. /// @@ -2147,7 +2147,7 @@ macro_rules! int_impl { } } - /// Returns the base 2 logarithm of the number. + /// Returns the base 2 logarithm of the number, rounded down. /// /// Returns `None` if the number is negative or zero. /// @@ -2171,7 +2171,7 @@ macro_rules! int_impl { } } - /// Returns the base 10 logarithm of the number. + /// Returns the base 10 logarithm of the number, rounded down. /// /// Returns `None` if the number is negative or zero. /// diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs index 46e64c33b84..2a8cb83d7bf 100644 --- a/library/core/src/num/uint_macros.rs +++ b/library/core/src/num/uint_macros.rs @@ -635,7 +635,8 @@ macro_rules! uint_impl { } } - /// Returns the logarithm of the number with respect to an arbitrary base. + /// Returns the logarithm of the number with respect to an arbitrary base, + /// rounded down. /// /// This method might not be optimized owing to implementation details; /// `log2` can produce results more efficiently for base 2, and `log10` @@ -644,8 +645,7 @@ macro_rules! uint_impl { /// # Panics /// /// When the number is negative, zero, or if the base is not at least 2; - /// it panics in debug mode and the return value is wrapped to 0 in - /// release mode (the only situation in which the method can return 0). + /// it panics in debug mode and the return value is 0 in release mode. /// /// # Examples /// @@ -673,13 +673,12 @@ macro_rules! uint_impl { } } - /// Returns the base 2 logarithm of the number. + /// Returns the base 2 logarithm of the number, rounded down. /// /// # Panics /// /// When the number is negative or zero it panics in debug mode and - /// the return value is wrapped to 0 in release mode (the only situation in - /// which the method can return 0). + /// the return value is 0 in release mode. /// /// # Examples /// @@ -707,13 +706,12 @@ macro_rules! uint_impl { } } - /// Returns the base 10 logarithm of the number. + /// Returns the base 10 logarithm of the number, rounded down. /// /// # Panics /// /// When the number is negative or zero it panics in debug mode and the - /// return value is wrapped to 0 in release mode (the only situation in - /// which the method can return 0). + /// return value is 0 in release mode. /// /// # Example /// @@ -741,7 +739,8 @@ macro_rules! uint_impl { } } - /// Returns the logarithm of the number with respect to an arbitrary base. + /// Returns the logarithm of the number with respect to an arbitrary base, + /// rounded down. /// /// Returns `None` if the number is zero, or if the base is not at least 2. /// @@ -781,7 +780,7 @@ macro_rules! uint_impl { } } - /// Returns the base 2 logarithm of the number. + /// Returns the base 2 logarithm of the number, rounded down. /// /// Returns `None` if the number is zero. /// @@ -805,7 +804,7 @@ macro_rules! uint_impl { } } - /// Returns the base 10 logarithm of the number. + /// Returns the base 10 logarithm of the number, rounded down. /// /// Returns `None` if the number is zero. /// @@ -1992,7 +1991,7 @@ macro_rules! uint_impl { /// Returns the smallest power of two greater than or equal to `self`. /// /// When return value overflows (i.e., `self > (1 << (N-1))` for type - /// `uN`), it panics in debug mode and return value is wrapped to 0 in + /// `uN`), it panics in debug mode and the return value is wrapped to 0 in /// release mode (the only situation in which method can return 0). /// /// # Examples