rename some copy! methods to copyto! (#24808)

When the deprecation gets lifted, they will be re-enabled
with a new meaning.

Author: rfourquet

NEWS.md

@@ -757,6 +757,10 @@ Deprecated or removed
   * `copy!` is deprecated for `AbstractSet` and `AbstractDict`, with the intention to re-enable
     it with a cleaner meaning in a future version ([#24844]).
 
+  * `copy!` (resp. `unsafe_copy!`) is deprecated for `AbstractArray` and is renamed `copyto!`
+    (resp. `unsafe_copyto!`); it will be re-introduced with a different meaning in a future
+    version ([#24808]).
+
   * `a:b` is deprecated for constructing a `StepRange` when `a` and `b` have physical units
     (Dates and Times). Use `a:s:b`, where `s = Dates.Day(1)` or `s = Dates.Second(1)`.
 

base/abstractarray.jl

@@ -585,7 +585,7 @@ empty(a::AbstractVector, ::Type{T}) where {T} = Vector{T}()
 
 ## from general iterable to any array
 
-function copy!(dest::AbstractArray, src)
+function copyto!(dest::AbstractArray, src)
     destiter = eachindex(dest)
     state = start(destiter)
     for x in src
@@ -595,7 +595,7 @@ function copy!(dest::AbstractArray, src)
     return dest
 end
 
-function copy!(dest::AbstractArray, dstart::Integer, src)
+function copyto!(dest::AbstractArray, dstart::Integer, src)
     i = Int(dstart)
     for x in src
         dest[i] = x
@@ -605,7 +605,7 @@ function copy!(dest::AbstractArray, dstart::Integer, src)
 end
 
 # copy from an some iterable object into an AbstractArray
-function copy!(dest::AbstractArray, dstart::Integer, src, sstart::Integer)
+function copyto!(dest::AbstractArray, dstart::Integer, src, sstart::Integer)
     if (sstart < 1)
         throw(ArgumentError(string("source start offset (",sstart,") is < 1")))
     end
@@ -633,7 +633,7 @@ function copy!(dest::AbstractArray, dstart::Integer, src, sstart::Integer)
 end
 
 # this method must be separate from the above since src might not have a length
-function copy!(dest::AbstractArray, dstart::Integer, src, sstart::Integer, n::Integer)
+function copyto!(dest::AbstractArray, dstart::Integer, src, sstart::Integer, n::Integer)
     n < 0 && throw(ArgumentError(string("tried to copy n=", n, " elements, but n should be nonnegative")))
     n == 0 && return dest
     dmax = dstart + n - 1
@@ -663,10 +663,10 @@ end
 ## copy between abstract arrays - generally more efficient
 ## since a single index variable can be used.
 
-copy!(dest::AbstractArray, src::AbstractArray) =
-    copy!(IndexStyle(dest), dest, IndexStyle(src), src)
+copyto!(dest::AbstractArray, src::AbstractArray) =
+    copyto!(IndexStyle(dest), dest, IndexStyle(src), src)
 
-function copy!(::IndexStyle, dest::AbstractArray, ::IndexStyle, src::AbstractArray)
+function copyto!(::IndexStyle, dest::AbstractArray, ::IndexStyle, src::AbstractArray)
     destinds, srcinds = linearindices(dest), linearindices(src)
     isempty(srcinds) || (first(srcinds) ∈ destinds && last(srcinds) ∈ destinds) ||
         throw(BoundsError(dest, srcinds))
@@ -676,7 +676,7 @@ function copy!(::IndexStyle, dest::AbstractArray, ::IndexStyle, src::AbstractArr
     return dest
 end
 
-function copy!(::IndexStyle, dest::AbstractArray, ::IndexCartesian, src::AbstractArray)
+function copyto!(::IndexStyle, dest::AbstractArray, ::IndexCartesian, src::AbstractArray)
     destinds, srcinds = linearindices(dest), linearindices(src)
     isempty(srcinds) || (first(srcinds) ∈ destinds && last(srcinds) ∈ destinds) ||
         throw(BoundsError(dest, srcinds))
@@ -687,17 +687,17 @@ function copy!(::IndexStyle, dest::AbstractArray, ::IndexCartesian, src::Abstrac
     return dest
 end
 
-function copy!(dest::AbstractArray, dstart::Integer, src::AbstractArray)
-    copy!(dest, dstart, src, first(linearindices(src)), _length(src))
+function copyto!(dest::AbstractArray, dstart::Integer, src::AbstractArray)
+    copyto!(dest, dstart, src, first(linearindices(src)), _length(src))
 end
 
-function copy!(dest::AbstractArray, dstart::Integer, src::AbstractArray, sstart::Integer)
+function copyto!(dest::AbstractArray, dstart::Integer, src::AbstractArray, sstart::Integer)
     srcinds = linearindices(src)
     sstart ∈ srcinds || throw(BoundsError(src, sstart))
-    copy!(dest, dstart, src, sstart, last(srcinds)-sstart+1)
+    copyto!(dest, dstart, src, sstart, last(srcinds)-sstart+1)
 end
 
-function copy!(dest::AbstractArray, dstart::Integer,
+function copyto!(dest::AbstractArray, dstart::Integer,
                src::AbstractArray, sstart::Integer,
                n::Integer)
     n == 0 && return dest
@@ -716,7 +716,7 @@ function copy(a::AbstractArray)
     copymutable(a)
 end
 
-function copy!(B::AbstractVecOrMat{R}, ir_dest::AbstractRange{Int}, jr_dest::AbstractRange{Int},
+function copyto!(B::AbstractVecOrMat{R}, ir_dest::AbstractRange{Int}, jr_dest::AbstractRange{Int},
                A::AbstractVecOrMat{S}, ir_src::AbstractRange{Int}, jr_src::AbstractRange{Int}) where {R,S}
     if length(ir_dest) != length(ir_src)
         throw(ArgumentError(string("source and destination must have same size (got ",
@@ -763,7 +763,7 @@ julia> Base.copymutable(tup)
 """
 function copymutable(a::AbstractArray)
     @_propagate_inbounds_meta
-    copy!(similar(a), a)
+    copyto!(similar(a), a)
 end
 copymutable(itr) = collect(itr)
 
@@ -855,7 +855,7 @@ keys(s::IndexStyle, A::AbstractArray, B::AbstractArray...) = eachindex(s, A, B..
 ## Conversions ##
 
 convert(::Type{AbstractArray{T,N}}, A::AbstractArray{T,N}) where {T,N  } = A
-convert(::Type{AbstractArray{T,N}}, A::AbstractArray{S,N}) where {T,S,N} = copy!(similar(A,T), A)
+convert(::Type{AbstractArray{T,N}}, A::AbstractArray{S,N}) where {T,S,N} = copyto!(similar(A,T), A)
 convert(::Type{AbstractArray{T}},   A::AbstractArray{S,N}) where {T,S,N} = convert(AbstractArray{T,N}, A)
 
 convert(::Type{Array}, A::AbstractArray{T,N}) where {T,N} = convert(Array{T,N}, A)
@@ -1150,7 +1150,7 @@ function typed_hcat(::Type{T}, A::AbstractVecOrMat...) where T
         for k=1:nargs
             Ak = A[k]
             n = length(Ak)
-            copy!(B, pos, Ak, 1, n)
+            copyto!(B, pos, Ak, 1, n)
             pos += n
         end
     else
@@ -1248,7 +1248,7 @@ end
 function _cat(A, shape::NTuple{N}, catdims, X...) where N
     offsets = zeros(Int, N)
     inds = Vector{UnitRange{Int}}(uninitialized, N)
-    concat = copy!(zeros(Bool, N), catdims)
+    concat = copyto!(zeros(Bool, N), catdims)
     for x in X
         for i = 1:N
             if concat[i]

base/array.jl

@@ -99,7 +99,7 @@ function vect(X...)
     T = promote_typeof(X...)
     #T[ X[i] for i=1:length(X) ]
     # TODO: this is currently much faster. should figure out why. not clear.
-    return copy!(Vector{T}(uninitialized, length(X)), X)
+    return copyto!(Vector{T}(uninitialized, length(X)), X)
 end
 
 size(a::Array, d) = arraysize(a, d)
@@ -143,7 +143,7 @@ end
 ## copy ##
 
 """
-    unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N)
+    unsafe_copyto!(dest::Ptr{T}, src::Ptr{T}, N)
 
 Copy `N` elements from a source pointer to a destination, with no checking. The size of an
 element is determined by the type of the pointers.
@@ -152,7 +152,7 @@ The `unsafe` prefix on this function indicates that no validation is performed o
 pointers `dest` and `src` to ensure that they are valid. Incorrect usage may corrupt or
 segfault your program, in the same manner as C.
 """
-function unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, n) where T
+function unsafe_copyto!(dest::Ptr{T}, src::Ptr{T}, n) where T
     # Do not use this to copy data between pointer arrays.
     # It can't be made safe no matter how carefully you checked.
     ccall(:memmove, Ptr{Void}, (Ptr{Void}, Ptr{Void}, UInt),
@@ -161,7 +161,7 @@ function unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, n) where T
 end
 
 """
-    unsafe_copy!(dest::Array, do, src::Array, so, N)
+    unsafe_copyto!(dest::Array, do, src::Array, so, N)
 
 Copy `N` elements from a source array to a destination, starting at offset `so` in the
 source and `do` in the destination (1-indexed).
@@ -170,11 +170,11 @@ The `unsafe` prefix on this function indicates that no validation is performed t
 that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in
 the same manner as C.
 """
-function unsafe_copy!(dest::Array{T}, doffs, src::Array{T}, soffs, n) where T
+function unsafe_copyto!(dest::Array{T}, doffs, src::Array{T}, soffs, n) where T
     t1 = @_gc_preserve_begin dest
     t2 = @_gc_preserve_begin src
     if isbits(T)
-        unsafe_copy!(pointer(dest, doffs), pointer(src, soffs), n)
+        unsafe_copyto!(pointer(dest, doffs), pointer(src, soffs), n)
     elseif isbitsunion(T)
         ccall(:memmove, Ptr{Void}, (Ptr{Void}, Ptr{Void}, UInt),
               pointer(dest, doffs), pointer(src, soffs), n * Base.bitsunionsize(T))
@@ -193,21 +193,21 @@ function unsafe_copy!(dest::Array{T}, doffs, src::Array{T}, soffs, n) where T
 end
 
 """
-    copy!(dest, do, src, so, N)
+    copyto!(dest, do, src, so, N)
 
 Copy `N` elements from collection `src` starting at offset `so`, to array `dest` starting at
 offset `do`. Return `dest`.
 """
-function copy!(dest::Array{T}, doffs::Integer, src::Array{T}, soffs::Integer, n::Integer) where T
+function copyto!(dest::Array{T}, doffs::Integer, src::Array{T}, soffs::Integer, n::Integer) where T
     n == 0 && return dest
     n > 0 || throw(ArgumentError(string("tried to copy n=", n, " elements, but n should be nonnegative")))
     if soffs < 1 || doffs < 1 || soffs+n-1 > length(src) || doffs+n-1 > length(dest)
         throw(BoundsError())
     end
-    unsafe_copy!(dest, doffs, src, soffs, n)
+    unsafe_copyto!(dest, doffs, src, soffs, n)
 end
 
-copy!(dest::Array{T}, src::Array{T}) where {T} = copy!(dest, 1, src, 1, length(src))
+copyto!(dest::Array{T}, src::Array{T}) where {T} = copyto!(dest, 1, src, 1, length(src))
 
 """
     copy(x)
@@ -403,7 +403,7 @@ convert(::Type{Array{T}}, x::Array{T,n}) where {T,n} = x
 convert(::Type{Array{T,n}}, x::Array{T,n}) where {T,n} = x
 
 convert(::Type{Array{T}}, x::AbstractArray{S,n}) where {T,n,S} = convert(Array{T,n}, x)
-convert(::Type{Array{T,n}}, x::AbstractArray{S,n}) where {T,n,S} = copy!(Array{T,n}(uninitialized, size(x)), x)
+convert(::Type{Array{T,n}}, x::AbstractArray{S,n}) where {T,n,S} = copyto!(Array{T,n}(uninitialized, size(x)), x)
 
 promote_rule(a::Type{Array{T,n}}, b::Type{Array{S,n}}) where {T,n,S} = el_same(promote_type(T,S), a, b)
 
@@ -432,8 +432,8 @@ julia> collect(Float64, 1:2:5)
 """
 collect(::Type{T}, itr) where {T} = _collect(T, itr, iteratorsize(itr))
 
-_collect(::Type{T}, itr, isz::HasLength) where {T} = copy!(Vector{T}(uninitialized, Int(length(itr)::Integer)), itr)
-_collect(::Type{T}, itr, isz::HasShape) where {T}  = copy!(similar(Array{T}, axes(itr)), itr)
+_collect(::Type{T}, itr, isz::HasLength) where {T} = copyto!(Vector{T}(uninitialized, Int(length(itr)::Integer)), itr)
+_collect(::Type{T}, itr, isz::HasShape) where {T}  = copyto!(similar(Array{T}, axes(itr)), itr)
 function _collect(::Type{T}, itr, isz::SizeUnknown) where T
     a = Vector{T}()
     for x in itr
@@ -475,7 +475,7 @@ collect(A::AbstractArray) = _collect_indices(axes(A), A)
 collect_similar(cont, itr) = _collect(cont, itr, iteratoreltype(itr), iteratorsize(itr))
 
 _collect(cont, itr, ::HasEltype, isz::Union{HasLength,HasShape}) =
-    copy!(_similar_for(cont, eltype(itr), itr, isz), itr)
+    copyto!(_similar_for(cont, eltype(itr), itr, isz), itr)
 
 function _collect(cont, itr, ::HasEltype, isz::SizeUnknown)
     a = _similar_for(cont, eltype(itr), itr, isz)
@@ -485,12 +485,12 @@ function _collect(cont, itr, ::HasEltype, isz::SizeUnknown)
     return a
 end
 
-_collect_indices(::Tuple{}, A) = copy!(Array{eltype(A),0}(uninitialized), A)
+_collect_indices(::Tuple{}, A) = copyto!(Array{eltype(A),0}(uninitialized), A)
 _collect_indices(indsA::Tuple{Vararg{OneTo}}, A) =
-    copy!(Array{eltype(A)}(uninitialized, length.(indsA)), A)
+    copyto!(Array{eltype(A)}(uninitialized, length.(indsA)), A)
 function _collect_indices(indsA, A)
     B = Array{eltype(A)}(uninitialized, length.(indsA))
-    copy!(B, CartesianIndices(axes(B)), A, CartesianIndices(indsA))
+    copyto!(B, CartesianIndices(axes(B)), A, CartesianIndices(indsA))
 end
 
 # define this as a macro so that the call to Inference
@@ -563,7 +563,7 @@ function collect_to!(dest::AbstractArray{T}, itr, offs, st) where T
         else
             R = typejoin(T, S)
             new = similar(dest, R)
-            copy!(new,1, dest,1, i-1)
+            copyto!(new,1, dest,1, i-1)
             @inbounds new[i] = el
             return collect_to!(new, itr, i+1, st)
         end
@@ -589,7 +589,7 @@ function grow_to!(dest, itr, st)
                 # TODO: merge back these two branches when copy! is re-enabled for sets
                 union!(new, dest)
             else
-                copy!(new, dest)
+                copyto!(new, dest)
             end
             push!(new, el)
             return grow_to!(new, itr, st)
@@ -628,22 +628,22 @@ function getindex end
 @eval getindex(A::Array, i1::Int) = arrayref($(Expr(:boundscheck)), A, i1)
 @eval getindex(A::Array, i1::Int, i2::Int, I::Int...) = (@_inline_meta; arrayref($(Expr(:boundscheck)), A, i1, i2, I...))
 
-# Faster contiguous indexing using copy! for UnitRange and Colon
+# Faster contiguous indexing using copyto! for UnitRange and Colon
 function getindex(A::Array, I::UnitRange{Int})
     @_inline_meta
     @boundscheck checkbounds(A, I)
     lI = length(I)
     X = similar(A, lI)
     if lI > 0
-        unsafe_copy!(X, 1, A, first(I), lI)
+        unsafe_copyto!(X, 1, A, first(I), lI)
     end
     return X
 end
 function getindex(A::Array, c::Colon)
     lI = length(A)
     X = similar(A, lI)
     if lI > 0
-        unsafe_copy!(X, 1, A, 1, lI)
+        unsafe_copyto!(X, 1, A, 1, lI)
     end
     return X
 end
@@ -694,14 +694,14 @@ function setindex!(A::Array, X::AbstractArray, I::AbstractVector{Int})
     return A
 end
 
-# Faster contiguous setindex! with copy!
+# Faster contiguous setindex! with copyto!
 function setindex!(A::Array{T}, X::Array{T}, I::UnitRange{Int}) where T
     @_inline_meta
     @boundscheck checkbounds(A, I)
     lI = length(I)
     @boundscheck setindex_shape_check(X, lI)
     if lI > 0
-        unsafe_copy!(A, first(I), X, 1, lI)
+        unsafe_copyto!(A, first(I), X, 1, lI)
     end
     return A
 end
@@ -710,7 +710,7 @@ function setindex!(A::Array{T}, X::Array{T}, c::Colon) where T
     lI = length(A)
     @boundscheck setindex_shape_check(X, lI)
     if lI > 0
-        unsafe_copy!(A, 1, X, 1, lI)
+        unsafe_copyto!(A, 1, X, 1, lI)
     end
     return A
 end
@@ -806,7 +806,7 @@ function append!(a::Array{<:Any,1}, items::AbstractVector)
     itemindices = eachindex(items)
     n = length(itemindices)
     _growend!(a, n)
-    copy!(a, length(a)-n+1, items, first(itemindices), n)
+    copyto!(a, length(a)-n+1, items, first(itemindices), n)
     return a
 end
 
@@ -850,9 +850,9 @@ function prepend!(a::Array{<:Any,1}, items::AbstractVector)
     n = length(itemindices)
     _growbeg!(a, n)
     if a === items
-        copy!(a, 1, items, n+1, n)
+        copyto!(a, 1, items, n+1, n)
     else
-        copy!(a, 1, items, first(itemindices), n)
+        copyto!(a, 1, items, first(itemindices), n)
     end
     return a
 end
@@ -1720,7 +1720,7 @@ function find(testf::Function, A)
         end
     end
     I = Vector{Int}(uninitialized, length(tmpI))
-    copy!(I, tmpI)
+    copyto!(I, tmpI)
     return I
 end
 _index_remapper(A::AbstractArray) = linearindices(A)

base/arraymath.jl

@@ -100,7 +100,7 @@ function flipdim(A::Array{T}, d::Integer) where T
                 for j=0:stride:(N-stride)
                     offs = j + 1 + (i-1)*M
                     boffs = j + 1 + (ri-1)*M
-                    copy!(B, boffs, A, offs, M)
+                    copyto!(B, boffs, A, offs, M)
                 end
             end
         else