Rename circshift to rotate

base/abstractarraymath.jl

@@ -171,15 +171,16 @@ function flipdim(A::AbstractArray, d::Integer)
     return B
 end
 
-function circshift(a::AbstractArray, shiftamt::Real)
-    circshift!(similar(a), a, (Integer(shiftamt),))
+function rotate(a::AbstractArray, shiftamt::Real)
+    rotate!(similar(a), a, (Integer(shiftamt),))
 end
-circshift(a::AbstractArray, shiftamt::DimsInteger) = circshift!(similar(a), a, shiftamt)
+rotate(a::AbstractArray, shiftamt::DimsInteger) = rotate!(similar(a), a, shiftamt)
 """
-    circshift(A, shifts)
+    rotate(A, shifts)
 
-Circularly shift the data in an array. The second argument is a vector giving the amount to
-shift in each dimension.
+Rotate the data in an array. The second argument is a vector, tuple, or scalar specifying
+the amount to shift in each dimension. Positive shifts correspond to rotation to the right
+and negative shifts to the left. A shift of 0 implies no movement.
 
 # Examples
 ```jldoctest
@@ -190,25 +191,25 @@ julia> b = reshape(collect(1:16), (4,4))
  3  7  11  15
  4  8  12  16
 
-julia> circshift(b, (0,2))
+julia> rotate(b, (0,2))
 4×4 Array{Int64,2}:
   9  13  1  5
  10  14  2  6
  11  15  3  7
  12  16  4  8
 
-julia> circshift(b, (-1,0))
+julia> rotate(b, (-1,0))
 4×4 Array{Int64,2}:
  2  6  10  14
  3  7  11  15
  4  8  12  16
  1  5   9  13
 ```
 
-See also [`circshift!`](@ref).
+See also [`rotate!`](@ref).
 """
-function circshift(a::AbstractArray, shiftamt)
-    circshift!(similar(a), a, map(Integer, (shiftamt...,)))
+function rotate(a::AbstractArray, shiftamt)
+    rotate!(similar(a), a, map(Integer, (shiftamt...,)))
 end
 
 # Uses K-B-N summation

base/deprecated.jl

@@ -1704,6 +1704,10 @@ export hex2num
 @deprecate convert(::Type{String}, v::Vector{UInt8})          String(v)
 @deprecate convert(::Type{S}, g::UTF8proc.GraphemeIterator) where {S<:AbstractString}  convert(S, g.s)
 
+# Issue #19923
+@deprecate circshift rotate
+@deprecate circshift! rotate!
+
 # issue #5148, PR #23259
 # warning for `const` on locals should be changed to an error in julia-syntax.scm
 

base/exports.jl

@@ -430,8 +430,6 @@ export
     checkbounds,
     checkindex,
     circcopy!,
-    circshift,
-    circshift!,
     clamp!,
     colon,
     conj!,
@@ -511,6 +509,8 @@ export
     reshape,
     reverse!,
     reverse,
+    rotate,
+    rotate!,
     rot180,
     rotl90,
     rotr90,

base/multidimensional.jl

@@ -941,26 +941,27 @@ in the range of `Rdest`. The sizes of the two regions must match.
 """
 copy!(::AbstractArray, ::CartesianRange, ::AbstractArray, ::CartesianRange)
 
-# circshift!
-circshift!(dest::AbstractArray, src, ::Tuple{}) = copy!(dest, src)
+# rotate!
+rotate!(dest::AbstractArray, src, ::Tuple{}) = copy!(dest, src)
 """
-    circshift!(dest, src, shifts)
+    rotate!(dest, src, shifts)
 
-Circularly shift the data in `src`, storing the result in
-`dest`. `shifts` specifies the amount to shift in each dimension.
+Rotate the data in `src`, storing the result in `dest`. `shifts` specifies the amount to
+shift in each dimension. Positive shifts corresond to movement to the right, negative to
+the left, and 0 implies no movement.
 
 The `dest` array must be distinct from the `src` array (they cannot
 alias each other).
 
-See also [`circshift`](@ref).
+See also [`rotate`](@ref).
 """
-@noinline function circshift!(dest::AbstractArray{T,N}, src, shiftamt::DimsInteger) where {T,N}
+@noinline function rotate!(dest::AbstractArray{T,N}, src, shiftamt::DimsInteger) where {T,N}
     dest === src && throw(ArgumentError("dest and src must be separate arrays"))
     inds = indices(src)
     indices(dest) == inds || throw(ArgumentError("indices of src and dest must match (got $inds and $(indices(dest)))"))
-    _circshift!(dest, (), src, (), inds, fill_to_length(shiftamt, 0, Val(N)))
+    _rotate!(dest, (), src, (), inds, fill_to_length(shiftamt, 0, Val(N)))
 end
-circshift!(dest::AbstractArray, src, shiftamt) = circshift!(dest, src, (shiftamt...,))
+rotate!(dest::AbstractArray, src, shiftamt) = rotate!(dest, src, (shiftamt...,))
 
 # For each dimension, we copy the first half of src to the second half
 # of dest, and the second half of src to the first half of dest. This
@@ -971,14 +972,14 @@ circshift!(dest::AbstractArray, src, shiftamt) = circshift!(dest, src, (shiftamt
 # time; when all the dimensions have been filled in, you call `copy!`
 # for that block. In other words, in two dimensions schematically we
 # have the following call sequence (--> means a call):
-#   circshift!(dest, src, shiftamt) -->
-#     _circshift!(dest, src, ("first half of dim1",)) -->
-#       _circshift!(dest, src, ("first half of dim1", "first half of dim2")) --> copy!
-#       _circshift!(dest, src, ("first half of dim1", "second half of dim2")) --> copy!
-#     _circshift!(dest, src, ("second half of dim1",)) -->
-#       _circshift!(dest, src, ("second half of dim1", "first half of dim2")) --> copy!
-#       _circshift!(dest, src, ("second half of dim1", "second half of dim2")) --> copy!
-@inline function _circshift!(dest, rdest, src, rsrc,
+#   rotate!(dest, src, shiftamt) -->
+#     _rotate!(dest, src, ("first half of dim1",)) -->
+#       _rotate!(dest, src, ("first half of dim1", "first half of dim2")) --> copy!
+#       _rotate!(dest, src, ("first half of dim1", "second half of dim2")) --> copy!
+#     _rotate!(dest, src, ("second half of dim1",)) -->
+#       _rotate!(dest, src, ("second half of dim1", "first half of dim2")) --> copy!
+#       _rotate!(dest, src, ("second half of dim1", "second half of dim2")) --> copy!
+@inline function _rotate!(dest, rdest, src, rsrc,
                              inds::Tuple{AbstractUnitRange,Vararg{Any}},
                              shiftamt::Tuple{Integer,Vararg{Any}})
     ind1, d = inds[1], shiftamt[1]
@@ -987,11 +988,11 @@ circshift!(dest::AbstractArray, src, shiftamt) = circshift!(dest, src, (shiftamt
     r1, r2 = first(ind1):sf-1, sf:last(ind1)
     r3, r4 = first(ind1):sl, sl+1:last(ind1)
     tinds, tshiftamt = tail(inds), tail(shiftamt)
-    _circshift!(dest, (rdest..., r1), src, (rsrc..., r4), tinds, tshiftamt)
-    _circshift!(dest, (rdest..., r2), src, (rsrc..., r3), tinds, tshiftamt)
+    _rotate!(dest, (rdest..., r1), src, (rsrc..., r4), tinds, tshiftamt)
+    _rotate!(dest, (rdest..., r2), src, (rsrc..., r3), tinds, tshiftamt)
 end
 # At least one of inds, shiftamt is empty
-function _circshift!(dest, rdest, src, rsrc, inds, shiftamt)
+function _rotate!(dest, rdest, src, rsrc, inds, shiftamt)
     copy!(dest, CartesianRange(rdest), src, CartesianRange(rsrc))
 end
 
@@ -1038,7 +1039,7 @@ function circcopy!(dest, src)
     _circcopy!(dest, (), indsdest, src, (), indssrc)
 end
 
-# This uses the same strategy described above for _circshift!
+# This uses the same strategy described above for _rotate!
 @inline function _circcopy!(dest, rdest, indsdest::Tuple{AbstractUnitRange,Vararg{Any}},
                             src,  rsrc,  indssrc::Tuple{AbstractUnitRange,Vararg{Any}})
     indd1, inds1 = indsdest[1], indssrc[1]

doc/src/stdlib/arrays.md

@@ -104,8 +104,8 @@ Base.vcat
 Base.hcat
 Base.hvcat
 Base.flipdim
-Base.circshift
-Base.circshift!
+Base.rotate
+Base.rotate!
 Base.circcopy!
 Base.contains(::Function, ::Any, ::Any)
 Base.find(::Any)

test/arrayops.jl

@@ -568,13 +568,13 @@ end
     end
 end
 
-@testset "circshift" begin
-    @test circshift(1:5, -1) == circshift(1:5, 4) == circshift(1:5, -6) == [2,3,4,5,1]
-    @test circshift(1:5, 1) == circshift(1:5, -4) == circshift(1:5, 6)  == [5,1,2,3,4]
+@testset "rotate" begin
+    @test rotate(1:5, -1) == rotate(1:5, 4) == rotate(1:5, -6) == [2,3,4,5,1]
+    @test rotate(1:5, 1) == rotate(1:5, -4) == rotate(1:5, 6)  == [5,1,2,3,4]
     a = [1:5;]
-    @test_throws ArgumentError Base.circshift!(a, a, 1)
+    @test_throws ArgumentError Base.rotate!(a, a, 1)
     b = copy(a)
-    @test Base.circshift!(b, a, 1) == [5,1,2,3,4]
+    @test Base.rotate!(b, a, 1) == [5,1,2,3,4]
 end
 
 # unique across dim

test/offsetarray.jl

@@ -388,7 +388,7 @@ v = OffsetArray(rand(8), (-2,))
 @test A+A == OffsetArray(parent(A)+parent(A), A.offsets)
 @test A.*A == OffsetArray(parent(A).*parent(A), A.offsets)
 
-@test circshift(A, (-1,2)) == OffsetArray(circshift(parent(A), (-1,2)), A.offsets)
+@test rotate(A, (-1,2)) == OffsetArray(rotate(parent(A), (-1,2)), A.offsets)
 
 src = reshape(collect(1:16), (4,4))
 dest = OffsetArray(Array{Int}(4,4), (-1,1))

test/perf/threads/lbm3d/README

@@ -4,6 +4,6 @@ The Matlab/Octave version is from the website. The Julia version is
 rewritten in devectorized form with threading directives applied to
 the parallelizable code.
 
-The circshift! implementation needs work to support arbitrary
+The rotate! implementation needs work to support arbitrary
 dimensioned grids.
 

test/perf/threads/lbm3d/circshift.jl

@@ -1,14 +1,14 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
-# An in-place version of circshift. Needs generalization -- currently
+# An in-place version of rotate. Needs generalization -- currently
 # works only on a 3D hyperplane of a 4D array and supports only unit
 # shifts. Code needs refactoring to reduce duplication.
 
 using Match
 
 # a is the 4D array; index specifies which 3D hyperplane; vec
 # specifies the shifts (only 1 and -1)
-function circshift3d1!(a,index,vec)
+function rotate3d1!(a,index,vec)
     nx = size(a,1)
     ny = size(a,2)
     nz = size(a,3)

test/perf/threads/lbm3d/lbm3d.jl

@@ -9,7 +9,7 @@
 #               Iain Haslam, March 2006.
 #
 # Julia version: devectorized and threaded. The in-place
-# circshift implementation is needed because of issue #10317.
+# rotate implementation is needed because of issue #10317.
 # Despite that, GC time is ~22% of runtime. relax! and
 # calc_equi! are broken out because of issue #10718. The
 # threaded call form is used and the for loop form is is
@@ -172,7 +172,7 @@ function lbm3d(n)
         tic()
         # Propagate -- nearest and next-nearest neighbors
         for i = 2:19
-            circshift3d1!(F, i, prop_shifts[i-1])
+            rotate3d1!(F, i, prop_shifts[i-1])
         end
         tprop = tprop + toq()
 

test/reduce.jl

@@ -204,7 +204,7 @@ prod2(itr) = invoke(prod, Tuple{Any}, itr)
 @test maximum(collect(Int16(1):Int16(100))) === Int16(100)
 @test maximum(Int32[1,2]) === Int32(2)
 
-A = circshift(reshape(1:24,2,3,4), (0,1,1))
+A = rotate(reshape(1:24,2,3,4), (0,1,1))
 @test extrema(A,1) == reshape([(23,24),(19,20),(21,22),(5,6),(1,2),(3,4),(11,12),(7,8),(9,10),(17,18),(13,14),(15,16)],1,3,4)
 @test extrema(A,2) == reshape([(19,23),(20,24),(1,5),(2,6),(7,11),(8,12),(13,17),(14,18)],2,1,4)
 @test extrema(A,3) == reshape([(5,23),(6,24),(1,19),(2,20),(3,21),(4,22)],2,3,1)