Add ispositive, etc. (#53677)

- #35067

It's faster for some complicated Real types.
```julia
julia> f(x) = x<=zero(typeof(x))
f (generic function with 1 method)

julia> g(x) = signbit(x)||iszero(x)
g (generic function with 1 method)

julia> @Btime f(x) setup=(x=rand(BigFloat))
  99.055 ns (4 allocations: 144 bytes)
true

julia> @Btime g(x) setup=(x=rand(BigFloat))
  10.700 ns (0 allocations: 0 bytes)
false
```

If you think this is a good idea then I'll add docstrings and tests.

Edit: FAQs according to discussions below
- Why `ispositive(x::Bool) = x`?
- Because it's fast.
#53677 (comment)
- Why support `ispositive(::Any)`?
  - #35067

---------

Co-authored-by: mikmoore <[email protected]>
Co-authored-by: Max Horn <[email protected]>
Co-authored-by: Mosè Giordano <[email protected]>

Author: 4 people

NEWS.md

@@ -26,6 +26,7 @@ Build system changes
 New library functions
 ---------------------
 
+* `ispositive(::Real)` and `isnegative(::Real)` are provided for performance and convenience ([#53677]).
 * Exporting function `fieldindex` to get the index of a struct's field ([#58119]).
 
 New library features

base/bool.jl

@@ -156,6 +156,7 @@ abs(x::Bool) = x
 abs2(x::Bool) = x
 iszero(x::Bool) = !x
 isone(x::Bool) = x
+ispositive(x::Bool) = x # could use fallback once #21712 is resolved
 
 <(x::Bool, y::Bool) = y&!x
 <=(x::Bool, y::Bool) = y|!x

base/exports.jl

@@ -338,7 +338,9 @@ export
     isinf,
     isinteger,
     isnan,
+    isnegative,
     isodd,
+    ispositive,
     ispow2,
     isqrt,
     isreal,

base/gmp.jl

@@ -11,7 +11,7 @@ import .Base: *, +, -, /, <, <<, >>, >>>, <=, ==, >, >=, ^, (~), (&), (|), xor,
              bin, oct, dec, hex, isequal, invmod, _prevpow2, _nextpow2, ndigits0zpb,
              widen, signed, unsafe_trunc, trunc, iszero, isone, big, flipsign, signbit,
              sign, isodd, iseven, digits!, hash, hash_integer, top_set_bit,
-             clamp, unsafe_takestring
+             ispositive, isnegative, clamp, unsafe_takestring
 
 import Core: Signed, Float16, Float32, Float64
 
@@ -383,7 +383,7 @@ function (::Type{T})(x::BigInt) where T<:Base.BitSigned
     else
         0 <= n <= cld(sizeof(T),sizeof(Limb)) || throw(InexactError(nameof(T), T, x))
         y = x % T
-        ispos(x) ⊻ (y > 0) && throw(InexactError(nameof(T), T, x)) # catch overflow
+        ispositive(x) ⊻ (y > 0) && throw(InexactError(nameof(T), T, x)) # catch overflow
         y
     end
 end
@@ -606,7 +606,7 @@ Number of ones in the binary representation of abs(x).
 count_ones_abs(x::BigInt) = iszero(x) ? 0 : MPZ.mpn_popcount(x)
 
 function top_set_bit(x::BigInt)
-    isneg(x) && throw(DomainError(x, "top_set_bit only supports negative arguments when they have type BitSigned."))
+    isnegative(x) && throw(DomainError(x, "top_set_bit only supports negative arguments when they have type BitSigned."))
     iszero(x) && return 0
     x.size * sizeof(Limb) << 3 - leading_zeros(GC.@preserve x unsafe_load(x.d, x.size))
 end
@@ -700,7 +700,7 @@ function prod(arr::AbstractArray{BigInt})
     foldl(MPZ.mul!, arr; init)
 end
 
-factorial(n::BigInt) = !isneg(n) ? MPZ.fac_ui(n) : throw(DomainError(n, "`n` must not be negative."))
+factorial(n::BigInt) = !isnegative(n) ? MPZ.fac_ui(n) : throw(DomainError(n, "`n` must not be negative."))
 
 function binomial(n::BigInt, k::Integer)
     k < 0 && return BigInt(0)
@@ -732,17 +732,17 @@ isone(x::BigInt) = x == Culong(1)
 <(i::Integer, x::BigInt) = cmp(x,i) > 0
 <(x::BigInt, f::CdoubleMax) = isnan(f) ? false : cmp(x,f) < 0
 <(f::CdoubleMax, x::BigInt) = isnan(f) ? false : cmp(x,f) > 0
-isneg(x::BigInt) = x.size < 0
-ispos(x::BigInt) = x.size > 0
+isnegative(x::BigInt) = x.size < 0
+ispositive(x::BigInt) = x.size > 0
 
-signbit(x::BigInt) = isneg(x)
+signbit(x::BigInt) = isnegative(x)
 flipsign!(x::BigInt, y::Integer) = (signbit(y) && (x.size = -x.size); x)
 flipsign( x::BigInt, y::Integer) = signbit(y) ? -x : x
 flipsign( x::BigInt, y::BigInt)  = signbit(y) ? -x : x
 # above method to resolving ambiguities with flipsign(::T, ::T) where T<:Signed
 function sign(x::BigInt)
-    isneg(x) && return -one(x)
-    ispos(x) && return one(x)
+    isnegative(x) && return -one(x)
+    ispositive(x) && return one(x)
     return x
 end
 
@@ -754,12 +754,12 @@ function string(n::BigInt; base::Integer = 10, pad::Integer = 1)
     iszero(n) && pad < 1 && return ""
     nd1 = ndigits(n, base=base)
     nd  = max(nd1, pad)
-    sv  = Base.StringMemory(nd + isneg(n))
+    sv  = Base.StringMemory(nd + isnegative(n))
     GC.@preserve sv MPZ.get_str!(pointer(sv) + nd - nd1, base, n)
-    @inbounds for i = (1:nd-nd1) .+ isneg(n)
+    @inbounds for i = (1:nd-nd1) .+ isnegative(n)
         sv[i] = '0' % UInt8
     end
-    isneg(n) && (sv[1] = '-' % UInt8)
+    isnegative(n) && (sv[1] = '-' % UInt8)
     unsafe_takestring(sv)
 end
 
@@ -769,7 +769,7 @@ function digits!(a::AbstractVector{T}, n::BigInt; base::Integer = 10) where {T<:
             # fast path using mpz_get_str via string(n; base)
             s = codeunits(string(n; base))
             i, j = firstindex(a)-1, length(s)+1
-            lasti = min(lastindex(a), firstindex(a) + length(s)-1 - isneg(n))
+            lasti = min(lastindex(a), firstindex(a) + length(s)-1 - isnegative(n))
             while i < lasti
                 # base ≤ 36: 0-9, plus a-z for 10-35
                 # base > 36: 0-9, plus A-Z for 10-35 and a-z for 36..61
@@ -778,14 +778,14 @@ function digits!(a::AbstractVector{T}, n::BigInt; base::Integer = 10) where {T<:
             end
             lasti = lastindex(a)
             while i < lasti; a[i+=1] = zero(T); end
-            return isneg(n) ? map!(-,a,a) : a
+            return isnegative(n) ? map!(-,a,a) : a
         elseif a isa StridedVector{<:Base.BitInteger} && stride(a,1) == 1 && ispow2(base) && base-1 ≤ typemax(T)
             # fast path using mpz_export
             origlen = length(a)
             _, writelen = MPZ.export!(a, n; nails = 8sizeof(T) - trailing_zeros(base))
             length(a) != origlen && resize!(a, origlen) # truncate to least-significant digits
             a[begin+writelen:end] .= zero(T)
-            return isneg(n) ? map!(-,a,a) : a
+            return isnegative(n) ? map!(-,a,a) : a
         end
     end
     return invoke(digits!, Tuple{typeof(a), Integer}, a, n; base) # slow generic fallback
@@ -917,7 +917,7 @@ module MPQ
 
 # Rational{BigInt}
 import .Base: unsafe_rational, __throw_rational_argerror_zero
-import ..GMP: BigInt, MPZ, Limb, isneg, libgmp
+import ..GMP: BigInt, MPZ, Limb, libgmp
 
 gmpq(op::Symbol) = (Symbol(:__gmpq_, op), libgmp)
 
@@ -995,7 +995,7 @@ end
 # define add, sub, mul, div, and their inplace versions
 function add!(z::Rational{BigInt}, x::Rational{BigInt}, y::Rational{BigInt})
     if iszero(x.den) || iszero(y.den)
-        if iszero(x.den) && iszero(y.den) && isneg(x.num) != isneg(y.num)
+        if iszero(x.den) && iszero(y.den) && isnegative(x.num) != isnegative(y.num)
             throw(DivideError())
         end
         return set!(z, iszero(x.den) ? x : y)
@@ -1008,7 +1008,7 @@ end
 
 function sub!(z::Rational{BigInt}, x::Rational{BigInt}, y::Rational{BigInt})
     if iszero(x.den) || iszero(y.den)
-        if iszero(x.den) && iszero(y.den) && isneg(x.num) == isneg(y.num)
+        if iszero(x.den) && iszero(y.den) && isnegative(x.num) == isnegative(y.num)
             throw(DivideError())
         end
         iszero(x.den) && return set!(z, x)
@@ -1025,7 +1025,7 @@ function mul!(z::Rational{BigInt}, x::Rational{BigInt}, y::Rational{BigInt})
         if iszero(x.num) || iszero(y.num)
             throw(DivideError())
         end
-        return set_si!(z, ifelse(xor(isneg(x.num), isneg(y.num)), -1, 1), 0)
+        return set_si!(z, ifelse(xor(isnegative(x.num), isnegative(y.num)), -1, 1), 0)
     end
     zq = _MPQ(z)
     ccall((:__gmpq_mul, libgmp), Cvoid,
@@ -1038,7 +1038,7 @@ function div!(z::Rational{BigInt}, x::Rational{BigInt}, y::Rational{BigInt})
         if iszero(y.den)
             throw(DivideError())
         end
-        isneg(y.num) || return set!(z, x)
+        isnegative(y.num) || return set!(z, x)
         return set_si!(z, flipsign(-1, x.num), 0)
     elseif iszero(y.den)
         return set_si!(z, 0, 1)

base/int.jl

@@ -139,6 +139,8 @@ iseven(n::Real) = isinteger(n) && iszero(rem(Integer(n), 2))
 signbit(x::Integer) = x < 0
 signbit(x::Unsigned) = false
 
+isnegative(x::Unsigned) = false
+
 flipsign(x::T, y::T) where {T<:BitSigned} = flipsign_int(x, y)
 flipsign(x::BitSigned, y::BitSigned) = flipsign_int(promote(x, y)...) % typeof(x)
 

base/missing.jl

@@ -86,6 +86,8 @@ isequal(::Any, ::Missing) = false
 isless(::Missing, ::Missing) = false
 isless(::Missing, ::Any) = false
 isless(::Any, ::Missing) = true
+ispositive(::Missing) = missing
+isnegative(::Missing) = missing
 isapprox(::Missing, ::Missing; kwargs...) = missing
 isapprox(::Missing, ::Any; kwargs...) = missing
 isapprox(::Any, ::Missing; kwargs...) = missing

base/mpfr.jl

@@ -18,7 +18,8 @@ import
         setrounding, maxintfloat, widen, significand, frexp, tryparse, iszero,
         isone, big, _string_n, decompose, minmax, _precision_with_base_2,
         sinpi, cospi, sincospi, tanpi, sind, cosd, tand, asind, acosd, atand,
-        uinttype, exponent_max, exponent_min, ieee754_representation, significand_mask
+        uinttype, exponent_max, exponent_min, ieee754_representation, significand_mask,
+        ispositive, isnegative
 
 import .Core: AbstractFloat
 import .Base: Rational, Float16, Float32, Float64, Bool
@@ -1135,6 +1136,10 @@ isfinite(x::BigFloat) = !isinf(x) && !isnan(x)
 iszero(x::BigFloat) = x.exp == mpfr_special_exponent_zero
 isone(x::BigFloat) = x == Clong(1)
 
+# In theory, `!iszero(x) && !isnan(x)` should be the same as `x.exp > mpfr_special_exponent_nan`, but this is safer.
+ispositive(x::BigFloat) = !signbit(x) && !iszero(x) && !isnan(x)
+isnegative(x::BigFloat) = signbit(x) && !iszero(x) && !isnan(x)
+
 @eval typemax(::Type{BigFloat}) = $(BigFloat(Inf))
 @eval typemin(::Type{BigFloat}) = $(BigFloat(-Inf))
 

base/number.jl

@@ -136,6 +136,50 @@ true
 """
 signbit(x::Real) = x < 0
 
+"""
+    ispositive(x)
+
+Test whether `x > 0`. See also [`isnegative`](@ref).
+
+!!! compat "Julia 1.13"
+    This function requires at least Julia 1.13.
+
+# Examples
+```jldoctest
+julia> ispositive(-4.0)
+false
+
+julia> ispositive(99)
+true
+
+julia> ispositive(0.0)
+false
+```
+"""
+ispositive(x::Real) = x > 0
+
+"""
+    isnegative(x)
+
+Test whether `x < 0`. See also [`ispositive`](@ref).
+
+!!! compat "Julia 1.13"
+    This function requires at least Julia 1.13.
+
+# Examples
+```jldoctest
+julia> isnegative(-4.0)
+true
+
+julia> isnegative(99)
+false
+
+julia> isnegative(-0.0)
+false
+```
+"""
+isnegative(x::Real) = x < 0
+
 """
     sign(x)
 

doc/src/base/base.md

@@ -139,6 +139,8 @@ Core.:(===)
 Core.isa
 Base.isequal
 Base.isless
+Base.ispositive
+Base.isnegative
 Base.isunordered
 Base.ifelse
 Core.typeassert

test/numbers.jl

@@ -831,6 +831,28 @@ end
     @test cmp(isless, 1, NaN) == -1
     @test cmp(isless, NaN, NaN) == 0
 end
+@testset "ispositive/isnegative" begin
+    for T in [Base.uniontypes(Base.BitInteger)..., Bool, Rational{Int}, BigInt, Base.uniontypes(Base.IEEEFloat)..., BigFloat, Missing]
+        values = T[zero(T), one(T)]
+        if T <: AbstractFloat
+            push!(values, Inf, NaN) # also check Infs and NaNs
+        elseif T <: Rational
+            push!(values, 1//0) # also check Infs
+        end
+        @testset "$T" begin
+            for value in values
+                # https://github.com/JuliaLang/julia/pull/53677#discussion_r1534044582
+                # Use eval to explicitly show expressions when they fail
+                @eval begin
+                    @test ispositive($value) === ($value > 0)
+                    @test ispositive(-$value) === (-$value > 0)
+                    @test isnegative($value) === ($value < 0)
+                    @test isnegative(-$value) === (-$value < 0)
+                end
+            end
+        end
+    end
+end
 @testset "Float vs Integer comparison" begin
     for x=-5:5, y=-5:5
         @test (x==y)==(Float64(x)==Int64(y))