Make `BinaryInteger._binaryLogarithm()` public API

[tstromberg (Tyler Stromberg)]

I am currently implementing a min-max heap (to back a priority queue), and this function would be useful in determining if a given index falls into a min layer or max layer. Yes, I could copy the implementation of FixedWidthInteger._binaryLogarithm() into my code (and I have basically already implemented the same thing), but maybe it's time to have a discussion about removing the prefix on this function and making it public API instead.

Three questions about the bitWidth type- and instance properties

There is one, but it's not public :) It's spelled _binaryLogarithm() + 1 and it's available on BinaryInteger. (For reasons beyond the scope of our discussion here, _binaryLogarithm() is generally more useful than _binaryLogarithm() + 1.) The method is probably useful enough that it could pass the bar for becoming a public API, but I dread the bikeshedding and haven't proposed it. For end users, though, it's not really more convenient than bitWidth - leadingZeroBitCount.

Thoughts?

[Dmitriy_Ignatyev]

Seems it can be exposed as part of public API.

"Yes, I could copy the implementation of FixedWidthInteger._binaryLogarithm() into my code" – why should you copy it? The following code is valid:

let binaryLogarithm = Int(0)._binaryLogarithm()

The problem is that currently it is marked with underscore and therefore unofficial.
So, lets make it official.

[tstromberg (Tyler Stromberg)]

why should you copy it? The following code is valid:

Yeah, fair. I mostly wanted to insulate myself from the change if it gets promoted to official public API.

There hasn't been much engagement on this; I think I'm going to work on putting together an official evolution proposal.