Make DomainError more informative

NEWS.md

@@ -157,8 +157,11 @@ Deprecated or removed
   * `fieldnames` now operates only on types. To get the names of fields in an object, use
     `fieldnames(typeof(x))` ([#22350]).
 
-  * `InexactError` now takes arguments: `InexactError(func::Symbol,
-    type, -3)` now prints as `ERROR: InexactError: func(type, -3)`. ([#20005])
+  * `InexactError` and `DomainError` now take
+    arguments. `InexactError(func::Symbol, type, -3)` now prints as
+    `ERROR: InexactError: func(type, -3)`, and `DomainError(val,
+    [msg])` prints as `ERROR: DomainError with val:\nmsg`. ([#20005],
+    [#22751])
 
 Julia v0.6.0 Release Notes
 ==========================

base/boot.jl

@@ -205,7 +205,6 @@ struct BoundsError        <: Exception
     BoundsError(a::ANY, i) = (@_noinline_meta; new(a,i))
 end
 struct DivideError        <: Exception end
-struct DomainError        <: Exception end
 struct OverflowError      <: Exception end
 struct OutOfMemoryError   <: Exception end
 struct ReadOnlyMemoryError<: Exception end
@@ -216,6 +215,12 @@ struct UndefVarError      <: Exception
     var::Symbol
 end
 struct InterruptException <: Exception end
+struct DomainError <: Exception
+    val
+    msg
+    DomainError(val::ANY) = (@_noinline_meta; new(val))
+    DomainError(val::ANY, msg::ANY) = (@_noinline_meta; new(val, msg))
+end
 mutable struct TypeError <: Exception
     func::Symbol
     context::AbstractString

base/combinatorics.jl

@@ -15,7 +15,7 @@ for n in 2:34
 end
 
 function factorial_lookup(n::Integer, table, lim)
-    n < 0 && throw(DomainError())
+    n < 0 && throw(DomainError(n, "`n` must not be negative."))
     n > lim && throw(OverflowError())
     n == 0 && return one(n)
     @inbounds f = table[n]
@@ -34,7 +34,7 @@ else
 end
 
 function gamma(n::Union{Int8,UInt8,Int16,UInt16,Int32,UInt32,Int64,UInt64})
-    n < 0 && throw(DomainError())
+    n < 0 && throw(DomainError(n, "`n` must not be negative."))
     n == 0 && return Inf
     n <= 2 && return 1.0
     n > 20 && return gamma(Float64(n))

base/dSFMT.jl

@@ -25,7 +25,7 @@ mutable struct DSFMT_state
     val::Vector{Int32}
 
     DSFMT_state(val::Vector{Int32} = zeros(Int32, JN32)) =
-        new(length(val) == JN32 ? val : throw(DomainError()))
+        new(length(val) == JN32 ? val : throw(DomainError(length(val), string("Expected length ", JN32, '.'))))
 end
 
 copy!(dst::DSFMT_state, src::DSFMT_state) = (copy!(dst.val, src.val); dst)

base/dates/rounding.jl

@@ -40,13 +40,13 @@ Takes the given `DateTime` and returns the number of milliseconds since the roun
 datetime2epochms(dt::DateTime) = value(dt) - DATETIMEEPOCH
 
 function Base.floor(dt::Date, p::Year)
-    value(p) < 1 && throw(DomainError())
+    value(p) < 1 && throw(DomainError(p))
     years = year(dt)
     return Date(years - mod(years, value(p)))
 end
 
 function Base.floor(dt::Date, p::Month)
-    value(p) < 1 && throw(DomainError())
+    value(p) < 1 && throw(DomainError(p))
     y, m = yearmonth(dt)
     months_since_epoch = y * 12 + m - 1
     month_offset = months_since_epoch - mod(months_since_epoch, value(p))
@@ -56,22 +56,22 @@ function Base.floor(dt::Date, p::Month)
 end
 
 function Base.floor(dt::Date, p::Week)
-    value(p) < 1 && throw(DomainError())
+    value(p) < 1 && throw(DomainError(p))
     days = value(dt) - WEEKEPOCH
     days = days - mod(days, value(Day(p)))
     return Date(UTD(WEEKEPOCH + Int64(days)))
 end
 
 function Base.floor(dt::Date, p::Day)
-    value(p) < 1 && throw(DomainError())
+    value(p) < 1 && throw(DomainError(p))
     days = date2epochdays(dt)
     return epochdays2date(days - mod(days, value(p)))
 end
 
 Base.floor(dt::DateTime, p::DatePeriod) = DateTime(Base.floor(Date(dt), p))
 
 function Base.floor(dt::DateTime, p::TimePeriod)
-    value(p) < 1 && throw(DomainError())
+    value(p) < 1 && throw(DomainError(p))
     milliseconds = datetime2epochms(dt)
     return epochms2datetime(milliseconds - mod(milliseconds, value(Millisecond(p))))
 end
@@ -166,7 +166,7 @@ Base.round(dt::TimeType, p::Period, r::RoundingMode{:Up}) = Base.ceil(dt, p)
 # No implementation of other `RoundingMode`s: rounding to nearest "even" is skipped because
 # "even" is not defined for Period; rounding toward/away from zero is skipped because ISO
 # 8601's year 0000 is not really "zero".
-Base.round(::TimeType, ::Period, ::RoundingMode) = throw(DomainError())
+Base.round(::TimeType, p::Period, ::RoundingMode) = throw(DomainError(p))
 
 # Default to RoundNearestTiesUp.
 Base.round(dt::TimeType, p::Period) = Base.round(dt, p, RoundNearestTiesUp)

base/deprecated.jl

@@ -1561,6 +1561,12 @@ function InexactError()
     InexactError(:none, Any, nothing)
 end
 
+# PR #22751
+function DomainError()
+    depwarn("DomainError now supports arguments, use `DomainError(value)` or `DomainError(value, msg)` instead.", :DomainError)
+    DomainError(nothing)
+end
+
 # PR #22703
 @deprecate Bidiagonal(dv::AbstractVector, ev::AbstractVector, isupper::Bool) Bidiagonal(dv, ev, ifelse(isupper, :U, :L))
 @deprecate Bidiagonal(dv::AbstractVector, ev::AbstractVector, uplo::Char) Bidiagonal(dv, ev, ifelse(uplo == 'U', :U, :L))

base/docs/helpdb/Base.jl

@@ -1402,14 +1402,15 @@ The highest value representable by the given (real) numeric `DataType`.
 typemax
 
 """
-    DomainError()
+    DomainError(val)
+    DomainError(val, msg)
 
-The arguments to a function or constructor are outside the valid domain.
+The argument `val` to a function or constructor is outside the valid domain.
 
 # Examples
 ```jldoctest
 julia> sqrt(-1)
-ERROR: DomainError:
+ERROR: DomainError with -1:
 sqrt will only return a complex result if called with a complex argument. Try sqrt(complex(x)).
 Stacktrace:
  [1] sqrt(::Int64) at ./math.jl:443

base/float.jl

@@ -443,17 +443,18 @@ for op in (:<, :<=, :isless)
 end
 
 function cmp(x::AbstractFloat, y::AbstractFloat)
-    (isnan(x) || isnan(y)) && throw(DomainError())
+    isnan(x) && throw(DomainError(x, "`x` cannot be NaN."))
+    isnan(y) && throw(DomainError(y, "`y` cannot be NaN."))
     ifelse(x<y, -1, ifelse(x>y, 1, 0))
 end
 
 function cmp(x::Real, y::AbstractFloat)
-    isnan(y) && throw(DomainError())
+    isnan(y) && throw(DomainError(y, "`y` cannot be NaN."))
     ifelse(x<y, -1, ifelse(x>y, 1, 0))
 end
 
 function cmp(x::AbstractFloat, y::Real)
-    isnan(x) && throw(DomainError())
+    isnan(x) && throw(DomainError(x, "`x` cannot be NaN."))
     ifelse(x<y, -1, ifelse(x>y, 1, 0))
 end
 

base/floatfuncs.jl

@@ -132,7 +132,7 @@ function _signif_og(x, digits, base)
 end
 
 function signif(x::Real, digits::Integer, base::Integer=10)
-    digits < 1 && throw(DomainError())
+    digits < 1 && throw(DomainError(digits, "`digits` cannot be less than 1."))
 
     x = float(x)
     (x == 0 || !isfinite(x)) && return x

base/gmp.jl

@@ -403,7 +403,7 @@ function invmod(x::BigInt, y::BigInt)
         return z
     end
     if (y==0 || MPZ.invert!(z, x, ya) == 0)
-        throw(DomainError())
+        throw(DomainError(y))
     end
     # GMP always returns a positive inverse; we instead want to
     # normalize such that div(z, y) == 0, i.e. we want a negative z
@@ -474,15 +474,15 @@ cmp(x::BigInt, y::CulongMax) = MPZ.cmp_ui(x, y)
 cmp(x::BigInt, y::Integer) = cmp(x, big(y))
 cmp(x::Integer, y::BigInt) = -cmp(y, x)
 
-cmp(x::BigInt, y::CdoubleMax) = isnan(y) ? throw(DomainError()) : MPZ.cmp_d(x, y)
+cmp(x::BigInt, y::CdoubleMax) = isnan(y) ? throw(DomainError(y, "`y` cannot be NaN.")) : MPZ.cmp_d(x, y)
 cmp(x::CdoubleMax, y::BigInt) = -cmp(y, x)
 
 isqrt(x::BigInt) = MPZ.sqrt(x)
 
 ^(x::BigInt, y::Culong) = MPZ.pow_ui(x, y)
 
 function bigint_pow(x::BigInt, y::Integer)
-    if y<0; throw(DomainError()); end
+    if y<0; throw(DomainError(y, "`y` cannot be negative.")); end
     if x== 1; return x; end
     if x==-1; return isodd(y) ? x : -x; end
     if y>typemax(Culong)
@@ -607,7 +607,7 @@ function base(b::Integer, n::BigInt, pad::Integer)
 end
 
 function ndigits0zpb(x::BigInt, b::Integer)
-    b < 2 && throw(DomainError())
+    b < 2 && throw(DomainError(b, "`b` cannot be less than 2."))
     x.size == 0 && return 0 # for consistency with other ndigits0z methods
     if ispow2(b) && 2 <= b <= 62 # GMP assumes b is in this range
         MPZ.sizeinbase(x, b)

base/intfuncs.jl

@@ -147,7 +147,8 @@ julia> invmod(5,6)
 """
 function invmod(n::T, m::T) where T<:Integer
     g, x, y = gcdx(n, m)
-    (g != 1 || m == 0) && throw(DomainError())
+    g != 1 && throw(DomainError((n, m), "Greatest common divisor is 1."))
+    m == 0 && throw(DomainError(m, "`m` must not be 0."))
     # Note that m might be negative here.
     # For unsigned T, x might be close to typemax; add m to force a wrap-around.
     r = mod(x + m, m)
@@ -159,6 +160,10 @@ invmod(n::Integer, m::Integer) = invmod(promote(n,m)...)
 # ^ for any x supporting *
 to_power_type(x::Number) = oftype(x*x, x)
 to_power_type(x) = x
+@noinline throw_domerr_powbysq(p) = throw(DomainError(p,
+    string("Cannot raise an integer x to a negative power ", p, '.',
+           "\nMake x a float by adding a zero decimal (e.g., 2.0^$p instead ",
+           "of 2^$p), or write 1/x^$(-p), float(x)^$p, or (x//1)^$p")))
 function power_by_squaring(x_, p::Integer)
     x = to_power_type(x_)
     if p == 1
@@ -170,7 +175,7 @@ function power_by_squaring(x_, p::Integer)
     elseif p < 0
         x == 1 && return copy(x)
         x == -1 && return iseven(p) ? one(x) : copy(x)
-        throw(DomainError())
+        throw_domerr_powbysq(p)
     end
     t = trailing_zeros(p) + 1
     p >>= t
@@ -190,7 +195,7 @@ function power_by_squaring(x_, p::Integer)
 end
 power_by_squaring(x::Bool, p::Unsigned) = ((p==0) | x)
 function power_by_squaring(x::Bool, p::Integer)
-    p < 0 && !x && throw(DomainError())
+    p < 0 && !x && throw_domerr_powbysq(p)
     return (p==0) | x
 end
 
@@ -348,7 +353,8 @@ julia> nextpow(4, 16)
 See also [`prevpow`](@ref).
 """
 function nextpow(a::Real, x::Real)
-    (a <= 1 || x <= 0) && throw(DomainError())
+    a <= 1 && throw(DomainError(a, "`a` must be greater than 1."))
+    x <= 0 && throw(DomainError(x, "`x` must be positive."))
     x <= 1 && return one(a)
     n = ceil(Integer,log(a, x))
     p = a^(n-1)
@@ -379,7 +385,8 @@ julia> prevpow(4, 16)
 See also [`nextpow`](@ref).
 """
 function prevpow(a::Real, x::Real)
-    (a <= 1 || x < 1) && throw(DomainError())
+    a <= 1 && throw(DomainError(a, "`a` must be greater than 1."))
+    x < 1 && throw(DomainError(x, "`x` must be ≥ 1."))
     n = floor(Integer,log(a, x))
     p = a^(n+1)
     p <= x ? p : a^n
@@ -498,7 +505,7 @@ function ndigits0z(x::Integer, b::Integer)
     elseif b > 1
         ndigits0zpb(x, b)
     else
-        throw(DomainError())
+        throw(DomainError(b, "The base `b` must not be in `[-1, 0, 1]`."))
     end
 end
 
@@ -582,7 +589,7 @@ const base62digits = ['0':'9';'A':'Z';'a':'z']
 
 
 function base(b::Int, x::Integer, pad::Int, neg::Bool)
-    (x >= 0) | (b < 0) || throw(DomainError())
+    (x >= 0) | (b < 0) || throw(DomainError(x, "For negative `x`, `b` must be negative."))
     2 <= abs(b) <= 62 || throw(ArgumentError("base must satisfy 2 ≤ abs(base) ≤ 62, got $b"))
     digits = abs(b) <= 36 ? base36digits : base62digits
     i = neg + ndigits(x, b, pad)
@@ -800,7 +807,7 @@ function isqrt(x::Union{Int64,UInt64,Int128,UInt128})
 end
 
 function factorial(n::Integer)
-    n < 0 && throw(DomainError())
+    n < 0 && throw(DomainError(n, "`n` must be nonnegative."))
     local f::typeof(n*n), i::typeof(n*n)
     f = 1
     for i = 2:n

base/libuv.jl

@@ -7,14 +7,14 @@ include(string(length(Core.ARGS) >= 2 ? Core.ARGS[2] : "", "uv_constants.jl"))
 # convert UV handle data to julia object, checking for null
 function uv_sizeof_handle(handle)
     if !(UV_UNKNOWN_HANDLE < handle < UV_HANDLE_TYPE_MAX)
-        throw(DomainError())
+        throw(DomainError(handle))
     end
     ccall(:uv_handle_size,Csize_t,(Int32,),handle)
 end
 
 function uv_sizeof_req(req)
     if !(UV_UNKNOWN_REQ < req < UV_REQ_TYPE_MAX)
-        throw(DomainError())
+        throw(DomainError(req))
     end
     ccall(:uv_req_size,Csize_t,(Int32,),req)
 end

base/linalg/eigen.jl

@@ -226,7 +226,8 @@ julia> A = [0 im; -1 0]
  -1+0im  0+0im
 
 julia> eigmax(A)
-ERROR: DomainError:
+ERROR: DomainError with Complex{Int64}[0+0im 0+1im; -1+0im 0+0im]:
+`A` cannot have complex eigenvalues.
 Stacktrace:
  [1] #eigmax#52(::Bool, ::Bool, ::Function, ::Array{Complex{Int64},2}) at ./linalg/eigen.jl:238
  [2] eigmax(::Array{Complex{Int64},2}) at ./linalg/eigen.jl:236
@@ -235,7 +236,7 @@ Stacktrace:
 function eigmax(A::Union{Number, StridedMatrix}; permute::Bool=true, scale::Bool=true)
     v = eigvals(A, permute = permute, scale = scale)
     if eltype(v)<:Complex
-        throw(DomainError())
+        throw(DomainError(A, "`A` cannot have complex eigenvalues."))
     end
     maximum(v)
 end
@@ -268,7 +269,8 @@ julia> A = [0 im; -1 0]
  -1+0im  0+0im
 
 julia> eigmin(A)
-ERROR: DomainError:
+ERROR: DomainError with Complex{Int64}[0+0im 0+1im; -1+0im 0+0im]:
+`A` cannot have complex eigenvalues.
 Stacktrace:
  [1] #eigmin#53(::Bool, ::Bool, ::Function, ::Array{Complex{Int64},2}) at ./linalg/eigen.jl:280
  [2] eigmin(::Array{Complex{Int64},2}) at ./linalg/eigen.jl:278
@@ -277,7 +279,7 @@ Stacktrace:
 function eigmin(A::Union{Number, StridedMatrix}; permute::Bool=true, scale::Bool=true)
     v = eigvals(A, permute = permute, scale = scale)
     if eltype(v)<:Complex
-        throw(DomainError())
+        throw(DomainError(A, "`A` cannot have complex eigenvalues."))
     end
     minimum(v)
 end