Skip to content

Commit

Permalink
Improve docs for int_log
Browse files Browse the repository at this point in the history 
* 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.
  • Loading branch information
Falk Hüffner committed Sep 7, 2021
1 parent b2d9bcd commit 138ebd1
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 25 deletions.
24 changes: 12 additions & 12 deletions library/core/src/num/int_macros.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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
///
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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.
///
Expand Down Expand Up @@ -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.
///
Expand All @@ -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.
///
Expand Down
25 changes: 12 additions & 13 deletions library/core/src/num/uint_macros.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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
///
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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.
///
Expand Down Expand Up @@ -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.
///
Expand All @@ -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.
///
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 138ebd1

Please sign in to comment.