Merge pull request #22751 from JuliaLang/teh/domain_error

Make DomainError more informative

Author: timholy

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])
 
   * The operating system identification functions: `is_linux`, `is_bsd`, `is_apple`, `is_unix`,
     and `is_windows`, have been deprecated in favor of `Sys.islinux`, `Sys.isbsd`, `Sys.isapple`,

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

@@ -150,7 +150,7 @@ julia> signif(357.913, 4, 2)
 ```
 """
 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)
@@ -599,7 +599,7 @@ function base(b::Integer, n::BigInt, pad::Integer=1)
 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)