Add function `bitsign` (inverse of `signbit`)

[eschnett]

The mathematical expression (-1)^n appears in many equations. It would be convenient to have an efficient standard implementation in Julia. This is, in effect, the inverse of the signbit function.

I propose the following implementation:

function bitsign(b::Bool)::Int
    1 - 2 * b   # this seems to be the most efficient way
end

function bitsign(b::I)::I where {I<:Signed}
    I(bitsign(isodd(b)))
end

[StefanKarpinski]

Would this be generalized to complex powers as well?

[eschnett]

@StefanKarpinski Are you looking for cis? Maybe a new function cispi, similar to sinpi and cospi?

[StefanKarpinski]

I'm not looking for anything, just trying to reason about the function you've proposed. If the definition is that it computes (-1)^n then the fact that it always returns ±1 for integer values is a specialization; for complex arguments it should compute the more general function. Similarly, consider the behavior of sign for a complex argument:

julia> sign(1 + 1im)
0.7071067811865475 + 0.7071067811865475im

[eschnett]

@StefanKarpinski I see; going for a generic definition makes sense. Of course, the efficient implementation (much more efficient than actually calculating (-1)^n) exists only for integer n.

If you allow the exponent to be any real or complex number, then the implementation would be (-1)^x = exp(im*pi*x) = cis(pi*x). That's also an expression that occurs frequently. The name bitsign doesn't work any more here.

[StefanKarpinski]

Right, that's part of why I was asking—the name seemed a bit too specific to the implementation. I think calling it cispi might be good and mentioning it in the help text of signbit. I guess the biggest worry is that it's pretty non-obvious to most people that cispi(n) is (-1)^n.

[StefanKarpinski]

It's also kind of amazing and unexpected that cispi is the inverse function of signbit.

[eschnett]

I just realize that we don't need cispi, the existing cospi will do fine. Should we instead add a method for cospi (and sinpi, for symmetry) that acts on integers or booleans?

[vtjnash]

No consensus that this is something desired (rejected from #35792)