deprecate ipermute! in favor of invpermute! (#25168)

Author: rfourquet

NEWS.md

@@ -880,6 +880,8 @@ Deprecated or removed
     (i.e. `Void <: T`). `isnull(x)` can be replaced with `x === nothing`
     and `unsafe_get`/`get` can be dropped or replaced with `coalesce`.
 
+  * `ipermute!` has been deprecated in favor of `invpermute!` ([#25168]).
+
   * `CartesianRange` has been renamed `CartesianIndices` ([#24715]).
 
   * `sub2ind` and `ind2sub` are deprecated in favor of using `CartesianIndices` and `LinearIndices` ([#24715]).

base/combinatorics.jl

@@ -101,7 +101,7 @@ to verify that `p` is a permutation.
 To return a new permutation, use `v[p]`. Note that this is generally faster than
 `permute!(v,p)` for large vectors.
 
-See also [`ipermute!`](@ref).
+See also [`invpermute!`](@ref).
 
 # Examples
 ```jldoctest
@@ -121,7 +121,7 @@ julia> A
 """
 permute!(a, p::AbstractVector) = permute!!(a, copymutable(p))
 
-function ipermute!!(a, p::AbstractVector{<:Integer})
+function invpermute!!(a, p::AbstractVector{<:Integer})
     count = 0
     start = 0
     while count < length(a)
@@ -145,7 +145,7 @@ function ipermute!!(a, p::AbstractVector{<:Integer})
 end
 
 """
-    ipermute!(v, p)
+    invpermute!(v, p)
 
 Like [`permute!`](@ref), but the inverse of the given permutation is applied.
 
@@ -155,7 +155,7 @@ julia> A = [1, 1, 3, 4];
 
 julia> perm = [2, 4, 3, 1];
 
-julia> ipermute!(A, perm);
+julia> invpermute!(A, perm);
 
 julia> A
 4-element Array{Int64,1}:
@@ -165,7 +165,7 @@ julia> A
  1
 ```
 """
-ipermute!(a, p::AbstractVector) = ipermute!!(a, copymutable(p))
+invpermute!(a, p::AbstractVector) = invpermute!!(a, copymutable(p))
 
 """
     invperm(v)

base/deprecated.jl

@@ -363,6 +363,9 @@ end
 
 @deprecate ipermutedims(A::AbstractArray,p) permutedims(A, invperm(p))
 
+# PR #25168
+@deprecate ipermute!(a, p::AbstractVector) invpermute!(a, p)
+
 # 18696
 function ($)(x, y)
     depwarn("`x \$ y` is deprecated.  use `xor(x, y)` or `x ⊻ y` instead.", :$)

base/exports.jl

@@ -459,7 +459,7 @@ export
     indmax,
     indmin,
     invperm,
-    ipermute!,
+    invpermute!,
     isassigned,
     isperm,
     issorted,

base/linalg/cholesky.jl

@@ -445,7 +445,7 @@ end
 
 function ldiv!(C::CholeskyPivoted{T}, B::StridedVector{T}) where T<:BlasFloat
     chkfullrank(C)
-    ipermute!(LAPACK.potrs!(C.uplo, C.factors, permute!(B, C.piv)), C.piv)
+    invpermute!(LAPACK.potrs!(C.uplo, C.factors, permute!(B, C.piv)), C.piv)
 end
 function ldiv!(C::CholeskyPivoted{T}, B::StridedMatrix{T}) where T<:BlasFloat
     chkfullrank(C)
@@ -455,7 +455,7 @@ function ldiv!(C::CholeskyPivoted{T}, B::StridedMatrix{T}) where T<:BlasFloat
     end
     LAPACK.potrs!(C.uplo, C.factors, B)
     for i=1:size(B, 2)
-        ipermute!(view(B, 1:n, i), C.piv)
+        invpermute!(view(B, 1:n, i), C.piv)
     end
     B
 end

doc/src/stdlib/arrays.md

@@ -169,7 +169,7 @@ Base.Random.randperm!
 Base.invperm
 Base.isperm
 Base.permute!(::Any, ::AbstractVector)
-Base.ipermute!
+Base.invpermute!
 Base.Random.randcycle
 Base.Random.randcycle!
 Base.Random.shuffle

test/combinatorics.jl

@@ -37,11 +37,11 @@ end
     @test !isperm(p)
 
     a = randcycle(10)
-    @test ipermute!(permute!([1:10;], a),a) == [1:10;]
+    @test invpermute!(permute!([1:10;], a),a) == [1:10;]
 
     # PR 12785
     let ai = 2:-1:1
-        @test ipermute!(permute!([1, 2], ai), ai) == [1, 2]
+        @test invpermute!(permute!([1, 2], ai), ai) == [1, 2]
     end
 end
 

test/sorting.jl

@@ -172,7 +172,7 @@ Base.step(r::ConstantRange) = 0
         permute!(c, ix)
         @test c == b
 
-        ipermute!(c, ix)
+        invpermute!(c, ix)
         @test c == a
 
         c = sort(a, alg=alg, lt=(>))
@@ -245,7 +245,7 @@ end
             c = copy(v)
             permute!(c, pi)
             @test c == si
-            ipermute!(c, pi)
+            invpermute!(c, pi)
             @test c == v
 
             # stable algorithms
@@ -256,7 +256,7 @@ end
                 s = copy(v)
                 permute!(s, p)
                 @test s == si
-                ipermute!(s, p)
+                invpermute!(s, p)
                 @test s == v
             end
 
@@ -269,7 +269,7 @@ end
                 s = copy(v)
                 permute!(s, p)
                 @test s == si
-                ipermute!(s, p)
+                invpermute!(s, p)
                 @test s == v
             end
         end