From cf0deee91763d8e13a7aa7702b4592eb235a2102 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Fri, 4 Jul 2025 08:12:45 -0500 Subject: [PATCH 1/3] Clarify "in-place"ness in sorting docs --- base/sort.jl | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/base/sort.jl b/base/sort.jl index 6cc1420708a35..481e640a0efb3 100644 --- a/base/sort.jl +++ b/base/sort.jl @@ -115,12 +115,15 @@ maybeview(v, k::Integer) = v[k] """ partialsort!(v, k; by=identity, lt=isless, rev=false) -Partially sort the vector `v` in place so that the value at index `k` (or +Partially sort the vector `v` in-place 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. 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!` may not fully sort the input array. +While the result of this function is stored in `v`, scratch space may be allocated to +improve the performance of the sorting process. + For the keyword arguments, see the documentation of [`sort!`](@ref). @@ -1625,10 +1628,13 @@ defalg(v) = DEFAULT_STABLE """ sort!(v; alg::Base.Sort.Algorithm=Base.Sort.defalg(v), lt=isless, by=identity, rev::Bool=false, order::Base.Order.Ordering=Base.Order.Forward) -Sort the vector `v` in place. A stable algorithm is used by default: the +Sort the vector `v` in-place. + +A stable algorithm is used by default: the ordering of elements that compare equal is preserved. A specific algorithm can be selected via the `alg` keyword (see [Sorting Algorithms](@ref) for available -algorithms). +algorithms). While the result of this function is stored in `v`, scratch space +may be allocated to improve the performance of the sorting process. Elements are first transformed with the function `by` and then compared according to either the function `lt` or the ordering `order`. Finally, the @@ -1745,7 +1751,7 @@ end Variant of [`sort!`](@ref) that returns a sorted copy of `v` leaving `v` itself unmodified. When calling `sort` on the [`keys`](@ref) or [`values](@ref) of a dictionary, `v` is -collected and then sorted in place. +collected and then sorted in-place. !!! compat "Julia 1.12" Sorting `NTuple`s requires Julia 1.12 or later. @@ -2289,7 +2295,7 @@ UIntMappable(T::Type, order::ReverseOrdering) = UIntMappable(T, order.fwd) ### Vectors -# Convert v to unsigned integers in place, maintaining sort order. +# Convert v to unsigned integers in-place, maintaining sort order. function uint_map!(v::AbstractVector, lo::Integer, hi::Integer, order::Ordering) u = reinterpret(UIntMappable(eltype(v), order), v) @inbounds for i in lo:hi From c4d7c2162c803da2437ee08b239119a2cebf17a5 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Fri, 4 Jul 2025 08:17:37 -0500 Subject: [PATCH 2/3] Avoid in-place altogether --- base/sort.jl | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/base/sort.jl b/base/sort.jl index 481e640a0efb3..09c3de8623baa 100644 --- a/base/sort.jl +++ b/base/sort.jl @@ -115,15 +115,12 @@ maybeview(v, k::Integer) = v[k] """ partialsort!(v, k; by=identity, lt=isless, rev=false) -Partially sort the vector `v` in-place so that the value at index `k` (or +Mutate the vector `v` so that 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. 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!` may not fully sort the input array. -While the result of this function is stored in `v`, scratch space may be allocated to -improve the performance of the sorting process. - For the keyword arguments, see the documentation of [`sort!`](@ref). @@ -1628,13 +1625,11 @@ defalg(v) = DEFAULT_STABLE """ sort!(v; alg::Base.Sort.Algorithm=Base.Sort.defalg(v), lt=isless, by=identity, rev::Bool=false, order::Base.Order.Ordering=Base.Order.Forward) -Sort the vector `v` in-place. +Mutate the vector `v` so that it is sorted. -A stable algorithm is used by default: the -ordering of elements that compare equal is preserved. A specific algorithm can -be selected via the `alg` keyword (see [Sorting Algorithms](@ref) for available -algorithms). While the result of this function is stored in `v`, scratch space -may be allocated to improve the performance of the sorting process. +A stable algorithm is used by default: the ordering of elements that +compare equal is preserved. A specific algorithm can be selected via the +`alg` keyword (see [Sorting Algorithms](@ref) for available algorithms). Elements are first transformed with the function `by` and then compared according to either the function `lt` or the ordering `order`. Finally, the @@ -1751,7 +1746,7 @@ end Variant of [`sort!`](@ref) that returns a sorted copy of `v` leaving `v` itself unmodified. When calling `sort` on the [`keys`](@ref) or [`values](@ref) of a dictionary, `v` is -collected and then sorted in-place. +collected and then sorted. !!! compat "Julia 1.12" Sorting `NTuple`s requires Julia 1.12 or later. From cb8211e09bbcda4d0490b233b343f21ba323e7ac Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Fri, 4 Jul 2025 08:19:15 -0500 Subject: [PATCH 3/3] Fix typo --- base/sort.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/base/sort.jl b/base/sort.jl index 09c3de8623baa..bfa65d2459680 100644 --- a/base/sort.jl +++ b/base/sort.jl @@ -115,7 +115,7 @@ maybeview(v, k::Integer) = v[k] """ partialsort!(v, k; by=identity, lt=isless, rev=false) -Mutate the vector `v` so that so that the value at index `k` (or +Mutate the vector `v` 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. If `k` is a single index, that value is returned; if `k` is a range, an array of values at those indices is