add Future.copy! function (#25144)

base/deprecated.jl

@@ -3587,9 +3587,30 @@ info(err::Exception; prefix="ERROR: ", kw...) =
 
 # #24844
 @deprecate copy!(dest::AbstractSet, src) union!(dest, src)
+
+function copy!(dest::AbstractSet, src::AbstractSet)
+    depwarn("copy!(dst::AbstractSet, src::AbstractSet) is deprecated. " *
+            "You can either use union!(dst, src) of Future.copy!(dst, src) instead.", :copy!)
+    union!(dest, src)
+end
+
 @deprecate copy!(dest::AbstractDict, src) foldl(push!, dest, src)
+
+function copy!(dest::AbstractDict, src::AbstractDict)
+    depwarn("copy!(dst::AbstractDict, src::AbstractDict) is deprecated. " *
+            "You can either use merge!(dst, src) of Future.copy!(dst, src) instead.", :copy!)
+    foldl(push!, dest, src)
+end
+
 # 24808
 @deprecate copy!(dest::Union{AbstractArray,IndexStyle}, args...) copyto!(dest, args...)
+
+function copy!(dest::AbstractArray, src::AbstractArray)
+    depwarn("copy!(dst::AbstractArray, src::AbstractArray) is deprecated. " *
+            "You can either use copyto!(dst, src) of Future.copy!(dst, src) instead.", :copy!)
+    copyto!(dest, src)
+end
+
 @deprecate unsafe_copy!(dest, args...) unsafe_copyto!(dest, args...)
 
 # issue #24019

base/sysimg.jl

@@ -503,6 +503,7 @@ Base.require(:Test)
 Base.require(:Unicode)
 Base.require(:Distributed)
 Base.require(:Printf)
+Base.require(:Future)
 
 @eval Base begin
     @deprecate_binding Test root_module(:Test) true ", run `using Test` instead"

stdlib/Future/src/Future.jl

@@ -0,0 +1,27 @@
+# This file is a part of Julia. License is MIT: https://julialang.org/license
+
+"The `Future` module implements future behavior of already existing functions,
+which will replace the current version in a future release of Julia."
+module Future
+
+## copy!
+
+"""
+    Future.copy!(dst, src) -> dst
+
+Copy `src` into `dst`.
+For collections of the same type, copy the elements of `src` into `dst`,
+discarding any pre-existing elements in `dst`.
+Usually, `dst == src` holds after the call.
+"""
+copy!(dst::AbstractSet, src::AbstractSet) = union!(empty!(dst), src)
+copy!(dst::AbstractDict, src::AbstractDict) = merge!(empty!(dst), src)
+copy!(dst::AbstractVector, src::AbstractVector) = append!(empty!(dst), src)
+
+function copy!(dst::AbstractArray, src::AbstractArray)
+    size(dst) == size(src) || throw(ArgumentError(
+        "arrays must have the same size for copy! (consider using `copyto!`)"))
+    copyto!(dst, src)
+end
+
+end # module Future

stdlib/Future/test/runtests.jl

@@ -0,0 +1,40 @@
+# This file is a part of Julia. License is MIT: https://julialang.org/license
+
+using Test
+using Future
+
+@testset "Future.copy! for AbstractSet" begin
+    for S = (Set, BitSet)
+        s = S([1, 2])
+        for a = ([1], UInt[1], [3, 4, 5], UInt[3, 4, 5])
+            @test s === Future.copy!(s, Set(a)) == S(a)
+            @test s === Future.copy!(s, BitSet(a)) == S(a)
+        end
+    end
+end
+
+
+@testset "Future.copy! for AbstractDict" begin
+    s = Dict(1=>2, 2=>3)
+    for a = ([3=>4], [0x3=>0x4], [3=>4, 5=>6, 7=>8], Pair{UInt,UInt}[3=>4, 5=>6, 7=>8])
+        @test s === Future.copy!(s, Dict(a)) == Dict(a)
+        if length(a) == 1 # current limitation of Base.ImmutableDict
+            @test s === Future.copy!(s, Base.ImmutableDict(a[])) == Dict(a[])
+        end
+    end
+end
+
+@testset "Future.copy! for AbstractVector" begin
+        s = Vector([1, 2])
+        for a = ([1], UInt[1], [3, 4, 5], UInt[3, 4, 5])
+            @test s === Future.copy!(s, Vector(a)) == Vector(a)
+            @test s === Future.copy!(s, SparseVector(a)) == Vector(a)
+        end
+end
+
+@testset "Future.copy! for AbstractArray" begin
+    @test_throws ArgumentError Future.copy!(zeros(2, 3), zeros(3, 2))
+    s = zeros(2, 2)
+    @test s === Future.copy!(s, fill(1, 2, 2)) == fill(1, 2, 2)
+    @test s === Future.copy!(s, fill(1.0, 2, 2)) == fill(1.0, 2, 2)
+end

test/compile.jl

@@ -218,7 +218,7 @@ try
                 [:Base, :Core, Foo2_module, FooBase_module, :Main]),
             # plus modules included in the system image
             Dict(s => Base.module_uuid(Base.root_module(s)) for s in
-                [:Base64, :CRC32c, :Dates, :DelimitedFiles, :FileWatching,
+                [:Base64, :CRC32c, :Dates, :DelimitedFiles, :FileWatching, :Future,
                  :IterativeEigensolvers, :Logging, :Mmap, :Printf, :Profile, :SharedArrays,
                  :SuiteSparse, :Test, :Unicode, :Distributed]))
         @test discard_module.(deps) == deps1