From ce62f348b10a257490a89835774d00a188be5646 Mon Sep 17 00:00:00 2001 From: Valentin Churavy Date: Thu, 23 Jun 2016 17:21:26 -0400 Subject: [PATCH] Fix doctest code-blocks in documentation cb8aa0b - fix most doctests in the manual that changed due to backtraces. cd3797e - fix stdlib doctests 1892f72 - fix doctests in devdocs d9495c7 - resolve Warning mismatch by renaming functions 83ef854 - convert superflous doctest to code-block 78f6d70 - Fix example about typemax and typemin Due to the changes in 4706184 tuples are now printed compact. Thus to demonstrate the point in this example we have to execute the examples independently. c03e6e0 - fixup linenumbers 35a31bb - start->first Ref #15753 --- base/docs/helpdb/Base.jl | 6 +- doc/devdocs/reflection.rst | 9 ++- doc/devdocs/types.rst | 74 +++++++++--------- doc/manual/arrays.rst | 8 +- doc/manual/complex-and-rational-numbers.rst | 4 +- doc/manual/constructors.rst | 29 +++++-- doc/manual/control-flow.rst | 67 +++++++++------- doc/manual/conversion-and-promotion.rst | 17 ++-- doc/manual/documentation.rst | 2 +- doc/manual/functions.rst | 4 +- .../integers-and-floating-point-numbers.rst | 21 +++-- doc/manual/mathematical-operations.rst | 20 ++--- doc/manual/metaprogramming.rst | 9 ++- doc/manual/methods.rst | 36 +++++---- doc/manual/performance-tips.rst | 2 +- doc/manual/stacktraces.rst | 78 ++++++++++--------- doc/manual/strings.rst | 14 ++-- doc/manual/types.rst | 27 +++++-- doc/manual/variables-and-scoping.rst | 5 +- doc/manual/variables.rst | 2 + doc/stdlib/base.rst | 3 +- doc/stdlib/collections.rst | 13 +--- 22 files changed, 270 insertions(+), 180 deletions(-) diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl index 41be192c95955..0432558ad3bfe 100644 --- a/base/docs/helpdb/Base.jl +++ b/base/docs/helpdb/Base.jl @@ -5643,7 +5643,8 @@ julia> deleteat!([6, 5, 4, 3, 2, 1], 1:2:5) julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:543 + in deleteat!(::Array{Int64,1}, ::Tuple{Int64,Int64}) at ./array.jl:565 + in eval(::Module, ::Any) at ./boot.jl:237 ``` """ deleteat!(collection, itr) @@ -8311,7 +8312,8 @@ julia> convert(Int, 3.0) julia> convert(Int, 3.5) ERROR: InexactError() - in convert at int.jl:209 + in convert(::Type{Int64}, ::Float64) at ./int.jl:229 + in eval(::Module, ::Any) at ./boot.jl:237 ``` If `T` is a [`AbstractFloat`](:obj:`AbstractFloat`) or [`Rational`](:obj:`Rational`) type, diff --git a/doc/devdocs/reflection.rst b/doc/devdocs/reflection.rst index 2f3ace38417db..a9ec23394e1ff 100644 --- a/doc/devdocs/reflection.rst +++ b/doc/devdocs/reflection.rst @@ -104,9 +104,14 @@ variable assignments: .. doctest:: julia> expand( :(f() = 1) ) - :($(Expr(:method, :f, :((top(svec))((top(apply_type))(Tuple),(top(svec))())), AST(:($(Expr(:lambda, Any[], Any[Any[],Any[],0,Any[]], :(begin # none, line 1: + :(begin + $(Expr(:method, :f)) + $(Expr(:method, :f, :((top(svec))((top(apply_type))(Tuple,((top(getfield))(Core,:Typeof))(f)),(top(svec))())), LambdaInfo for anonymous + :(begin # none, line 1: return 1 - end))))), false))) + end), false)) + return f + end) .. rubric:: Intermediate and compiled representations diff --git a/doc/devdocs/types.rst b/doc/devdocs/types.rst index 9b66337475400..286ff63fbed02 100644 --- a/doc/devdocs/types.rst +++ b/doc/devdocs/types.rst @@ -130,9 +130,9 @@ one can extract the underlying :obj:`TypeVar`: .. testcode:: s g{S<:Integer}(x::S) = 0 - m = start(methods(g)) + m = first(methods(g)) p = m.sig.parameters - tv = p[1] + tv = p[2] dump(tv) .. testoutput:: s @@ -140,7 +140,7 @@ one can extract the underlying :obj:`TypeVar`: TypeVar name: Symbol S lb: Union{} - ub: Integer::DataType <: Real + ub: Integer <: Real bound: Bool true Here ``ub`` is ``Integer``, as specified in the function definition. @@ -160,27 +160,27 @@ parameters. For example: julia> h3{T<:Real}(A::Array{T}, b::T) = 1 h3 (generic function with 1 method) - julia> p1 = start(methods(h1)).sig.parameters - svec(Array{T,N},Real) + julia> p1 = first(methods(h1)).sig.parameters + svec(#h1,Array{T,N},Real) - julia> p2 = start(methods(h2)).sig.parameters - svec(Array{T,N},T<:Real) + julia> p2 = first(methods(h2)).sig.parameters + svec(#h2,Array{T,N},T<:Real) - julia> p3 = start(methods(h3)).sig.parameters - svec(Array{T<:Real,N},T<:Real) + julia> p3 = first(methods(h3)).sig.parameters + svec(#h3,Array{T<:Real,N},T<:Real) - julia> dump(p1[1].parameters[1]) + julia> dump(p1[2].parameters[1]) TypeVar name: Symbol T lb: Union{} - ub: Any::DataType <: Any + ub: Any <: Any bound: Bool false - julia> dump(p3[1].parameters[1]) + julia> dump(p3[2].parameters[1]) TypeVar name: Symbol T lb: Union{} - ub: Real::DataType <: Number + ub: Real <: Number bound: Bool true Note that ``p2`` shows two objects called ``T``, but only one of them @@ -194,7 +194,7 @@ One can construct :obj:`TypeVar`\s manually: .. doctest:: julia> TypeVar(:V, Signed, Real, false) - Signed<:V<:Real + V<:Real There are convenience versions that allow you to omit any of these arguments except the ``name`` symbol. @@ -215,20 +215,21 @@ a lot about how Julia does dispatch: julia> methods(candid) # 1 method for generic function "candid": - candid{T}(A::Array{T,N}, x::T) at none:1 + candid{T}(A::Array{T,N<:Any}, x::T) at none:1 julia> methods(sneaky) # 1 method for generic function "sneaky": - sneaky{T}(A::Array{T,N}, x::T) at none:1 + sneaky{T}(A::Array{T,N<:Any}, x::T<:Any) at none:1 These therefore print identically, but they have very different behavior: .. doctest:: julia> candid([1],3.2) - ERROR: MethodError: `candid` has no method matching candid(::Array{Int64,1}, ::Float64) + ERROR: MethodError: no method matching candid(::Array{Int64,1}, ::Float64) Closest candidates are: candid{T}(::Array{T,N}, !Matched::T) + in eval(::Module, ::Any) at ./boot.jl:237 julia> sneaky([1],3.2) 1 @@ -244,11 +245,11 @@ bound :obj:`TypeVar` objects with a hash (``#T`` instead of ``T``): .. doctest:: - julia> jl_(start(methods(candid))) - Method(sig=Tuple{Array{#T<:Any, N<:Any}, #T<:Any}, va=false, isstaged=false, tvars=#T<:Any, func=#, invokes=nothing, next=nothing) + julia> jl_(first(methods(candid))) + Method(sig=Tuple{Main.#candid, Array{#T<:Any, N<:Any}, #T<:Any}, va=false, isstaged=false, tvars=#T<:Any, func=Main.candid(?), invokes=nothing, next=nothing) - julia> jl_(start(methods(sneaky))) - Method(sig=Tuple{Array{#T<:Any, N<:Any}, T<:Any}, va=false, isstaged=false, tvars=#T<:Any, func=#, invokes=nothing, next=nothing) + julia> jl_(first(methods(sneaky))) + Method(sig=Tuple{Main.#sneaky, Array{#T<:Any, N<:Any}, T<:Any}, va=false, isstaged=false, tvars=#T<:Any, func=Main.sneaky(?), invokes=nothing, next=nothing) Even though both print as ``T``, in ``sneaky`` the second ``T`` is not bound, and hence it isn't constrained to be the same type as the @@ -320,8 +321,17 @@ the type, which is an object of type :obj:`TypeName`: cache: SimpleVector length: Int64 135 linearcache: SimpleVector - length: Int64 18 - uid: Int64 37 + length: Int64 60 + uid: Int64 43 + mt: MethodTable + name: Symbol Array + defs: Void nothing + cache: Void nothing + cache_arg1: Void nothing + cache_targ: Void nothing + max_args: Int64 0 + kwsorter: #undef + module: Module Core In this case, the relevant field is ``primary``, which holds a reference to the "primary" instance of the type:: @@ -357,20 +367,10 @@ type: MyType{Float32,5} julia> MyType.name.cache - svec(MyType{Float32,5},MyType{Int64,2},Evaluation succeeded, but an error occurred while showing value of type SimpleVector: - ERROR: UndefRefError: access to undefined reference - in getindex at ./essentials.jl:211 - in show_delim_array at show.jl:229 - in show at show.jl:257 - in anonymous at show.jl:1278 - in with_output_limit at ./show.jl:1255 - in showlimited at show.jl:1277 - in display at multimedia.jl:120 - [inlined code] from multimedia.jl:151 - in display at multimedia.jl:162 - -(The error is triggered because the cache is pre-allocated to have -length 8, but only the first two entries are populated.) + svec(MyType{Float32,5},MyType{Int64,2},#undef,#undef,#undef,#undef,#undef,#undef) + +(The cache is pre-allocated to have length 8, but only the first two entries +are populated.) Consequently, when you instantiate a parametric type, each concrete type gets saved in a type-cache. However, instances with :obj:`TypeVar` parameters are not cached. diff --git a/doc/manual/arrays.rst b/doc/manual/arrays.rst index 007483ae3c8db..0f667f4baeb6c 100644 --- a/doc/manual/arrays.rst +++ b/doc/manual/arrays.rst @@ -497,9 +497,9 @@ the name of the function to vectorize. Here is a simple example: julia> methods(square) # 4 methods for generic function "square": - square{T<:Number}(::AbstractArray{T<:Number,1}) at operators.jl:374 - square{T<:Number}(::AbstractArray{T<:Number,2}) at operators.jl:375 - square{T<:Number}(::AbstractArray{T<:Number,N}) at operators.jl:377 + square{T<:Number}(x::AbstractArray{T,1}) at operators.jl:... + square{T<:Number}(x::AbstractArray{T,2}) at operators.jl:... + square{T<:Number}(x::AbstractArray{T,N<:Any}) at operators.jl:... square(x) at none:1 julia> square([1 2 4; 5 6 7]) @@ -631,7 +631,7 @@ stride parameters. 0.507762 0.573567 0.220124 0.165816 0.211049 0.433277 0.539476 julia> b = sub(a, 2:2:8,2:2:4) - 4×2 SubArray{Float64,2,Array{Float64,2},Tuple{StepRange{Int64,Int64},StepRange{Int64,Int64}},1}: + 4×2 SubArray{Float64,2,Array{Float64,2},Tuple{StepRange{Int64,Int64},StepRange{Int64,Int64}},false}: 0.537192 0.996234 0.736979 0.228787 0.991511 0.74485 diff --git a/doc/manual/complex-and-rational-numbers.rst b/doc/manual/complex-and-rational-numbers.rst index 87712d917bb92..dcf49c8a8f0ee 100644 --- a/doc/manual/complex-and-rational-numbers.rst +++ b/doc/manual/complex-and-rational-numbers.rst @@ -159,7 +159,8 @@ versus ``-1 + 0im`` even though ``-1 == -1 + 0im``: julia> sqrt(-1) ERROR: DomainError: sqrt will only return a complex result if called with a complex argument. Try sqrt(complex(x)). - in sqrt at math.jl:146 + in sqrt(::Int64) at ./math.jl:146 + in eval(::Module, ::Any) at ./boot.jl:237 julia> sqrt(-1 + 0im) 0.0 + 1.0im @@ -305,6 +306,7 @@ Trying to construct a :const:`NaN` rational value, however, is not: ERROR: ArgumentError: invalid rational: zero(Int64)//zero(Int64) in Rational{Int64}(::Int64, ::Int64) at ./rational.jl:8 in //(::Int64, ::Int64) at ./rational.jl:22 + in eval(::Module, ::Any) at ./boot.jl:237 As usual, the promotion system makes interactions with other numeric types effortless: diff --git a/doc/manual/constructors.rst b/doc/manual/constructors.rst index 9207a19c42a7b..81661e656b18b 100644 --- a/doc/manual/constructors.rst +++ b/doc/manual/constructors.rst @@ -121,7 +121,8 @@ Now ``OrderedPair`` objects can only be constructed such that julia> OrderedPair(2,1) ERROR: out of order - in call at none:5 + in OrderedPair(::Int64, ::Int64) at ./none:5 + in eval(::Module, ::Any) at ./boot.jl:237 You can still reach in and directly change the field values to violate this invariant, but messing around with an object's internals uninvited is @@ -266,6 +267,7 @@ access to an uninitialized reference is an immediate error: julia> z.xx ERROR: UndefRefError: access to undefined reference + in eval(::Module, ::Any) at ./boot.jl:237 This avoids the need to continually check for ``null`` values. However, not all object fields are references. Julia considers some @@ -323,9 +325,14 @@ types of the arguments given to the constructor. Here are some examples: Point{Float64}(1.0,2.5) julia> Point(1,2.5) - ERROR: MethodError: `convert` has no method matching convert(::Type{Point{T<:Real}}, ::Int64, ::Float64) - This may have arisen from a call to the constructor Point{T<:Real}(...), - since type constructors fall back to convert methods. + ERROR: MethodError: no method matching Point{T<:Real}(::Int64, ::Float64) + Closest candidates are: + (!Matched::Type{BoundsError})(::ANY, ::ANY) + (!Matched::Type{TypeError})(::Any, ::Any, !Matched::Any, !Matched::Any) + (!Matched::Type{TypeConstructor})(::ANY, ::ANY) + ... + in eval(::Module, ::Any) at ./boot.jl:237 + ## explicit T ## @@ -334,7 +341,9 @@ types of the arguments given to the constructor. Here are some examples: julia> Point{Int64}(1.0,2.5) ERROR: InexactError() - in call at none:2 + [inlined code] from ./int.jl:229 + in Point{Int64}(::Float64, ::Float64) at ./none:2 + in eval(::Module, ::Any) at ./boot.jl:237 julia> Point{Float64}(1.0,2.5) Point{Float64}(1.0,2.5) @@ -419,9 +428,13 @@ However, other similar calls still don't work: .. doctest:: julia> Point(1.5,2) - ERROR: MethodError: `convert` has no method matching convert(::Type{Point{T<:Real}}, ::Float64, ::Int64) - This may have arisen from a call to the constructor Point{T<:Real}(...), - since type constructors fall back to convert methods. + ERROR: MethodError: no method matching Point{T<:Real}(::Float64, ::Int64) + Closest candidates are: + (!Matched::Type{BoundsError})(::ANY, ::ANY) + (!Matched::Type{TypeError})(::Any, ::Any, !Matched::Any, !Matched::Any) + (!Matched::Type{TypeConstructor})(::ANY, ::ANY) + ... + in eval(::Module, ::Any) at ./boot.jl:237 For a much more general way of making all such calls work sensibly, see :ref:`man-conversion-and-promotion`. At the risk diff --git a/doc/manual/control-flow.rst b/doc/manual/control-flow.rst index 25486060dbbb7..28d86231463a1 100644 --- a/doc/manual/control-flow.rst +++ b/doc/manual/control-flow.rst @@ -128,7 +128,7 @@ So, we could have defined the ``test`` function above as .. doctest:: - julia> function test(x,y) + julia> function test1(x,y) if x < y relation = "less than" elseif x == y @@ -138,7 +138,7 @@ So, we could have defined the ``test`` function above as end println("x is ", relation, " y.") end - test (generic function with 1 method) + test1 (generic function with 1 method) The variable ``relation`` is declared inside the ``if`` block, but used outside. However, when depending on this behavior, make sure all possible @@ -147,7 +147,7 @@ the above function results in a runtime error .. doctest:: - julia> function test(x,y) + julia> function test2(x,y) if x < y relation = "less than" elseif x == y @@ -155,14 +155,15 @@ the above function results in a runtime error end println("x is ", relation, " y.") end - test (generic function with 1 method) + test2 (generic function with 1 method) - julia> test(1,2) + julia> test2(1,2) x is less than y. - julia> test(2,1) + julia> test2(2,1) ERROR: UndefVarError: relation not defined - in test at none:7 + in test2(::Int64, ::Int64) at ./none:7 + in eval(::Module, ::Any) at ./boot.jl:237 ``if`` blocks also return a value, which may seem unintuitive to users coming from many other languages. This value is simply the return value @@ -193,6 +194,7 @@ conditional expression is anything but ``true`` or ``false``: println("true") end ERROR: TypeError: non-boolean (Int64) used in boolean context + in eval(::Module, ::Any) at ./boot.jl:237 This error indicates that the conditional was of the wrong type: :obj:`Int64` rather than the required :obj:`Bool`. @@ -236,17 +238,17 @@ together: .. doctest:: - julia> test(x, y) = println(x < y ? "x is less than y" : + julia> test4(x, y) = println(x < y ? "x is less than y" : x > y ? "x is greater than y" : "x is equal to y") - test (generic function with 1 method) + test4 (generic function with 1 method) - julia> test(1, 2) + julia> test4(1, 2) x is less than y - julia> test(2, 1) + julia> test4(2, 1) x is greater than y - julia> test(1, 1) + julia> test4(1, 1) x is equal to y To facilitate chaining, the operator associates from right to left. @@ -365,7 +367,8 @@ For example, a recursive factorial routine could be defined like this: julia> fact(-1) ERROR: n must be non-negative - in fact at none:2 + in fact(::Int64) at ./none:2 + in eval(::Module, ::Any) at ./boot.jl:237 Boolean operations *without* short-circuit evaluation can be done with the @@ -394,6 +397,7 @@ except for the last entry in a conditional chain is an error: julia> 1 && true ERROR: TypeError: non-boolean (Int64) used in boolean context + in eval(::Module, ::Any) at ./boot.jl:237 On the other hand, any type of expression can be used at the end of a conditional chain. It will be evaluated and returned depending on the preceding conditionals: @@ -478,6 +482,7 @@ different variable name to test this: julia> j ERROR: UndefVarError: j not defined + in eval(::Module, ::Any) at ./boot.jl:237 See :ref:`man-variables-and-scoping` for a detailed explanation of variable scope and how it works in Julia. @@ -661,7 +666,8 @@ negative real value: julia> sqrt(-1) ERROR: DomainError: sqrt will only return a complex result if called with a complex argument. Try sqrt(complex(x)). - in sqrt at math.jl:146 + in sqrt(::Int64) at ./math.jl:146 + in eval(::Module, ::Any) at ./boot.jl:237 You may define your own exceptions in the following way: @@ -678,15 +684,16 @@ if the argument is negative: .. doctest:: - julia> f(x) = x>=0 ? exp(-x) : throw(DomainError()) - f (generic function with 1 method) + julia> g(x) = x>=0 ? exp(-x) : throw(DomainError()) + g (generic function with 1 method) - julia> f(1) + julia> g(1) 0.36787944117144233 - julia> f(-1) + julia> g(-1) ERROR: DomainError: - in f at none:1 + in g(::Int64) at ./none:1 + in eval(::Module, ::Any) at ./boot.jl:237 Note that :exc:`DomainError` without parentheses is not an exception, but a type of exception. It needs to be called to obtain an :exc:`Exception` object: @@ -706,6 +713,7 @@ error reporting: julia> throw(UndefVarError(:x)) ERROR: UndefVarError: x not defined + in eval(::Module, ::Any) at ./boot.jl:237 This mechanism can be implemented easily by custom exception types following the way :exc:`UndefVarError` is written: @@ -737,7 +745,8 @@ the :func:`sqrt` function that raises an error if its argument is negative: julia> fussy_sqrt(-1) ERROR: negative x not allowed - in fussy_sqrt at none:1 + in fussy_sqrt(::Int64) at ./none:1 + in eval(::Module, ::Any) at ./boot.jl:237 If ``fussy_sqrt`` is called with a negative value from another function, instead of trying to continue execution of the calling function, it @@ -762,7 +771,9 @@ session: julia> verbose_fussy_sqrt(-1) before fussy_sqrt ERROR: negative x not allowed - in verbose_fussy_sqrt at none:3 + [inlined code] from ./none:1 + in verbose_fussy_sqrt(::Int64) at ./none:3 + in eval(::Module, ::Any) at ./boot.jl:237 Warnings and informational messages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -783,7 +794,8 @@ execution.: julia> error("Hi"); 1+1 ERROR: Hi - in error at ./error.jl:21 + in error(::ASCIIString) at ./error.jl:21 + in eval(::Module, ::Any) at ./boot.jl:237 The ``try/catch`` statement @@ -796,17 +808,17 @@ call either the real or complex square root method on demand using .. doctest:: - julia> f(x) = try + julia> h(x) = try sqrt(x) catch sqrt(complex(x, 0)) end - f (generic function with 1 method) + h (generic function with 1 method) - julia> f(1) + julia> h(1) 1.0 - julia> f(-1) + julia> h(-1) 0.0 + 1.0im It is important to note that in real code computing this function, one would @@ -842,7 +854,8 @@ assumes ``x`` is a real number and returns its square root: julia> sqrt_second(-9) ERROR: DomainError: - in sqrt_second at none:7 + in sqrt_second(::Int64) at ./none:7 + in eval(::Module, ::Any) at ./boot.jl:237 Note that the symbol following ``catch`` will always be interpreted as a name for the exception, so care is needed when writing ``try/catch`` expressions diff --git a/doc/manual/conversion-and-promotion.rst b/doc/manual/conversion-and-promotion.rst index 8e3a06c2a2198..823f3e691dd3a 100644 --- a/doc/manual/conversion-and-promotion.rst +++ b/doc/manual/conversion-and-promotion.rst @@ -101,10 +101,11 @@ requested conversion: This may have arisen from a call to the constructor AbstractFloat(...), since type constructors fall back to convert methods. Closest candidates are: - convert(::Type{AbstractFloat}, ::Bool) - convert(::Type{AbstractFloat}, ::Int8) - convert(::Type{AbstractFloat}, ::Int16) + convert(::Type{AbstractFloat}, !Matched::Bool) + convert(::Type{AbstractFloat}, !Matched::Int8) + convert(::Type{AbstractFloat}, !Matched::Int16) ... + in eval(::Module, ::Any) at ./boot.jl:237 Some languages consider parsing strings as numbers or formatting numbers as strings to be conversions (many dynamic languages will even @@ -146,7 +147,8 @@ to one and zero: julia> convert(Bool, 1im) ERROR: InexactError() - in convert at complex.jl:18 + in convert(::Type{Bool}, ::Complex{Int64}) at ./complex.jl:18 + in eval(::Module, ::Any) at ./boot.jl:237 julia> convert(Bool, 0im) false @@ -161,7 +163,8 @@ This is the actual implementation in julia:: julia> convert(Bool, 1im) ERROR: InexactError() - in convert at complex.jl:18 + in convert(::Type{Bool}, ::Complex{Int64}) at ./complex.jl:18 + in eval(::Module, ::Any) at ./boot.jl:237 Case Study: Rational Conversions @@ -250,10 +253,10 @@ promotion is to convert numeric arguments to a common type: (1.0,2.5,3.0,0.75) julia> promote(1.5, im) - (1.5 + 0.0im,0.0 + 1.0im) + (1.5+0.0im,0.0+1.0im) julia> promote(1 + 2im, 3//4) - (1//1 + 2//1*im,3//4 + 0//1*im) + (1//1+2//1*im,3//4+0//1*im) Floating-point values are promoted to the largest of the floating-point argument types. Integer values are promoted to the larger of either the diff --git a/doc/manual/documentation.rst b/doc/manual/documentation.rst index 305137d358431..7b6d8945e097c 100644 --- a/doc/manual/documentation.rst +++ b/doc/manual/documentation.rst @@ -30,7 +30,7 @@ macros and pass them to the ``@doc`` macro just as well. Here is a more complex example, still using Markdown: -.. doctest:: +.. code-block:: julia """ bar(x[, y]) diff --git a/doc/manual/functions.rst b/doc/manual/functions.rst index 786f9f12d1c8e..f10430f73113c 100644 --- a/doc/manual/functions.rst +++ b/doc/manual/functions.rst @@ -204,12 +204,12 @@ without being given a name, using either of these syntaxes: .. doctest:: julia> x -> x^2 + 2x - 1 - #1 (generic function with 1 method) + (::#1) (generic function with 1 method) julia> function (x) x^2 + 2x - 1 end - #2 (generic function with 1 method) + (::#3) (generic function with 1 method) This creates a function taking one argument *x* and returning the value of the polynomial *x*\ ^2 + 2\ *x* - 1 at that value. diff --git a/doc/manual/integers-and-floating-point-numbers.rst b/doc/manual/integers-and-floating-point-numbers.rst index c5e60a71e738c..eb4a3b3af5b19 100644 --- a/doc/manual/integers-and-floating-point-numbers.rst +++ b/doc/manual/integers-and-floating-point-numbers.rst @@ -412,14 +412,23 @@ types: .. doctest:: - julia> (typemin(Float16),typemax(Float16)) - (-Inf16,Inf16) + julia> typemin(Float16) + -Inf16 - julia> (typemin(Float32),typemax(Float32)) - (-Inf32,Inf32) + julia> typemax(Float16) + Inf16 - julia> (typemin(Float64),typemax(Float64)) - (-Inf,Inf) + julia> typemin(Float32) + -Inf32 + + julia> typemax(Float32) + Inf32 + + julia> typemin(Float64) + -Inf + + julia> typemax(Float64) + Inf Machine epsilon diff --git a/doc/manual/mathematical-operations.rst b/doc/manual/mathematical-operations.rst index 2f6ae1409a132..0dc73d3e0b947 100644 --- a/doc/manual/mathematical-operations.rst +++ b/doc/manual/mathematical-operations.rst @@ -384,21 +384,23 @@ The following examples show the different forms. julia> Int8(128) ERROR: InexactError() - in call at ./essentials.jl:58 - in eval at ./boot.jl:263 + in Int8(::Int64) at ./sysimg.jl:50 + in eval(::Module, ::Any) at ./boot.jl:237 julia> Int8(127.0) 127 julia> Int8(3.14) ERROR: InexactError() - in call at ./essentials.jl:58 - in eval at ./boot.jl:263 + [inlined code] from ./int.jl:229 + in Int8(::Float64) at ./sysimg.jl:50 + in eval(::Module, ::Any) at ./boot.jl:237 julia> Int8(128.0) ERROR: InexactError() - in call at ./essentials.jl:58 - in eval at ./boot.jl:263 + [inlined code] from ./int.jl:229 + in Int8(::Float64) at ./sysimg.jl:50 + in eval(::Module, ::Any) at ./boot.jl:237 julia> 127 % Int8 127 @@ -411,9 +413,9 @@ The following examples show the different forms. julia> round(Int8,127.6) ERROR: InexactError() - in trunc at ./float.jl:357 - in round at ./float.jl:177 - in eval at ./boot.jl:263 + in trunc(::Type{Int8}, ::Float64) at ./float.jl:373 + in round(::Type{Int8}, ::Float64) at ./float.jl:180 + in eval(::Module, ::Any) at ./boot.jl:237 See :ref:`man-conversion-and-promotion` for how to define your own conversions and promotions. diff --git a/doc/manual/metaprogramming.rst b/doc/manual/metaprogramming.rst index bc32d8c0a9019..c4c3ac8444153 100644 --- a/doc/manual/metaprogramming.rst +++ b/doc/manual/metaprogramming.rst @@ -257,6 +257,7 @@ cause a compile-time error: julia> $a + b ERROR: unsupported or misplaced expression $ + in eval(::Module, ::Any) at ./boot.jl:237 In this example, the tuple ``(1,2,3)`` is interpolated as an expression into a conditional test: @@ -264,7 +265,7 @@ expression into a conditional test: .. doctest:: julia> ex = :(a in $:((1,2,3)) ) - :($(Expr(:in, :a, :((1,2,3))))) + :(a in (1,2,3)) Interpolating symbols into a nested expression requires enclosing each symbol in an enclosing quote block:: @@ -297,6 +298,9 @@ at global scope using :func:`eval`: julia> eval(ex) ERROR: UndefVarError: b not defined + in eval(::Module, ::Any) at ./boot.jl:237 + in eval(::Any) at ./boot.jl:236 + in eval(::Module, ::Any) at ./boot.jl:237 julia> a = 1; b = 2; @@ -316,6 +320,7 @@ module's environment: julia> x ERROR: UndefVarError: x not defined + in eval(::Module, ::Any) at ./boot.jl:237 julia> eval(ex) 1 @@ -420,6 +425,7 @@ Here is an extraordinarily simple macro: julia> macro sayhello() return :( println("Hello, world!") ) end + @sayhello (macro with 1 method) Macros have a dedicated character in Julia's syntax: the ``@`` (at-sign), followed by the unique name declared in a ``macro NAME ... end`` block. @@ -545,6 +551,7 @@ This macro can be used like this: julia> @assert 1==0 ERROR: AssertionError: 1 == 0 + in eval(::Module, ::Any) at ./boot.jl:237 In place of the written syntax, the macro call is expanded at parse time to its returned result. This is equivalent to writing:: diff --git a/doc/manual/methods.rst b/doc/manual/methods.rst index 2a21398f824e3..e7fb935b2891e 100644 --- a/doc/manual/methods.rst +++ b/doc/manual/methods.rst @@ -93,22 +93,26 @@ Applying it to any other types of arguments will result in a :exc:`MethodError`: .. doctest:: julia> f(2.0, 3) - ERROR: MethodError: `f` has no method matching f(::Float64, ::Int64) + ERROR: MethodError: no method matching f(::Float64, ::Int64) Closest candidates are: f(::Float64, !Matched::Float64) + in eval(::Module, ::Any) at ./boot.jl:237 julia> f(Float32(2.0), 3.0) - ERROR: MethodError: `f` has no method matching f(::Float32, ::Float64) + ERROR: MethodError: no method matching f(::Float32, ::Float64) Closest candidates are: f(!Matched::Float64, ::Float64) + in eval(::Module, ::Any) at ./boot.jl:237 julia> f(2.0, "3.0") - ERROR: MethodError: `f` has no method matching f(::Float64, ::String) + ERROR: MethodError: no method matching f(::Float64, ::String) Closest candidates are: f(::Float64, !Matched::Float64) + in eval(::Module, ::Any) at ./boot.jl:237 julia> f("2.0", "3.0") - ERROR: MethodError: `f` has no method matching f(::String, ::String) + ERROR: MethodError: no method matching f(::String, ::String) + in eval(::Module, ::Any) at ./boot.jl:237 As you can see, the arguments must be precisely of type :obj:`Float64`. Other numeric types, such as integers or 32-bit floating-point values, @@ -173,12 +177,14 @@ function ``f`` remains undefined, and applying it will still result in a .. doctest:: julia> f("foo", 3) - ERROR: MethodError: `f` has no method matching f(::String, ::Int64) + ERROR: MethodError: no method matching f(::String, ::Int64) Closest candidates are: f(!Matched::Number, ::Number) + in eval(::Module, ::Any) at ./boot.jl:237 julia> f() - ERROR: MethodError: `f` has no method matching f() + ERROR: MethodError: no method matching f() + in eval(::Module, ::Any) at ./boot.jl:237 You can easily see which methods exist for a function by entering the function object itself in an interactive session: @@ -412,19 +418,19 @@ the intersection case: .. doctest:: - julia> g(x::Float64, y::Float64) = 2x + 2y; + julia> h(x::Float64, y::Float64) = 2x + 2y; - julia> g(x::Float64, y) = 2x + y; + julia> h(x::Float64, y) = 2x + y; - julia> g(x, y::Float64) = x + 2y; + julia> h(x, y::Float64) = x + 2y; - julia> g(2.0, 3) + julia> h(2.0, 3) 7.0 - julia> g(2, 3.0) + julia> h(2, 3.0) 8.0 - julia> g(2.0, 3.0) + julia> h(2.0, 3.0) 10.0 To suppress Julia's warning, the disambiguating method must be defined @@ -492,9 +498,10 @@ signature: 4 julia> myappend([1,2,3],2.5) - ERROR: MethodError: `myappend` has no method matching myappend(::Array{Int64,1}, ::Float64) + ERROR: MethodError: no method matching myappend(::Array{Int64,1}, ::Float64) Closest candidates are: myappend{T}(::Array{T,1}, !Matched::T) + in eval(::Module, ::Any) at ./boot.jl:237 julia> myappend([1.0,2.0,3.0],4.0) 4-element Array{Float64,1}: @@ -504,9 +511,10 @@ signature: 4.0 julia> myappend([1.0,2.0,3.0],4) - ERROR: MethodError: `myappend` has no method matching myappend(::Array{Float64,1}, ::Int64) + ERROR: MethodError: no method matching myappend(::Array{Float64,1}, ::Int64) Closest candidates are: myappend{T}(::Array{T,1}, !Matched::T) + in eval(::Module, ::Any) at ./boot.jl:237 As you can see, the type of the appended element must match the element type of the vector it is appended to, or else a :exc:`MethodError` is raised. diff --git a/doc/manual/performance-tips.rst b/doc/manual/performance-tips.rst index f1932563ac9c8..f5fe2518e9e2c 100644 --- a/doc/manual/performance-tips.rst +++ b/doc/manual/performance-tips.rst @@ -279,7 +279,7 @@ change: .. doctest:: julia> m.a = 4.5f0 - 4.5 + 4.5f0 julia> typeof(m.a) Float64 diff --git a/doc/manual/stacktraces.rst b/doc/manual/stacktraces.rst index 570737a43fec0..fb56df43e72c5 100644 --- a/doc/manual/stacktraces.rst +++ b/doc/manual/stacktraces.rst @@ -31,8 +31,9 @@ alias :obj:`StackTrace` can be used in place of ``Vector{StackFrame}``. (Example julia> example() ...-element Array{StackFrame,1}: - example at none:1 - eval at boot.jl:265 + in example() at none:1 + in eval(::Module, ::Any) at boot.jl:237 + [inlined code] from sysimg.jl:11 ... julia> @noinline child() = stacktrace() @@ -46,10 +47,11 @@ alias :obj:`StackTrace` can be used in place of ``Vector{StackFrame}``. (Example julia> grandparent() ...-element Array{StackFrame,1}: - child at none:1 - parent at none:1 - grandparent at none:1 - eval at boot.jl:265 + [inlined code] from stacktraces.jl:135 + in child() at none:1 + in parent() at none:1 + in grandparent() at none:1 + in eval(::Module, ::Any) at boot.jl:237 ... Note that when calling :func:`stacktrace` you'll typically see a frame with @@ -77,7 +79,7 @@ returned by :func:`backtrace`: .. doctest:: julia> top_frame = stacktrace()[1] - eval at boot.jl:265 + in eval(::Module, ::Any) at boot.jl:237 julia> top_frame.func :eval @@ -86,7 +88,7 @@ returned by :func:`backtrace`: Symbol("./boot.jl") julia> top_frame.line - 265 + 237 julia> top_frame.inlined_file Symbol("") @@ -116,17 +118,19 @@ helpful in many places, the most obvious application is in error handling and de julia> @noinline bad_function() = undeclared_variable bad_function (generic function with 1 method) - julia> @noinline example() = try + julia> @noinline example1() = try bad_function() catch stacktrace() end - example (generic function with 1 method) + example1 (generic function with 1 method) - julia> example() + julia> example1() ...-element Array{StackFrame,1}: - example at none:4 - eval at boot.jl:265 + [inlined code] from stacktraces.jl:135 + in example1() at none:2 + in eval(::Module, ::Any) at boot.jl:237 + [inlined code] from sysimg.jl:11 ... You may notice that in the example above the first stack frame points points at line 4, @@ -142,50 +146,52 @@ returns stack information for the context of the most recent exception: .. doctest:: - julia> @noinline bad_function() = undeclared_variable - bad_function (generic function with 1 method) + julia> @noinline bad_function1() = undeclared_variable + bad_function1 (generic function with 1 method) - julia> @noinline example() = try - bad_function() + julia> @noinline example2() = try + bad_function1() catch catch_stacktrace() end - example (generic function with 1 method) + example2 (generic function with 1 method) - julia> example() + julia> example2() ...-element Array{StackFrame,1}: - bad_function at none:1 - example at none:2 - eval at boot.jl:265 + in bad_function1() at none:1 + in example2() at none:2 + in eval(::Module, ::Any) at boot.jl:237 + [inlined code] from sysimg.jl:11 ... Notice that the stack trace now indicates the appropriate line number and the missing frame. .. doctest:: - julia> @noinline child() = error("Whoops!") - child (generic function with 1 method) + julia> @noinline child1() = error("Whoops!") + child1 (generic function with 1 method) - julia> @noinline parent() = child() - parent (generic function with 1 method) + julia> @noinline parent1() = child1() + parent1 (generic function with 1 method) - julia> @noinline function grandparent() + julia> @noinline function grandparent1() try - parent() + parent1() catch err println("ERROR: ", err.msg) catch_stacktrace() end end - grandparent (generic function with 1 method) + grandparent1 (generic function with 1 method) - julia> grandparent() + julia> grandparent1() ERROR: Whoops! ...-element Array{StackFrame,1}: - child at none:1 - parent at none:1 - grandparent at none:3 - eval at boot.jl:265 + in child1() at none:1 + in parent1() at none:1 + in grandparent1() at none:3 + in eval(::Module, ::Any) at boot.jl:237 + [inlined code] from sysimg.jl:11 ... Comparison with :func:`backtrace` @@ -248,7 +254,7 @@ by passing them into :func:`StackTraces.lookup`: Ptr{Void} @0x... julia> frame = StackTraces.lookup(pointer) - [inlined code from task.c:663] rec_backtrace at task.c:723 + in jl_backtrace_from_here at stackwalk.c:103 julia> println("The top frame is from $(frame.func)!") - The top frame is from rec_backtrace! + The top frame is from jl_backtrace_from_here! diff --git a/doc/manual/strings.rst b/doc/manual/strings.rst index 7c5c34a2e33e4..3185106de4e01 100644 --- a/doc/manual/strings.rst +++ b/doc/manual/strings.rst @@ -289,13 +289,15 @@ such an invalid byte index, an error is thrown: julia> s[2] ERROR: UnicodeError: invalid character index - in next at ./unicode/utf8.jl:65 - in getindex at strings/basic.jl:37 + in next(::UTF8String, ::Int64) at ./unicode/utf8.jl:65 + in getindex(::UTF8String, ::Int64) at ./strings/basic.jl:38 + in eval(::Module, ::Any) at ./boot.jl:237 julia> s[3] ERROR: UnicodeError: invalid character index - in next at ./unicode/utf8.jl:65 - in getindex at strings/basic.jl:37 + in next(::UTF8String, ::Int64) at ./unicode/utf8.jl:65 + in getindex(::UTF8String, ::Int64) at ./strings/basic.jl:38 + in eval(::Module, ::Any) at ./boot.jl:237 julia> s[4] ' ' @@ -547,10 +549,11 @@ contained in a string: false julia> contains("Xylophon", 'o') - ERROR: MethodError: `contains` has no method matching contains(::String, ::Char) + ERROR: MethodError: no method matching contains(::String, ::Char) Closest candidates are: contains(!Matched::Function, ::Any, !Matched::Any) contains(::AbstractString, !Matched::AbstractString) + in eval(::Module, ::Any) at ./boot.jl:237 The last error is because ``'o'`` is a character literal, and :func:`contains` is a generic function that looks for subsequences. To look for an element in a @@ -871,6 +874,7 @@ error: julia> "DATA\xff\u2200" ERROR: syntax: invalid UTF-8 sequence + in eval(::Module, ::Any) at ./boot.jl:237 Also observe the significant distinction between ``\xff`` and ``\uff``: the former escape sequence encodes the *byte 255*, whereas the latter diff --git a/doc/manual/types.rst b/doc/manual/types.rst index 9215c075537f6..b79cbc2c3880b 100644 --- a/doc/manual/types.rst +++ b/doc/manual/types.rst @@ -102,6 +102,7 @@ exception is thrown, otherwise, the left-hand value is returned: julia> (1+2)::AbstractFloat ERROR: TypeError: typeassert: expected AbstractFloat, got Int64 + in eval(::Module, ::Any) at ./boot.jl:237 julia> (1+2)::Int 3 @@ -411,7 +412,8 @@ However, the value for ``baz`` must be convertible to :class:`Int`: julia> Foo((), 23.5, 1) ERROR: InexactError() - in call at none:2 + in Foo(::Tuple{}, ::Float64, ::Int64) at ./none:2 + in eval(::Module, ::Any) at ./boot.jl:237 You may find a list of field names using the ``fieldnames`` function. @@ -442,7 +444,7 @@ You can also change the values as one would expect: .. doctest:: julia> foo.qux = 2 - 2.0 + 2 julia> foo.bar = 1//2 1//2 @@ -765,9 +767,22 @@ each field: ERROR: MethodError: Cannot `convert` an object of type Float64 to an object of type Point{Float64} This may have arisen from a call to the constructor Point{Float64}(...), since type constructors fall back to convert methods. + Closest candidates are: + convert{T}(::Type{T}, !Matched::T) + (!Matched::Type{BoundsError})(::ANY) + (!Matched::Type{BoundsError})(::ANY, !Matched::ANY) + ... + in Point{Float64}(::Float64) at ./sysimg.jl:50 + in eval(::Module, ::Any) at ./boot.jl:237 julia> Point{Float64}(1.0,2.0,3.0) ERROR: MethodError: no method matching Point{Float64}(::Float64, ::Float64, ::Float64) + Closest candidates are: + (!Matched::Type{TypeError})(::Any, ::Any, ::Any, !Matched::Any) + (!Matched::Type{Expr})(::ANY...) + (!Matched::Type{Core.Inference.Generator{I,F}})(::Any, ::Any, ::Any...) + ... + in eval(::Module, ::Any) at ./boot.jl:237 Only one default constructor is generated for parametric types, since overriding it is not possible. This constructor accepts any arguments @@ -909,9 +924,11 @@ subtypes of :obj:`Real`: julia> Pointy{AbstractString} ERROR: TypeError: Pointy: in T, expected T<:Real, got Type{AbstractString} + in eval(::Module, ::Any) at ./boot.jl:237 julia> Pointy{1} ERROR: TypeError: Pointy: in T, expected T<:Real, got Int64 + in eval(::Module, ::Any) at ./boot.jl:237 Type parameters for parametric composite types can be restricted in the same manner:: @@ -1342,13 +1359,13 @@ To construct an object representing a non-missing value of type ``T``, use the .. doctest:: julia> x1 = Nullable(1) - Nullable(1) + Nullable{Int64}(1) julia> x2 = Nullable(1.0) - Nullable(1.0) + Nullable{Float64}(1.0) julia> x3 = Nullable([1, 2, 3]) - Nullable([1,2,3]) + Nullable{Array{Int64,1}}([1,2,3]) Note the core distinction between these two ways of constructing a :obj:`Nullable` object: in one style, you provide a type, ``T``, as a function parameter; in diff --git a/doc/manual/variables-and-scoping.rst b/doc/manual/variables-and-scoping.rst index 480e836bf9a82..0b63516a82739 100644 --- a/doc/manual/variables-and-scoping.rst +++ b/doc/manual/variables-and-scoping.rst @@ -306,11 +306,12 @@ macro definition need not come before its inner usage: .. doctest:: julia> f = y -> x + y - (anonymous function) + (::#1) (generic function with 1 method) julia> f(3) ERROR: UndefVarError: x not defined - in anonymous at none:1 + in (::##1#2)(::Int64) at ./none:1 + in eval(::Module, ::Any) at ./boot.jl:237 julia> x = 1 1 diff --git a/doc/manual/variables.rst b/doc/manual/variables.rst index c2d374de36094..a102dc62dbd46 100644 --- a/doc/manual/variables.rst +++ b/doc/manual/variables.rst @@ -128,9 +128,11 @@ statements: julia> else = false ERROR: syntax: unexpected "else" + in eval(::Module, ::Any) at ./boot.jl:237 julia> try = "No" ERROR: syntax: unexpected "=" + in eval(::Module, ::Any) at ./boot.jl:237 Stylistic Conventions diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index 7e3e92c70930f..89ee7abf0584c 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -367,7 +367,8 @@ All Objects julia> convert(Int, 3.5) ERROR: InexactError() - in convert at int.jl:209 + in convert(::Type{Int64}, ::Float64) at ./int.jl:229 + in eval(::Module, ::Any) at ./boot.jl:237 If ``T`` is a :obj:`AbstractFloat` or :obj:`Rational` type, then it will return the closest value to ``x`` representable by ``T``\ . diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index 095277f615441..116163dc7e961 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -1134,7 +1134,8 @@ Dequeues julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:543 + in deleteat!(::Array{Int64,1}, ::Tuple{Int64,Int64}) at ./array.jl:565 + in eval(::Module, ::Any) at ./boot.jl:237 .. function:: splice!(collection, index, [replacement]) -> item @@ -1324,17 +1325,11 @@ inserted and priorities accessed or changed using indexing notation. julia> # Insert keys with associated priorities pq["a"] = 10; pq["b"] = 5; pq["c"] = 15; pq - Base.Collections.PriorityQueue{Any,Any,Base.Order.ForwardOrdering} with 3 entries: - "c" => 15 - "b" => 5 - "a" => 10 + Base.Collections.PriorityQueue{Any,Any,Base.Order.ForwardOrdering}("c"=>15,"b"=>5,"a"=>10) julia> # Change the priority of an existing key pq["a"] = 0; pq - Base.Collections.PriorityQueue{Any,Any,Base.Order.ForwardOrdering} with 3 entries: - "c" => 15 - "b" => 5 - "a" => 0 + Base.Collections.PriorityQueue{Any,Any,Base.Order.ForwardOrdering}("c"=>15,"b"=>5,"a"=>0) Heap Functions --------------