diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl index b5b9324295787..f7de758f68a69 100644 --- a/base/docs/helpdb/Base.jl +++ b/base/docs/helpdb/Base.jl @@ -465,14 +465,6 @@ julia> exp10(0.2) """ exp10 -""" - partialsort(v, k, [by=,] [lt=,] [rev=false]) - -Variant of [`partialsort!`](@ref) which copies `v` before partially sorting it, thereby returning the -same thing as `partialsort!` but leaving `v` unmodified. -""" -partialsort - """ accept(server[,client]) @@ -635,59 +627,6 @@ julia> getfield(a, :num) """ getfield -""" - partialsort!(v, k, [by=,] [lt=,] [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 -at the position where it would appear if the array were fully sorted via a non-stable -algorithm. If `k` is a single index, that value is returned; if `k` is a range, an array of -values at those indices is returned. Note that `partialsort!` does not fully sort the input -array. - -# Examples -```jldoctest -julia> a = [1, 2, 4, 3, 4] -5-element Array{Int64,1}: - 1 - 2 - 4 - 3 - 4 - -julia> partialsort!(a, 4) -4 - -julia> a -5-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 4 - -julia> a = [1, 2, 4, 3, 4] -5-element Array{Int64,1}: - 1 - 2 - 4 - 3 - 4 - -julia> partialsort!(a, 4, rev=true) -2 - -julia> a -5-element Array{Int64,1}: - 4 - 4 - 3 - 2 - 1 -``` -""" -partialsort! - """ Float64(x [, mode::RoundingMode]) @@ -1010,18 +949,6 @@ Get the current position of a stream. """ position -""" - partialsortperm(v, k, [alg=,] [by=,] [lt=,] [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 -if `k` is a range) values of a fully sorted version of `v`. If `k` is a single index, -that value is returned; if `k` is a range, an array of values at those indices is returned. - -Note that this is equivalent to, but more efficient than, calling `sortperm(...)[k]`. -""" -partialsortperm - """ reinterpret(type, A) @@ -1108,14 +1035,6 @@ Compute a type that contains both `T` and `S`. """ typejoin -""" - partialsortperm!(ix, v, k, [alg=,] [by=,] [lt=,] [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)`. -""" -partialsortperm! - """ precompile(f,args::Tuple{Vararg{Any}}) diff --git a/base/sort.jl b/base/sort.jl index e9aa1f2201e06..cf173218e14ab 100644 --- a/base/sort.jl +++ b/base/sort.jl @@ -87,10 +87,68 @@ function partialsort!(v::AbstractVector, k::Union{Int,OrdinalRange}, o::Ordering sort!(v, first(inds), last(inds), PartialQuickSort(k), o) v[k] end + +""" + partialsort!(v, k, [by=,] [lt=,] [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 +at the position where it would appear if the array were fully sorted via a non-stable +algorithm. If `k` is a single index, that value is returned; if `k` is a range, an array of +values at those indices is returned. Note that `partialsort!` does not fully sort the input +array. + +# Examples +```jldoctest +julia> a = [1, 2, 4, 3, 4] +5-element Array{Int64,1}: + 1 + 2 + 4 + 3 + 4 + +julia> partialsort!(a, 4) +4 + +julia> a +5-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 4 + +julia> a = [1, 2, 4, 3, 4] +5-element Array{Int64,1}: + 1 + 2 + 4 + 3 + 4 + +julia> partialsort!(a, 4, rev=true) +2 + +julia> a +5-element Array{Int64,1}: + 4 + 4 + 3 + 2 + 1 +``` +""" partialsort!(v::AbstractVector, k::Union{Int,OrdinalRange}; lt=isless, by=identity, rev::Bool=false, order::Ordering=Forward) = partialsort!(v, k, ord(lt,by,rev,order)) +""" + partialsort(v, k, [by=,] [lt=,] [rev=false]) + +Variant of [`partialsort!`](@ref) which copies `v` before partially sorting it, thereby returning the +same thing as `partialsort!` but leaving `v` unmodified. +""" partialsort(v::AbstractVector, k::Union{Int,OrdinalRange}; kws...) = partialsort!(copymutable(v), k; kws...) @@ -612,9 +670,25 @@ sort(v::AbstractVector; kws...) = sort!(copymutable(v); kws...) ## partialsortperm: the permutation to sort the first k elements of an array ## +""" + partialsortperm(v, k, [alg=,] [by=,] [lt=,] [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 +if `k` is a range) values of a fully sorted version of `v`. If `k` is a single index, +that value is returned; if `k` is a range, an array of values at those indices is returned. + +Note that this is equivalent to, but more efficient than, calling `sortperm(...)[k]`. +""" partialsortperm(v::AbstractVector, k::Union{Integer,OrdinalRange}; kwargs...) = partialsortperm!(similar(Vector{eltype(k)}, indices(v,1)), v, k; kwargs..., initialized=false) +""" + partialsortperm!(ix, v, k, [alg=,] [by=,] [lt=,] [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)`. +""" function partialsortperm!(ix::AbstractVector{<:Integer}, v::AbstractVector, k::Union{Int, OrdinalRange}; lt::Function=isless,