From cfd187af2a6143565cb7c01b254927bbfba4bc62 Mon Sep 17 00:00:00 2001 From: Lilith Hafner Date: Mon, 30 Oct 2023 10:32:32 -0500 Subject: [PATCH 1/7] update sort docstring --- base/sort.jl | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/base/sort.jl b/base/sort.jl index f411a240e4e9b..e3215e6092bb3 100644 --- a/base/sort.jl +++ b/base/sort.jl @@ -1474,7 +1474,9 @@ end Variant of [`sort!`](@ref) that returns a sorted copy of `v` leaving `v` itself unmodified. -Uses `Base.copymutable` to support immutable collections and iterables. +By default, `sort` copies its input with [`Base.copymutable`](@ref) before sorting, but some types have +specialized versions of `sort` such as `NTuples` (`sort(::NTuple)` returns an `NTuple`) and +`Dict` (`sort(::Dict)` produces a new sorted dictionary data structure) !!! compat "Julia 1.10" `sort` of arbitrary iterables requires at least Julia 1.10. From 50daaf586ad79dbbacd15cba04b158aed96c6134 Mon Sep 17 00:00:00 2001 From: Lilith Hafner Date: Mon, 30 Oct 2023 10:33:03 -0500 Subject: [PATCH 2/7] make copymutable public --- base/exports.jl | 1 + 1 file changed, 1 insertion(+) diff --git a/base/exports.jl b/base/exports.jl index b6f7ea0d6ad35..c77421d5b1b68 100644 --- a/base/exports.jl +++ b/base/exports.jl @@ -1114,6 +1114,7 @@ public split_rest, tail, checked_length, + copymutable, # Loading DL_LOAD_PATH, From 3b02a302eb1becd174e0fb9ed3ff4dc8ed5d47a1 Mon Sep 17 00:00:00 2001 From: Lilith Hafner Date: Mon, 30 Oct 2023 10:35:02 -0500 Subject: [PATCH 3/7] clarify that users should not typically need to override copymutable --- base/abstractarray.jl | 3 +++ 1 file changed, 3 insertions(+) diff --git a/base/abstractarray.jl b/base/abstractarray.jl index 881070ff7aa00..dbbb28548ed18 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -1201,6 +1201,9 @@ this is equivalent to `copy(a)`, but for other array types it may differ depending on the type of `similar(a)`. For generic iterables this is equivalent to `collect(a)`. +To change the behavior of `copymutable` on a custom collection is typically +sufficient to define `similar` for that collection. + # Examples ```jldoctest julia> tup = (1, 2, 3) From fcf631329ab048dab424f94d748bc6cdd8722257 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Tue, 31 Oct 2023 14:05:35 -0500 Subject: [PATCH 4/7] Grammar --- base/sort.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/base/sort.jl b/base/sort.jl index e3215e6092bb3..489377008a022 100644 --- a/base/sort.jl +++ b/base/sort.jl @@ -1475,8 +1475,8 @@ end Variant of [`sort!`](@ref) that returns a sorted copy of `v` leaving `v` itself unmodified. By default, `sort` copies its input with [`Base.copymutable`](@ref) before sorting, but some types have -specialized versions of `sort` such as `NTuples` (`sort(::NTuple)` returns an `NTuple`) and -`Dict` (`sort(::Dict)` produces a new sorted dictionary data structure) +specialized versions of `sort`, such as `NTuples` (`sort(::NTuple)` returns an `NTuple`) and +`Dict` (`sort(::Dict)` produces a new sorted dictionary data structure). !!! compat "Julia 1.10" `sort` of arbitrary iterables requires at least Julia 1.10. From a03e2ef8dd262bf06e8c3cebf6173f85236aa5f9 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Tue, 31 Oct 2023 14:06:12 -0500 Subject: [PATCH 5/7] xref similar --- base/abstractarray.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/base/abstractarray.jl b/base/abstractarray.jl index dbbb28548ed18..8efff0e001e41 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -1202,7 +1202,7 @@ differ depending on the type of `similar(a)`. For generic iterables this is equivalent to `collect(a)`. To change the behavior of `copymutable` on a custom collection is typically -sufficient to define `similar` for that collection. +sufficient to define [`similar`](@ref) for that collection. # Examples ```jldoctest From 6647c1d5f67d0c091d1a1a58ff120accb22a5d17 Mon Sep 17 00:00:00 2001 From: Lilith Hafner Date: Tue, 31 Oct 2023 14:14:17 -0500 Subject: [PATCH 6/7] add to manual --- doc/src/base/collections.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/src/base/collections.md b/doc/src/base/collections.md index a8f2bdc6b7d7d..5baf0125f6e4f 100644 --- a/doc/src/base/collections.md +++ b/doc/src/base/collections.md @@ -137,6 +137,7 @@ Base.tail Base.step Base.collect(::Any) Base.collect(::Type, ::Any) +Base.copymutable(::Any) Base.filter Base.filter! Base.replace(::Any, ::Pair...) From d12cb607cfe278e87f12a856e201c32d1ced59ff Mon Sep 17 00:00:00 2001 From: Lilith Hafner Date: Tue, 31 Oct 2023 14:29:43 -0500 Subject: [PATCH 7/7] clarify docstring and add StaticArrays example --- base/abstractarray.jl | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/base/abstractarray.jl b/base/abstractarray.jl index 8efff0e001e41..5a143a24fc096 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -1196,13 +1196,12 @@ end """ copymutable(a) -Make a mutable copy of an array or iterable `a`. For `a::Array`, -this is equivalent to `copy(a)`, but for other array types it may -differ depending on the type of `similar(a)`. For generic iterables -this is equivalent to `collect(a)`. +Make a mutable copy of an array or iterable `a`. The result should have the same content as +`a`, but support mutation. For `Array`s and most iterables this is equivalent to +`collect(a)`, but for other array types it may differ depending on the type of `similar(a)`. -To change the behavior of `copymutable` on a custom collection is typically -sufficient to define [`similar`](@ref) for that collection. +To change the behavior of `copymutable` on a custom collection, define [`similar`](@ref) +for that collection. # Examples ```jldoctest @@ -1214,6 +1213,20 @@ julia> Base.copymutable(tup) 1 2 3 + +julia> using StaticArrays + +julia> s = SVector{3}(1,2,3) +3-element SVector{3, Int64} with indices SOneTo(3): + 1 + 2 + 3 + +julia> Base.copymutable(s) +3-element MVector{3, Int64} with indices SOneTo(3): + 1 + 2 + 3 ``` """ function copymutable(a::AbstractArray)