Rename realmin/max -> floatmin/max (#28302)

The names `realmin`/`realmax`, don't make too much sense in our terminology. These function are floating-point property queries, querying in particular the largest/smallest positive normalized floating point value. `posnormfloatmin` isn't a great name however, so simply `floatmin` was suggested. This has the advantage that it's suggestive of the fact that it's a floating point type query, even if it's not quite the minimum floating point value or even the minimum positive floating point value, but that's what docs are for. In any case, they're better than real. We have a good number of subtypes of `Real` for which these functions make no sense. In libc, these are called FLT_MIN/FLT_MAX or DBL_MIN/DBL_MAX.

NEWS.md

@@ -1323,6 +1323,8 @@ Deprecated or removed
 
   * `squeeze` is deprecated in favor of `dropdims`.
 
+  * `realmin`/`realmax` are deprecated in favor of `floatmin`/`floatmax` ([#28302]).
+
 Command-line option changes
 ---------------------------
 

base/complex.jl

@@ -364,8 +364,8 @@ function /(z::ComplexF64, w::ComplexF64)
     two = 2.0
     ab = max(abs(a), abs(b))
     cd = max(abs(c), abs(d))
-    ov = realmax(a)
-    un = realmin(a)
+    ov = floatmax(a)
+    un = floatmin(a)
     ϵ = eps(Float64)
     bs = two/(ϵ*ϵ)
     s = 1.0
@@ -397,8 +397,8 @@ function inv(w::ComplexF64)
     half = 0.5
     two = 2.0
     cd = max(abs(c), abs(d))
-    ov = realmax(c)
-    un = realmin(c)
+    ov = floatmax(c)
+    un = floatmin(c)
     ϵ = eps(Float64)
     bs = two/(ϵ*ϵ)
     s = 1.0

base/deprecated.jl

@@ -1771,6 +1771,10 @@ end
 # PR #28223
 @deprecate code_llvm_raw(f, types=Tuple) code_llvm(f, types; raw=true)
 
+# PR #28302
+@deprecate realmin floatmin
+@deprecate realmax floatmax
+
 # END 0.7 deprecations
 
 # BEGIN 1.0 deprecations

base/exports.jl

@@ -309,8 +309,8 @@ export
     rad2deg,
     rationalize,
     real,
-    realmax,
-    realmin,
+    floatmax,
+    floatmin,
     reim,
     reinterpret,
     rem,

base/float.jl

@@ -725,46 +725,46 @@ end
     typemin(x::T) where {T<:Real} = typemin(T)
     typemax(x::T) where {T<:Real} = typemax(T)
 
-    realmin(::Type{Float16}) = $(bitcast(Float16, 0x0400))
-    realmin(::Type{Float32}) = $(bitcast(Float32, 0x00800000))
-    realmin(::Type{Float64}) = $(bitcast(Float64, 0x0010000000000000))
-    realmax(::Type{Float16}) = $(bitcast(Float16, 0x7bff))
-    realmax(::Type{Float32}) = $(bitcast(Float32, 0x7f7fffff))
-    realmax(::Type{Float64}) = $(bitcast(Float64, 0x7fefffffffffffff))
-
-    eps(x::AbstractFloat) = isfinite(x) ? abs(x) >= realmin(x) ? ldexp(eps(typeof(x)), exponent(x)) : nextfloat(zero(x)) : oftype(x, NaN)
+    floatmin(::Type{Float16}) = $(bitcast(Float16, 0x0400))
+    floatmin(::Type{Float32}) = $(bitcast(Float32, 0x00800000))
+    floatmin(::Type{Float64}) = $(bitcast(Float64, 0x0010000000000000))
+    floatmax(::Type{Float16}) = $(bitcast(Float16, 0x7bff))
+    floatmax(::Type{Float32}) = $(bitcast(Float32, 0x7f7fffff))
+    floatmax(::Type{Float64}) = $(bitcast(Float64, 0x7fefffffffffffff))
+
+    eps(x::AbstractFloat) = isfinite(x) ? abs(x) >= floatmin(x) ? ldexp(eps(typeof(x)), exponent(x)) : nextfloat(zero(x)) : oftype(x, NaN)
     eps(::Type{Float16}) = $(bitcast(Float16, 0x1400))
     eps(::Type{Float32}) = $(bitcast(Float32, 0x34000000))
     eps(::Type{Float64}) = $(bitcast(Float64, 0x3cb0000000000000))
     eps() = eps(Float64)
 end
 
 """
-    realmin(T)
+    floatmin(T)
 
 The smallest in absolute value non-subnormal value representable by the given
 floating-point DataType `T`.
 """
-realmin(x::T) where {T<:AbstractFloat} = realmin(T)
+floatmin(x::T) where {T<:AbstractFloat} = floatmin(T)
 
 """
-    realmax(T)
+    floatmax(T)
 
 The highest finite value representable by the given floating-point DataType `T`.
 
 # Examples
 ```jldoctest
-julia> realmax(Float16)
+julia> floatmax(Float16)
 Float16(6.55e4)
 
-julia> realmax(Float32)
+julia> floatmax(Float32)
 3.4028235f38
 ```
 """
-realmax(x::T) where {T<:AbstractFloat} = realmax(T)
+floatmax(x::T) where {T<:AbstractFloat} = floatmax(T)
 
-realmin() = realmin(Float64)
-realmax() = realmax(Float64)
+floatmin() = floatmin(Float64)
+floatmax() = floatmax(Float64)
 
 """
     eps(::Type{T}) where T<:AbstractFloat

base/mpfr.jl

@@ -15,7 +15,7 @@ import
         log1p,
         eps, signbit, sin, cos, sincos, tan, sec, csc, cot, acos, asin, atan,
         cosh, sinh, tanh, sech, csch, coth, acosh, asinh, atanh,
-        cbrt, typemax, typemin, unsafe_trunc, realmin, realmax, rounding,
+        cbrt, typemax, typemin, unsafe_trunc, floatmin, floatmax, rounding,
         setrounding, maxintfloat, widen, significand, frexp, tryparse, iszero,
         isone, big, _string_n
 
@@ -881,8 +881,8 @@ end
 
 eps(::Type{BigFloat}) = nextfloat(BigFloat(1)) - BigFloat(1)
 
-realmin(::Type{BigFloat}) = nextfloat(zero(BigFloat))
-realmax(::Type{BigFloat}) = prevfloat(BigFloat(Inf))
+floatmin(::Type{BigFloat}) = nextfloat(zero(BigFloat))
+floatmax(::Type{BigFloat}) = prevfloat(BigFloat(Inf))
 
 """
     setprecision(f::Function, [T=BigFloat,] precision::Integer)

base/special/cbrt.jl

@@ -65,7 +65,7 @@ These implementations assume that NaNs, infinities and zeros have already been f
     k = significand_bits(T) - (8*sizeof(T) - 32)
 
     u = highword(x) & 0x7fff_ffff
-    if u >= Base.Math.highword(realmin(T))
+    if u >= Base.Math.highword(floatmin(T))
         v = div(u, UInt32(3)) + floor(UInt32, adj * exp2(k))
     else
         # subnormal

base/twiceprecision.jl

@@ -622,7 +622,7 @@ function _linspace(start::T, stop::T, len::Integer) where {T<:IEEEFloat}
     end
     # 2x calculations to get high precision endpoint matching while also
     # preventing overflow in ref_hi+(i-offset)*step_hi
-    m, k = prevfloat(realmax(T)), max(imin-1, len-imin)
+    m, k = prevfloat(floatmax(T)), max(imin-1, len-imin)
     step_hi_pre = clamp(step, max(-(m+ref)/k, (-m+ref)/k), min((m-ref)/k, (m+ref)/k))
     nb = nbitslen(T, len, imin)
     step_hi = truncbits(step_hi_pre, nb)

doc/src/base/base.md

@@ -162,8 +162,8 @@ Base.datatype_pointerfree
 ```@docs
 Base.typemin
 Base.typemax
-Base.realmin
-Base.realmax
+Base.floatmin
+Base.floatmax
 Base.maxintfloat
 Base.eps(::Type{<:AbstractFloat})
 Base.eps(::AbstractFloat)

stdlib/LinearAlgebra/src/givens.jl

@@ -61,9 +61,9 @@ function Base.copy(aG::Adjoint{<:Any,<:Givens})
 end
 Base.copy(aR::Adjoint{<:Any,Rotation{T}}) where {T} = Rotation{T}(reverse!([r' for r in aR.parent.rotations]))
 
-realmin2(::Type{Float32}) = reinterpret(Float32, 0x26000000)
-realmin2(::Type{Float64}) = reinterpret(Float64, 0x21a0000000000000)
-realmin2(::Type{T}) where {T} = (twopar = 2one(T); twopar^trunc(Integer,log(realmin(T)/eps(T))/log(twopar)/twopar))
+floatmin2(::Type{Float32}) = reinterpret(Float32, 0x26000000)
+floatmin2(::Type{Float64}) = reinterpret(Float64, 0x21a0000000000000)
+floatmin2(::Type{T}) where {T} = (twopar = 2one(T); twopar^trunc(Integer,log(floatmin(T)/eps(T))/log(twopar)/twopar))
 
 # derived from LAPACK's dlartg
 # Copyright:
@@ -78,8 +78,8 @@ function givensAlgorithm(f::T, g::T) where T<:AbstractFloat
     zeropar = T0(zero(T)) # must be dimensionless
 
     # need both dimensionful and dimensionless versions of these:
-    safmn2 = realmin2(T0)
-    safmn2u = realmin2(T)
+    safmn2 = floatmin2(T0)
+    safmn2u = floatmin2(T)
     safmx2 = one(T)/safmn2
     safmx2u = oneunit(T)/safmn2
 
@@ -152,9 +152,9 @@ function givensAlgorithm(f::Complex{T}, g::Complex{T}) where T<:AbstractFloat
     czero = complex(zeropar)
 
     abs1(ff) = max(abs(real(ff)), abs(imag(ff)))
-    safmin = realmin(T0)
-    safmn2 = realmin2(T0)
-    safmn2u = realmin2(T)
+    safmin = floatmin(T0)
+    safmn2 = floatmin2(T0)
+    safmn2u = floatmin2(T)
     safmx2 = one(T)/safmn2
     safmx2u = oneunit(T)/safmn2
     scalepar = max(abs1(f), abs1(g))

stdlib/LinearAlgebra/test/pinv.jl

@@ -160,24 +160,24 @@ end
 
     if eltya <: LinearAlgebra.BlasReal
         @testset "sub-normal numbers/vectors/matrices" begin
-            a = pinv(realmin(eltya)/100)
+            a = pinv(floatmin(eltya)/100)
             @test a ≈ 0.0
             # Complex subnormal
-            a = pinv(realmin(eltya)/100*(1+1im))
+            a = pinv(floatmin(eltya)/100*(1+1im))
             @test a ≈ 0.0
 
-            a = pinv([realmin(eltya); realmin(eltya)]/100)
+            a = pinv([floatmin(eltya); floatmin(eltya)]/100)
             @test a[1] ≈ 0.0
             @test a[2] ≈ 0.0
             # Complex subnormal
-            a = pinv([realmin(eltya); realmin(eltya)]/100*(1+1im))
+            a = pinv([floatmin(eltya); floatmin(eltya)]/100*(1+1im))
             @test a[1] ≈ 0.0
             @test a[2] ≈ 0.0
-            a = pinv(Diagonal([realmin(eltya); realmin(eltya)]/100))
+            a = pinv(Diagonal([floatmin(eltya); floatmin(eltya)]/100))
             @test a.diag[1] ≈ 0.0
             @test a.diag[2] ≈ 0.0
             # Complex subnormal
-            a = pinv(Diagonal([realmin(eltya); realmin(eltya)]/100*(1+1im)))
+            a = pinv(Diagonal([floatmin(eltya); floatmin(eltya)]/100*(1+1im)))
             @test a.diag[1] ≈ 0.0
             @test a.diag[2] ≈ 0.0
         end

stdlib/Statistics/test/runtests.jl

@@ -6,7 +6,7 @@ using Test: guardsrand
 @testset "middle" begin
     @test middle(3) === 3.0
     @test middle(2, 3) === 2.5
-    let x = ((realmax(1.0)/4)*3)
+    let x = ((floatmax(1.0)/4)*3)
         @test middle(x, x) === x
     end
     @test middle(1:8) === 4.5

test/grisu.jl

@@ -1278,14 +1278,14 @@ fill!(buffer,0)
 map(x->Grisu.Bignums.zero!(x),bignums)
 
 #Float16
-min_double = realmin(Float16)
+min_double = floatmin(Float16)
 status,len,point = Grisu.fastshortest(min_double,buffer)
 @test status
 @test "6104" == trimrep(buffer)
 @test -4 == point
 fill!(buffer,0)
 
-max_double = realmax(Float16)
+max_double = floatmax(Float16)
 status,len,point = Grisu.fastshortest(max_double,buffer)
 @test status
 @test "655" == trimrep(buffer)

test/math.jl

@@ -56,9 +56,9 @@ end
         end
 
         for (a,b) in [(T(12.8),T(0.8)),
-                      (prevfloat(realmin(T)), prevfloat(one(T), 2)),
-                      (prevfloat(realmin(T)), prevfloat(one(T), 2)),
-                      (prevfloat(realmin(T)), nextfloat(one(T), -2)),
+                      (prevfloat(floatmin(T)), prevfloat(one(T), 2)),
+                      (prevfloat(floatmin(T)), prevfloat(one(T), 2)),
+                      (prevfloat(floatmin(T)), nextfloat(one(T), -2)),
                       (nextfloat(zero(T), 3), T(0.75)),
                       (prevfloat(zero(T), -3), T(0.75)),
                       (nextfloat(zero(T)), T(0.5))]
@@ -94,8 +94,8 @@ end
             @test ldexp(T(-0.854375), 5) === T(-27.34)
             @test ldexp(T(1.0), typemax(Int)) === T(Inf)
             @test ldexp(T(1.0), typemin(Int)) === T(0.0)
-            @test ldexp(prevfloat(realmin(T)), typemax(Int)) === T(Inf)
-            @test ldexp(prevfloat(realmin(T)), typemin(Int)) === T(0.0)
+            @test ldexp(prevfloat(floatmin(T)), typemax(Int)) === T(Inf)
+            @test ldexp(prevfloat(floatmin(T)), typemin(Int)) === T(0.0)
 
             @test ldexp(T(0.0), Int128(0)) === T(0.0)
             @test ldexp(T(-0.0), Int128(0)) === T(-0.0)
@@ -104,8 +104,8 @@ end
             @test ldexp(T(-0.854375), Int128(5)) === T(-27.34)
             @test ldexp(T(1.0), typemax(Int128)) === T(Inf)
             @test ldexp(T(1.0), typemin(Int128)) === T(0.0)
-            @test ldexp(prevfloat(realmin(T)), typemax(Int128)) === T(Inf)
-            @test ldexp(prevfloat(realmin(T)), typemin(Int128)) === T(0.0)
+            @test ldexp(prevfloat(floatmin(T)), typemax(Int128)) === T(Inf)
+            @test ldexp(prevfloat(floatmin(T)), typemin(Int128)) === T(0.0)
 
             @test ldexp(T(0.0), BigInt(0)) === T(0.0)
             @test ldexp(T(-0.0), BigInt(0)) === T(-0.0)
@@ -114,18 +114,18 @@ end
             @test ldexp(T(-0.854375), BigInt(5)) === T(-27.34)
             @test ldexp(T(1.0), BigInt(typemax(Int128))) === T(Inf)
             @test ldexp(T(1.0), BigInt(typemin(Int128))) === T(0.0)
-            @test ldexp(prevfloat(realmin(T)), BigInt(typemax(Int128))) === T(Inf)
-            @test ldexp(prevfloat(realmin(T)), BigInt(typemin(Int128))) === T(0.0)
+            @test ldexp(prevfloat(floatmin(T)), BigInt(typemax(Int128))) === T(Inf)
+            @test ldexp(prevfloat(floatmin(T)), BigInt(typemin(Int128))) === T(0.0)
 
             # Test also against BigFloat reference. Needs to be exactly rounded.
-            @test ldexp(realmin(T), -1) == T(ldexp(big(realmin(T)), -1))
-            @test ldexp(realmin(T), -2) == T(ldexp(big(realmin(T)), -2))
-            @test ldexp(realmin(T)/2, 0) == T(ldexp(big(realmin(T)/2), 0))
-            @test ldexp(realmin(T)/3, 0) == T(ldexp(big(realmin(T)/3), 0))
-            @test ldexp(realmin(T)/3, -1) == T(ldexp(big(realmin(T)/3), -1))
-            @test ldexp(realmin(T)/3, 11) == T(ldexp(big(realmin(T)/3), 11))
-            @test ldexp(realmin(T)/11, -10) == T(ldexp(big(realmin(T)/11), -10))
-            @test ldexp(-realmin(T)/11, -10) == T(ldexp(big(-realmin(T)/11), -10))
+            @test ldexp(floatmin(T), -1) == T(ldexp(big(floatmin(T)), -1))
+            @test ldexp(floatmin(T), -2) == T(ldexp(big(floatmin(T)), -2))
+            @test ldexp(floatmin(T)/2, 0) == T(ldexp(big(floatmin(T)/2), 0))
+            @test ldexp(floatmin(T)/3, 0) == T(ldexp(big(floatmin(T)/3), 0))
+            @test ldexp(floatmin(T)/3, -1) == T(ldexp(big(floatmin(T)/3), -1))
+            @test ldexp(floatmin(T)/3, 11) == T(ldexp(big(floatmin(T)/3), 11))
+            @test ldexp(floatmin(T)/11, -10) == T(ldexp(big(floatmin(T)/11), -10))
+            @test ldexp(-floatmin(T)/11, -10) == T(ldexp(big(-floatmin(T)/11), -10))
         end
     end
 end

test/mpfr.jl

@@ -27,8 +27,8 @@ import Base.MPFR
     @test typeof(BigFloat(typemax(UInt64))) == BigFloat
     @test typeof(BigFloat(typemax(UInt128))) == BigFloat
 
-    @test typeof(BigFloat(realmax(Float32))) == BigFloat
-    @test typeof(BigFloat(realmax(Float64))) == BigFloat
+    @test typeof(BigFloat(floatmax(Float32))) == BigFloat
+    @test typeof(BigFloat(floatmax(Float64))) == BigFloat
 
     @test typeof(BigFloat(BigInt(1))) == BigFloat
     @test typeof(BigFloat(BigFloat(1))) == BigFloat
@@ -648,11 +648,11 @@ end
     @test BigFloat(1) + x == BigFloat(1) + prevfloat(x)
     @test eps(BigFloat) == eps(BigFloat(1))
 end
-@testset "realmin/realmax" begin
-    x = realmin(BigFloat)
+@testset "floatmin/floatmax" begin
+    x = floatmin(BigFloat)
     @test x > 0
     @test prevfloat(x) == 0
-    x = realmax(BigFloat)
+    x = floatmax(BigFloat)
     @test !isinf(x)
     @test isinf(nextfloat(x))
 end

test/numbers.jl

@@ -1585,10 +1585,10 @@ end
 @test eps(-float(0)) == 5e-324
 @test eps(nextfloat(float(0))) == 5e-324
 @test eps(-nextfloat(float(0))) == 5e-324
-@test eps(realmin()) == 5e-324
-@test eps(-realmin()) == 5e-324
-@test eps(realmax()) ==  2.0^(1023-52)
-@test eps(-realmax()) ==  2.0^(1023-52)
+@test eps(floatmin()) == 5e-324
+@test eps(-floatmin()) == 5e-324
+@test eps(floatmax()) ==  2.0^(1023-52)
+@test eps(-floatmax()) ==  2.0^(1023-52)
 @test isnan(eps(NaN))
 @test isnan(eps(Inf))
 @test isnan(eps(-Inf))
@@ -1782,12 +1782,12 @@ end
     @test 0xf.fP1 === 31.875
     @test -0x1.0p2 === -4.0
 end
-@testset "eps / realmin / realmax" begin
+@testset "eps / floatmin / floatmax" begin
     @test 0x1p-52 == eps()
     @test 0x1p-52 + 1 != 1
     @test 0x1p-53 + 1 == 1
-    @test 0x1p-1022 == realmin()
-    @test 0x1.fffffffffffffp1023 == realmax()
+    @test 0x1p-1022 == floatmin()
+    @test 0x1.fffffffffffffp1023 == floatmax()
     @test isinf(nextfloat(0x1.fffffffffffffp1023))
 end
 @testset "issue #1308" begin
@@ -1985,8 +1985,8 @@ for F in (Float16,Float32,Float64)
     @test reinterpret(Signed,one(F)) === signed(Base.exponent_one(F))
 end
 
-@test eps(realmax(Float64)) == 1.99584030953472e292
-@test eps(-realmax(Float64)) == 1.99584030953472e292
+@test eps(floatmax(Float64)) == 1.99584030953472e292
+@test eps(-floatmax(Float64)) == 1.99584030953472e292
 
 # modular multiplicative inverses of odd numbers via exponentiation