Rebase of #35792, add cispi function (#38449)

* Implement cispi

* Review comments in #35792

* Remove docs relating cispi and signbit

* Review comment, more expressive function doc.

Co-authored-by: Simeon Schaub <simeondavidschaub99@gmail.com>

* Switch examples to show complex outputs

Co-authored-by: Erik Schnetter <schnetter@gmail.com>
Co-authored-by: Simeon Schaub <simeondavidschaub99@gmail.com>

Author: 3 people

base/complex.jl

@@ -541,6 +541,30 @@ function cis(z::Complex)
     Complex(v * c, v * s)
 end
 
+cispi(theta::Real) = Complex(reverse(sincospi(theta))...)
+
+"""
+    cispi(z)
+
+Compute ``\\exp(i\\pi x)`` more accurately than `cis(pi*x)`, especially for large `x`.
+
+# Examples
+```jldoctest
+julia> cispi(1)
+-1.0 + 0.0im
+
+julia> cispi(0.25 + 1im)
+0.030556854645952924 + 0.030556854645952924im
+```
+
+!!! compat "Julia 1.6"
+    This function requires Julia 1.6 or later.
+"""
+function cispi(z::Complex)
+    sipi, copi = sincospi(z)
+    return complex(real(copi) - imag(sipi), imag(copi) + real(sipi))
+end
+
 """
     angle(z)
 

base/exports.jl

@@ -229,6 +229,7 @@ export
     cbrt,
     ceil,
     cis,
+    cispi,
     clamp,
     cld,
     cmp,

doc/src/base/math.md

@@ -162,6 +162,7 @@ Base.reim
 Base.conj
 Base.angle
 Base.cis
+Base.cispi
 Base.binomial
 Base.factorial
 Base.gcd

test/complex.jl

@@ -123,6 +123,8 @@ end
             @test atanh(x) ≈ atanh(big(x))
             @test cis(real(x)) ≈ cis(real(big(x)))
             @test cis(x) ≈ cis(big(x))
+            @test cispi(real(x)) ≈ cispi(real(big(x)))
+            @test cispi(x) ≈ cispi(big(x))
             @test cos(x) ≈ cos(big(x))
             @test cosh(x) ≈ cosh(big(x))
             @test exp(x) ≈ exp(big(x))
@@ -918,6 +920,21 @@ end
     @test cis(1.0+0.0im) ≈ 0.54030230586813971740093660744297660373231042061+0.84147098480789650665250232163029899962256306079im
     @test cis(pi) ≈ -1.0+0.0im
     @test cis(pi/2) ≈ 0.0+1.0im
+    @test cispi(false) == 1
+    @test cispi(true) == -1
+    @test cispi(-1) == -1
+    @test cispi(0) == 1
+    @test cispi(1) == -1
+    @test cispi(2) == 1
+    @test cispi(0.0) == cispi(0)
+    @test cispi(1.0) == cispi(1)
+    @test cispi(2.0) == cispi(2)
+    @test cispi(0.5) == im
+    @test cispi(1.5) == -im
+    @test cispi(0.25) ≈ cis(π/4)
+    @test cispi(0.0+0.0im) == cispi(0)
+    @test cispi(1.0+0.0im) == cispi(1)
+    @test cispi(2.0+0.0im) == cispi(2)
 end
 
 @testset "exp2" begin