From 45acdb734c79bee3065cfffdcebcc2dd60347b6e Mon Sep 17 00:00:00 2001
From: Rafael Fourquet <fourquet.rafael@gmail.com>
Date: Mon, 18 Dec 2017 21:14:18 +0100
Subject: [PATCH] deprecate ipermute! in favor of invpermute!

---
 NEWS.md                 |  2 ++
 base/combinatorics.jl   | 10 +++++-----
 base/deprecated.jl      |  3 +++
 base/exports.jl         |  2 +-
 base/linalg/cholesky.jl |  4 ++--
 test/combinatorics.jl   |  4 ++--
 test/sorting.jl         |  8 ++++----
 7 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index e61876eddecfab..106cad1ab58ee1 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -816,6 +816,8 @@ Deprecated or removed
     and `unsafe_get`/`get` can be dropped or replaced with `coalesce`.
     `NullException` has been removed.
 
+  * `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]).
diff --git a/base/combinatorics.jl b/base/combinatorics.jl
index 7b8b79fc16bfdb..369832e28dd186 100644
--- a/base/combinatorics.jl
+++ b/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)
diff --git a/base/deprecated.jl b/base/deprecated.jl
index 11751f36ad6fb2..01d7763e42bdc5 100644
--- a/base/deprecated.jl
+++ b/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::AbstractVector)
+
 # 18696
 function ($)(x, y)
     depwarn("`x \$ y` is deprecated.  use `xor(x, y)` or `x ⊻ y` instead.", :$)
diff --git a/base/exports.jl b/base/exports.jl
index f9b2d14c11db33..47a93cde2c5ff2 100644
--- a/base/exports.jl
+++ b/base/exports.jl
@@ -459,7 +459,7 @@ export
     indmax,
     indmin,
     invperm,
-    ipermute!,
+    invpermute!,
     isassigned,
     isperm,
     issorted,
diff --git a/base/linalg/cholesky.jl b/base/linalg/cholesky.jl
index 0e36604a6f67ed..92e8b814385dbe 100644
--- a/base/linalg/cholesky.jl
+++ b/base/linalg/cholesky.jl
@@ -432,7 +432,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)
@@ -442,7 +442,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
diff --git a/test/combinatorics.jl b/test/combinatorics.jl
index 9713d89fa90358..11a5a3d96c6d47 100644
--- a/test/combinatorics.jl
+++ b/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
 
diff --git a/test/sorting.jl b/test/sorting.jl
index 002b3394b13727..7384459a0c8e36 100644
--- a/test/sorting.jl
+++ b/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