Merge branch 'master' into teh/beginindex

base/interactiveutil.jl

@@ -580,22 +580,22 @@ end
 
 # `methodswith` -- shows a list of methods using the type given
 """
-    methodswith(typ[, module or function][, showparents::Bool=false])
+    methodswith(typ[, module or function]; supertypes::Bool=false])
 
 Return an array of methods with an argument of type `typ`.
 
 The optional second argument restricts the search to a particular module or function
 (the default is all top-level modules).
 
-If optional `showparents` is `true`, also return arguments with a parent type of `typ`,
+If keyword `supertypes` is `true`, also return arguments with a parent type of `typ`,
 excluding type `Any`.
 """
-function methodswith(t::Type, f::Function, showparents::Bool=false, meths = Method[])
+function methodswith(t::Type, f::Function, meths = Method[]; supertypes::Bool=false)
     for d in methods(f)
         if any(function (x)
                    let x = rewrap_unionall(x, d.sig)
                        (type_close_enough(x, t) ||
-                        (showparents ? (t <: x && (!isa(x,TypeVar) || x.ub != Any)) :
+                        (supertypes ? (t <: x && (!isa(x,TypeVar) || x.ub != Any)) :
                          (isa(x,TypeVar) && x.ub != Any && t == x.ub)) &&
                         x != Any)
                    end
@@ -607,25 +607,25 @@ function methodswith(t::Type, f::Function, showparents::Bool=false, meths = Meth
     return meths
 end
 
-function _methodswith(t::Type, m::Module, showparents::Bool)
+function _methodswith(t::Type, m::Module, supertypes::Bool)
     meths = Method[]
     for nm in names(m)
         if isdefined(m, nm)
             f = getfield(m, nm)
             if isa(f, Function)
-                methodswith(t, f, showparents, meths)
+                methodswith(t, f, meths; supertypes = supertypes)
             end
         end
     end
     return unique(meths)
 end
 
-methodswith(t::Type, m::Module, showparents::Bool=false) = _methodswith(t, m, showparents)
+methodswith(t::Type, m::Module; supertypes::Bool=false) = _methodswith(t, m, supertypes)
 
-function methodswith(t::Type, showparents::Bool=false)
+function methodswith(t::Type; supertypes::Bool=false)
     meths = Method[]
     for mod in loaded_modules_array()
-        append!(meths, _methodswith(t, mod, showparents))
+        append!(meths, _methodswith(t, mod, supertypes))
     end
     return unique(meths)
 end
@@ -691,17 +691,17 @@ download(url, filename)
 # testing
 
 """
-    Base.runtests(tests=["all"], numcores=ceil(Int, Sys.CPU_CORES / 2);
+    Base.runtests(tests=["all"]; ncores=ceil(Int, Sys.CPU_CORES / 2),
                   exit_on_error=false, [seed])
 
 Run the Julia unit tests listed in `tests`, which can be either a string or an array of
-strings, using `numcores` processors. If `exit_on_error` is `false`, when one test
+strings, using `ncores` processors. If `exit_on_error` is `false`, when one test
 fails, all remaining tests in other files will still be run; they are otherwise discarded,
 when `exit_on_error == true`.
 If a seed is provided via the keyword argument, it is used to seed the
 global RNG in the context where the tests are run; otherwise the seed is chosen randomly.
 """
-function runtests(tests = ["all"], numcores = ceil(Int, Sys.CPU_CORES / 2);
+function runtests(tests = ["all"]; ncores = ceil(Int, Sys.CPU_CORES / 2),
                   exit_on_error=false,
                   seed::Union{BitInteger,Nothing}=nothing)
     if isa(tests,AbstractString)
@@ -710,7 +710,7 @@ function runtests(tests = ["all"], numcores = ceil(Int, Sys.CPU_CORES / 2);
     exit_on_error && push!(tests, "--exit-on-error")
     seed != nothing && push!(tests, "--seed=0x$(hex(seed % UInt128))") # cast to UInt128 to avoid a minus sign
     ENV2 = copy(ENV)
-    ENV2["JULIA_CPU_CORES"] = "$numcores"
+    ENV2["JULIA_CPU_CORES"] = "$ncores"
     try
         run(setenv(`$(julia_cmd()) $(joinpath(Sys.BINDIR,
             Base.DATAROOTDIR, "julia", "test", "runtests.jl")) $tests`, ENV2))

base/loading.jl

@@ -355,7 +355,7 @@ const re_subsection_deps    = r"^\s*\[\s*\"?(\w+)\"?\s*\.\s*\"?deps\"?\s*\]\s*(?
 const re_key_to_string      = r"^\s*(\w+)\s*=\s*\"(.*)\"\s*(?:#|$)"
 const re_uuid_to_string     = r"^\s*uuid\s*=\s*\"(.*)\"\s*(?:#|$)"
 const re_path_to_string     = r"^\s*path\s*=\s*\"(.*)\"\s*(?:#|$)"
-const re_hash_to_string     = r"^\s*hash-sha1\s*=\s*\"(.*)\"\s*(?:#|$)"
+const re_hash_to_string     = r"^\s*git-tree-sha1\s*=\s*\"(.*)\"\s*(?:#|$)"
 const re_manifest_to_string = r"^\s*manifest\s*=\s*\"(.*)\"\s*(?:#|$)"
 const re_deps_to_any        = r"^\s*deps\s*=\s*(.*?)\s*(?:#|$)"
 

base/promotion.jl

@@ -352,6 +352,22 @@ else
     _return_type(@nospecialize(f), @nospecialize(t)) = Any
 end
 
+"""
+    promote_op(f, argtypes...)
+
+Guess what an appropriate container eltype would be for storing results of
+`f(::argtypes...)`. The guess is in part based on type inference, so can change any time.
+
+!!! warning
+    In pathological cases, the type returned by `promote_op(f, argtypes...)` may not even
+    be a supertype of the return value of `f(::argtypes...)`. Therefore, `promote_op`
+    should _not_ be used e.g. in the preallocation of an output array.
+
+!!! warning
+    Due to its fragility, use of `promote_op` should be avoided. It is preferable to base
+    the container eltype on the type of the actual elements. Only in the absence of any
+    elements (for an empty result container), it may be unavoidable to call `promote_op`.
+"""
 promote_op(::Any...) = (@_inline_meta; Any)
 function promote_op(f, ::Type{S}) where S
     @_inline_meta

base/reducedim.jl

@@ -667,7 +667,7 @@ function findminmax!(f, Rval, Rind, A::AbstractArray{T,N}) where {T,N}
 end
 
 """
-    findmin!(rval, rind, A, [init=true]) -> (minval, index)
+    findmin!(rval, rind, A) -> (minval, index)
 
 Find the minimum of `A` and the corresponding linear index along singleton
 dimensions of `rval` and `rind`, and store the results in `rval` and `rind`.
@@ -714,7 +714,7 @@ end
 isgreater(a, b) = isless(b,a)
 
 """
-    findmax!(rval, rind, A, [init=true]) -> (maxval, index)
+    findmax!(rval, rind, A) -> (maxval, index)
 
 Find the maximum of `A` and the corresponding linear index along singleton
 dimensions of `rval` and `rind`, and store the results in `rval` and `rind`.

base/reflection.jl

@@ -674,28 +674,28 @@ function signature_type(@nospecialize(f), @nospecialize(args))
 end
 
 """
-    code_lowered(f, types, expand_generated = true)
+    code_lowered(f, types; generated = true)
 
 Return an array of the lowered forms (IR) for the methods matching the given generic function
 and type signature.
 
-If `expand_generated` is `false`, the returned `CodeInfo` instances will correspond to fallback
+If `generated` is `false`, the returned `CodeInfo` instances will correspond to fallback
 implementations. An error is thrown if no fallback implementation exists.
-If `expand_generated` is `true`, these `CodeInfo` instances will correspond to the method bodies
+If `generated` is `true`, these `CodeInfo` instances will correspond to the method bodies
 yielded by expanding the generators.
 
-Note that an error will be thrown if `types` are not leaf types when `expand_generated` is
+Note that an error will be thrown if `types` are not leaf types when `generated` is
 `true` and the corresponding method is a `@generated` method.
 """
-function code_lowered(@nospecialize(f), @nospecialize(t = Tuple), expand_generated::Bool = true)
+function code_lowered(@nospecialize(f), @nospecialize(t = Tuple); generated::Bool = true)
     return map(method_instances(f, t)) do m
-        if expand_generated && isgenerated(m)
+        if generated && isgenerated(m)
             if isa(m, Core.MethodInstance)
                 return Core.Compiler.get_staged(m)
             else # isa(m, Method)
                 error("Could not expand generator for `@generated` method ", m, ". ",
                       "This can happen if the provided argument types (", t, ") are ",
-                      "not leaf types, but the `expand_generated` argument is `true`.")
+                      "not leaf types, but the `generated` argument is `true`.")
             end
         end
         return uncompressed_ast(m)

base/sort.jl

@@ -90,7 +90,7 @@ function partialsort!(v::AbstractVector, k::Union{Int,OrdinalRange}, o::Ordering
 end
 
 """
-    partialsort!(v, k, [by=<transform>,] [lt=<comparison>,] [rev=false])
+    partialsort!(v, k; by=<transform>, lt=<comparison>, rev=false)
 
 Partially sort the vector `v` in place, according to the order specified by `by`, `lt` and
 `rev` so that the value at index `k` (or range of adjacent values if `k` is a range) occurs
@@ -145,7 +145,7 @@ partialsort!(v::AbstractVector, k::Union{Int,OrdinalRange};
     partialsort!(v, k, ord(lt,by,rev,order))
 
 """
-    partialsort(v, k, [by=<transform>,] [lt=<comparison>,] [rev=false])
+    partialsort(v, k, by=<transform>, lt=<comparison>, rev=false)
 
 Variant of [`partialsort!`](@ref) which copies `v` before partially sorting it, thereby returning the
 same thing as `partialsort!` but leaving `v` unmodified.
@@ -279,7 +279,7 @@ for s in [:searchsortedfirst, :searchsortedlast, :searchsorted]
 end
 
 """
-    searchsorted(a, x, [by=<transform>,] [lt=<comparison>,] [rev=false])
+    searchsorted(a, x; by=<transform>, lt=<comparison>, rev=false)
 
 Return the range of indices of `a` which compare as equal to `x` (using binary search)
 according to the order specified by the `by`, `lt` and `rev` keywords, assuming that `a`
@@ -304,7 +304,7 @@ julia> searchsorted(a, 4, rev=true)
 """ searchsorted
 
 """
-    searchsortedfirst(a, x, [by=<transform>,] [lt=<comparison>,] [rev=false])
+    searchsortedfirst(a, x; by=<transform>, lt=<comparison>, rev=false)
 
 Return the index of the first value in `a` greater than or equal to `x`, according to the
 specified order. Return `length(a) + 1` if `x` is greater than all values in `a`.
@@ -324,7 +324,7 @@ julia> searchsortedfirst([1, 2, 4, 5, 14], 15)
 """ searchsortedfirst
 
 """
-    searchsortedlast(a, x, [by=<transform>,] [lt=<comparison>,] [rev=false])
+    searchsortedlast(a, x; by=<transform>, lt=<comparison>, rev=false)
 
 Return the index of the last value in `a` less than or equal to `x`, according to the
 specified order. Return `0` if `x` is less than all values in `a`. `a` is assumed to
@@ -671,7 +671,7 @@ sort(v::AbstractVector; kws...) = sort!(copymutable(v); kws...)
 ## partialsortperm: the permutation to sort the first k elements of an array ##
 
 """
-    partialsortperm(v, k, [alg=<algorithm>,] [by=<transform>,] [lt=<comparison>,] [rev=false])
+    partialsortperm(v, k; alg=<algorithm>, by=<transform>, lt=<comparison>, rev=false)
 
 Return a partial permutation of the vector `v`, according to the order specified by
 `by`, `lt` and `rev`, so that `v[output]` returns the first `k` (or range of adjacent values
@@ -686,7 +686,7 @@ partialsortperm(v::AbstractVector, k::Union{Integer,OrdinalRange}; kwargs...) =
     partialsortperm!(similar(Vector{eltype(k)}, axes(v,1)), v, k; kwargs..., initialized=false)
 
 """
-    partialsortperm!(ix, v, k, [alg=<algorithm>,] [by=<transform>,] [lt=<comparison>,] [rev=false,] [initialized=false])
+    partialsortperm!(ix, v, k; alg=<algorithm>, by=<transform>, lt=<comparison>, rev=false, initialized=false)
 
 Like [`partialsortperm`](@ref), but accepts a preallocated index vector `ix`. If `initialized` is `false`
 (the default), `ix` is initialized to contain the values `1:length(ix)`.