What's the correct *wrapping* value for `ilog{|2|10}`?

[scottmcm]

Filing since it's in pFCP over at #70887 (comment), and I don't think we can reasonably change it after stabilization (especially since it's documented).

Currently, 0.ilog2() in release mode evaluates to 0. (And same for the other bases.)

It's not obvious to me that that's necessarily the best option. For example, the (BITS-1) - LeadingZeros implementation is slightly nicer on CPUs from the past decade or so https://rust.godbolt.org/z/3q6WME84Y (and I think would be just as nice on older ones if LLVM was a bit smarter), but gives -1_{as u32} in 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 1.ilog2() and 0.ilog2() give the same thing. For example u32::MAX.next_power_of_two() returns 0 in release mode, which isn't a power of two (according to is_power_of_two), so it's distinguishable from all the non-wrapping cases.

This only affects ilog/ilog2/ilog10 on uNN. (The checked versions don't have an issue, nor do the ones on NonZeroUNN.)

[scottmcm]

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 panic!.

There was this note: #80918 (comment)

In this case of logs, checking has to be done anyway

For which I think the ilog2 implementation I mention above is a counter-example, albeit only for the base-2 case.

Also, currently ilog2 in release mode is essentially .checked_ilog2().unwrap_or(0), so we can pick any value we want to return for those cases.

---

FWIW, the implementation in https://graphics.stanford.edu/~seander/bithacks.html#IntegerLogLookup gives -1 as the result for ilog2(0).

[leonardo-m]

In Rust we try to do the right thing. Not even Python gives -1. Let's avoid in-band error values in Rust.

[scottmcm]

@leonardo-m What's your proposal for what the "right" thing is, then? That 0.ilog2() panic in release too?

Arguably the most-correct value is −∞ (like (+0.0_f32).log2()), but that doesn't fit in any of our integer types.

So 0.saturating_ilog2() => 0 would make sense, but release mode for the other un-prefixed things is wrapping, not saturating.

[leonardo-m]

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.

[cmpute]

I think returning -1 (wrapped if necessary) is a clear distinguish between normal and error result. Returning an Option 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 i32::MIN as u32? However it seems weird and -1 still seems better to me

[leonardo-m]

I think returning -1 (wrapped if necessary) is a clear distinguish between normal and error result.

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).

Returning an Option is not ideal currently because it will makes the function practically unusable in const context (before const unwrap is stabilized)

Let's return Option and and wait for const unwrap to be stabilized before making ilog const, then.

[scottmcm]

Let's return Option and [...]

That's what 0.checked_ilog2() does already. Is your proposal, then, that the -> u32 version of ilog2 just shouldn't exist on uNN? How do you square that with precedent of other things -- like uNN::next_power_of_two or iNN::abs -- that have the checked_ version return Option, but the un-prefixed one wrap in release mode?

[programmerjake]

what about treating it like division by zero and just panicking?

[lnicola]

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 UNN::BITS - x.leading_zeros() - 1 to keep the code branchless and avoid the ugly unwrap()) and a defined value outside of the usual input range. u32::MAX.next_power_of_two() (from above) is a good example.

If you want stricter guarantees than that, you can use NonZeroUNN.

[jdahlstrom]

A minor point: u32::MAX.next_power_of_two() 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 ilog2.