Change:
Filing since it's in pFCP over at , and I don't think we can reasonably change it after stabilization (especially since it's documented). Currently, in release mode evaluates to . (And same for the other bases.) It's not obvious to me that that's necessarily the best option. For example, the implementation is slightly nicer on CPUs from the past or so (and I think would be just as nice on older ones ), but gives <subas u32</subin the wrapping case. It also might be nice to have the wrapping case give something clearly different from any of the successful cases, rather than having and give the same thing. For example returns in release mode, which isn't a power of two (according to ), so it's distinguishable from all the non-wrapping cases. This only affects // on . (The checked versions don't have an issue, nor do the ones on .)
I couldn't find any previous discussion of what the exact wrapping value ought to be, just that there ought to be one, as opposed to a . There was this note: For which I think the implementation I mention above is a counter-example, albeit only for the base-2 case. Also, currently in release mode is essentially , so we can pick any value we want to return for those cases. FWIW, the implementation in gives as the result for .
In Rust we try to do the right thing. Not even Python gives -1. Let's avoid in-band error values in Rust.
What's your proposal for what the "right" thing is, then? That panic in release too? Arguably the most-correct value is −∞ (like ), but that doesn't fit in any of our integer types. So would make sense, but release mode for the other un-prefixed things is wrapping, not saturating.
Python has some functions that return in-band values: "xy".find("y") 1 "xy".find("z") -1 From Rust I expect something better. In Rust if a function isn't naturally total and you can't restrict its input, then I expect it to return Option (or Result), or when that's isn't ergonomic enough, a panic (in release too). Returning -1 is dangerous as that Python find function, returning 0 is not math.
I think returning (wrapped if necessary) is a clear distinguish between normal and error result. Returning an is not ideal currently because it will makes the function practically unusable in const context (before const unwrap is stabilized) If getting closest to the "correct" math answer, how about choosing ? However it seems weird and still seems better to me
Perhaps in other languages. Rust is known for being better than that. I have chosen to use Rust because it's a bit better than Python (see above). Let's return Option and and wait for const unwrap to be stabilized before making ilog const, then.
That's what does already. Is your proposal, then, that the version of just shouldn't exist on ? How do you square that with precedent of other things -- like or -- that have the version return , but the un-prefixed one wrap in release mode?
what about treating it like division by zero and just panicking?
I'd be fine with -1. The point of these methods is to get fast code (otherwise many won't use them and will prefer to do to keep the code branchless and avoid the ugly ) and a defined value outside of the usual input range. (from above) is a good example. If you want stricter guarantees than that, you can use .
A minor point: being 0 is actually a reasonable choice - even though 0 is not a power of two, it is congruent to the correct power of two modulo 2^32 (which is 2^32 itself), so exactly what is expected in wrapping arithmetic. But unfortunately there's no "−∞ mod 2^32" that could be used for .
Modular arithmetic is confusing in the context of logarithm, if you want to return the discrete logarithm of 0 in the release mode, then there are a lot of candidates, because (in case of ) therefore in the sense of modular arithmetic, could be any multiple of . If you really want to achieve something close to , then I guess the best value is as I mentioned above. (Interestingly though, = , which is a multiple of 8, 16, 32, 64, 128)
That's certainly a possibility. suggested not doing that back in the original PR, though:
Doesn't implicitly include a check for zero in the code generated? ]
Also, since the methods are implemented for signed integers as well, another issue would be the log of negative values. For example for floating-point, would return &minus;&infin;, but would return NaN. So if would return some value for &minus;&infin;, would panic anyway, or return some value?
I don't think it makes sense to do anything other than panic in the case of negative values, which in turn is probably an argument for panicking on zero as well. I guess one could argue that "wrapping" could be interpreted as wrapping the preimage to fit in the function's domain (rather than just wrapping the image to fit in the range) but IMO that would be entirely unintuitive and unhelpful as well. After thinking about it a bit, it seems to me that simply cannot have a meaningful variant, because semantics (as reasonably interpreted) cannot answer the question "what should the result be for values for which the original function is undefined?" There are no elements in 's domain for which the function underflows or overflows.
That's only the case on old chips. As I linked in the OP (), that happens in the instruction generation very-last-phase of LLVM on old chips, and on newer chips it knows to emit a different instruction instead of the branching code: The good news is that it looks like newer LLVM has gotten smarter here. It used to be that, because of how the intrinsic gets translated, it would emit obviously-redundant assembly on old chips in some code patterns, as you could see in Rust 1.16:
is supposed to find the largest so that . Since computers use wrapping arithmetic, the equation is better put as . The largest satisfying this equation in the case is (aka ). So if we consider a wrapping to be the inverse of , makes perfect sense (and is very efficient on modern CPUs, as others have pointed out). I would also advocate for to be as a method which always has this behaviour. [Edit: it already behaves that way]
Note that's already how works . It's just that it wraps to in release right now -- this issue doesn't propose removing the panic in debug behaviour, just to figure out what the best value for release would be.
Since, from the notes, it seems like the libs-api meeting today said "how about we panic instead of wrap", I'll try to answer my own question from above: I would propose the following rule: Conceptually, the result is first calculated in true ℤ (aka to infinite precision). Then for the non-prefixed versions If that result is undefined (, , etc), then it panics (regardless of compilation mode) If that result is defined and fits in the result type, it's returned. If that result is defined but not in-range for the result type, it panics if overflow checking is enabled, and wraps (mod 2<supN</supfor uN) if overflow checking is disabled. I think that's consistent with all the current precedent. ( also is good reading about the distinction I'm drawing here.)
I would redefine that to include cases where the result is defined but you can't wrap that to the result type, e.g. or . that would cover and
I agree, but was considering that implied by "in ℤ", as that set includes neither −∞ nor ⅈ. (Like how is , not a complex number.)
I'm not necessarily against panicking in that case. I just pointed out how it's a bit inconsistent with the other operations we have on integers. (Whether it makes sense for the other operations to have this difference in behavior between debug and release mode is an interesting discussion too, but I'm afraid that ship has sailed.) The reason we don't always panic on overflow for and etc. is performance. It's simply too costly to do. (We always panic on division by zero because that's both mathematically undefined (even modulo 2<supBITS</sup) and because on some platforms, the native division instruction will signal/abort/trap the program when the right hand side is zero.) We applied the same reasoning to things like and , although one might reasonably argue that for those it might be fine to always panic, since these are not as common as and . (You could then still use if you really want to make sure there's no check, if you're sure it's unnecessary.) That seems reasonable. It'd be nice if it'd still be easy to get the efficient calculation through some usage of or though. It looks like llvm isn't smart enough today to turn into simply a count-leading-zeros and a subtract instruction. :(
We discussed this again in the libs-api meeting, and we concluded pretty much the same as rule, meaning that these functions should panic on zero in all compilation modes, since there's not a modulo-2<supN</sup-correct result.

Discussion:
/// /// # Panics /// <del> /// 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 0 in release /// mode. </del> <ins> /// This function will panic if `self` is less than or equal to zero, /// or if `base` is less then 2. </ins> /// /// # Examples ///

without modifying the original"] #[inline] #[track_caller] <del> #[rustc_inherit_overflow_checks] #[allow(arithmetic_overflow)] </del> pub const fn ilog(self, base: Self) -> u32 { <del> match self.checked_ilog(base) { Some(n) => n, None => { // In debug builds, trigger a panic on None. // This should optimize completely out in release builds. let _ = Self::MAX + 1; 0 }, } </del> <ins> assert!(base >= 2, "base of integer logarithm must be at least 2"); self.checked_ilog(base).expect("argument of integer logarithm must be positive") </ins> } /// Returns the base 2 logarithm of the number, rounded down. /// /// # Panics /// <del> /// When the number is negative or zero it panics in debug mode and the return value /// is 0 in release mode. </del> <ins> /// This function will panic if `self` is less than or equal to zero. </ins> /// /// # Examples ///

without modifying the original"] #[inline] #[track_caller] <del> #[rustc_inherit_overflow_checks] #[allow(arithmetic_overflow)] </del> pub const fn ilog2(self) -> u32 { <del> match self.checked_ilog2() { Some(n) => n, None => { // In debug builds, trigger a panic on None. // This should optimize completely out in release builds. let _ = Self::MAX + 1; 0 }, } </del> <ins> self.checked_ilog2().expect("argument of integer logarithm must be positive") </ins> } /// Returns the base 10 logarithm of the number, rounded down. /// /// # Panics /// <del> /// When the number is negative or zero it panics in debug mode and the return value /// is 0 in release mode. </del> <ins> /// This function will panic if `self` is less than or equal to zero. </ins> /// /// # Example ///

/// /// # Panics /// <del> /// When the number is zero, or if the base is not at least 2; /// it panics in debug mode and the return value is 0 in release mode. </del> <ins> /// This function will panic if `self` is zero, or if `base` is less then 2. </ins> /// /// # Examples ///

without modifying the original"] #[inline] #[track_caller] <del> #[rustc_inherit_overflow_checks] #[allow(arithmetic_overflow)] </del> pub const fn ilog(self, base: Self) -> u32 { <del> match self.checked_ilog(base) { Some(n) => n, None => { // In debug builds, trigger a panic on None. // This should optimize completely out in release builds. let _ = Self::MAX + 1; 0 }, } </del> <ins> assert!(base >= 2, "base of integer logarithm must be at least 2"); self.checked_ilog(base).expect("argument of integer logarithm must be positive") </ins> } /// Returns the base 2 logarithm of the number, rounded down. /// /// # Panics /// <del> /// When the number is zero it panics in debug mode and /// the return value is 0 in release mode. </del> <ins> /// This function will panic if `self` is zero. </ins> /// /// # Examples ///

without modifying the original"] #[inline] #[track_caller] <del> #[rustc_inherit_overflow_checks] #[allow(arithmetic_overflow)] </del> pub const fn ilog2(self) -> u32 { <del> match self.checked_ilog2() { Some(n) => n, None => { // In debug builds, trigger a panic on None. // This should optimize completely out in release builds. let _ = Self::MAX + 1; 0 }, } </del> <ins> self.checked_ilog2().expect("argument of integer logarithm must be positive") </ins> } /// Returns the base 10 logarithm of the number, rounded down. /// /// # Panics /// <del> /// When the number is zero it panics in debug mode and the /// return value is 0 in release mode. </del> <ins> /// This function will panic if `self` is zero. </ins> /// /// # Example ///

without modifying the original"] #[inline] #[track_caller] <del> #[rustc_inherit_overflow_checks] #[allow(arithmetic_overflow)] </del> pub const fn ilog10(self) -> u32 { <del> match self.checked_ilog10() { Some(n) => n, None => { // In debug builds, trigger a panic on None. // This should optimize completely out in release builds. let _ = Self::MAX + 1; 0 }, } </del> <ins> self.checked_ilog10().expect("argument of integer logarithm must be positive") </ins> } /// Returns the logarithm of the number with respect to an arbitrary base,

fn ilog10_u128() { ilog10_loop! { u128, 38 } } <ins> #[test] #[should_panic(expected = "argument of integer logarithm must be positive")] fn ilog2_of_0_panic() { let _ = 0u32.ilog2(); } #[test] #[should_panic(expected = "argument of integer logarithm must be positive")] fn ilog10_of_0_panic() { let _ = 0u32.ilog10(); } #[test] #[should_panic(expected = "argument of integer logarithm must be positive")] fn ilog3_of_0_panic() { let _ = 0u32.ilog(3); } #[test] #[should_panic(expected = "base of integer logarithm must be at least 2")] fn ilog0_of_1_panic() { let _ = 1u32.ilog(0); } #[test] #[should_panic(expected = "base of integer logarithm must be at least 2")] fn ilog1_of_1_panic() { let _ = 1u32.ilog(1); } </ins>