add mutating versions of randperm & randcycle (#22723)

NEWS.md

@@ -75,6 +75,10 @@ This section lists changes that do not have deprecation warnings.
     `@everywhere include_string(Main, $(read("filename", String)), "filename")`.
     Improving upon this API is left as an opportunity for packages.
 
+  * `randperm(n)` and `randcycle(n)` now always return a `Vector{Int}` (independent of
+    the type of `n`). Use the corresponding mutating functions `randperm!` and `randcycle!`
+    to control the array type ([#22723]).
+
 Library improvements
 --------------------
 
@@ -128,6 +132,9 @@ Library improvements
   * `Diagonal` is now parameterized on the type of the wrapped vector. This allows
     for `Diagonal` matrices with arbitrary `AbstractVector`s ([#22718]).
 
+  * Mutating versions of `randperm` and `randcycle` have been added:
+    `randperm!` and `randcycle!` ([#22723]).
+
 Compiler/Runtime improvements
 -----------------------------
 

base/exports.jl

@@ -508,7 +508,9 @@ export
     prod,
     promote_shape,
     randcycle,
+    randcycle!,
     randperm,
+    randperm!,
     randsubseq!,
     randsubseq,
     range,

base/random.jl

@@ -12,9 +12,10 @@ export srand,
        randexp, randexp!,
        bitrand,
        randstring,
-       randsubseq,randsubseq!,
-       shuffle,shuffle!,
-       randperm, randcycle,
+       randsubseq, randsubseq!,
+       shuffle, shuffle!,
+       randperm, randperm!,
+       randcycle, randcycle!,
        AbstractRNG, MersenneTwister, RandomDevice,
        GLOBAL_RNG, randjump
 
@@ -1789,30 +1790,47 @@ shuffle(a::AbstractArray) = shuffle(GLOBAL_RNG, a)
 
 Construct a random permutation of length `n`. The optional `rng` argument specifies a random
 number generator (see [Random Numbers](@ref)).
-To randomly permute a arbitrary vector, see [`shuffle`](@ref)
+To randomly permute an arbitrary vector, see [`shuffle`](@ref)
 or [`shuffle!`](@ref).
 
 # Examples
 ```jldoctest
-julia> rng = MersenneTwister(1234);
+julia> randperm(MersenneTwister(1234), 4)
+4-element Array{Int64,1}:
+ 2
+ 1
+ 4
+ 3
+```
+"""
+randperm(r::AbstractRNG, n::Integer) = randperm!(r, Vector{Int}(n))
+randperm(n::Integer) = randperm(GLOBAL_RNG, n)
+
+"""
+    randperm!([rng=GLOBAL_RNG,] A::Array{<:Integer})
+
+Construct in `A` a random permutation of length `length(A)`. The
+optional `rng` argument specifies a random number generator (see
+[Random Numbers](@ref)). To randomly permute an arbitrary vector, see
+[`shuffle`](@ref) or [`shuffle!`](@ref).
 
-julia> randperm(rng, 4)
+# Examples
+```jldoctest
+julia> randperm!(MersenneTwister(1234), Vector{Int}(4))
 4-element Array{Int64,1}:
  2
  1
  4
  3
 ```
 """
-function randperm(r::AbstractRNG, n::Integer)
-    a = Vector{typeof(n)}(n)
+function randperm!(r::AbstractRNG, a::Array{<:Integer})
+    n = length(a)
     @assert n <= Int64(2)^52
-    if n == 0
-       return a
-    end
+    n == 0 && return a
     a[1] = 1
     mask = 3
-    @inbounds for i = 2:Int(n)
+    @inbounds for i = 2:n
         j = 1 + rand_lt(r, i, mask)
         if i != j # a[i] is uninitialized (and could be #undef)
             a[i] = a[j]
@@ -1822,7 +1840,9 @@ function randperm(r::AbstractRNG, n::Integer)
     end
     return a
 end
-randperm(n::Integer) = randperm(GLOBAL_RNG, n)
+
+randperm!(a::Array{<:Integer}) = randperm!(GLOBAL_RNG, a)
+
 
 """
     randcycle([rng=GLOBAL_RNG,] n::Integer)
@@ -1832,9 +1852,29 @@ argument specifies a random number generator, see [Random Numbers](@ref).
 
 # Examples
 ```jldoctest
-julia> rng = MersenneTwister(1234);
+julia> randcycle(MersenneTwister(1234), 6)
+6-element Array{Int64,1}:
+ 3
+ 5
+ 4
+ 6
+ 1
+ 2
+```
+"""
+randcycle(r::AbstractRNG, n::Integer) = randcycle!(r, Vector{Int}(n))
+randcycle(n::Integer) = randcycle(GLOBAL_RNG, n)
+
+"""
+    randcycle!([rng=GLOBAL_RNG,] A::Array{<:Integer})
 
-julia> randcycle(rng, 6)
+Construct in `A` a random cyclic permutation of length `length(A)`.
+The optional `rng` argument specifies a random number generator, see
+[Random Numbers](@ref).
+
+# Examples
+```jldoctest
+julia> randcycle!(MersenneTwister(1234), Vector{Int}(6))
 6-element Array{Int64,1}:
  3
  5
@@ -1844,20 +1884,21 @@ julia> randcycle(rng, 6)
  2
 ```
 """
-function randcycle(r::AbstractRNG, n::Integer)
-    a = Vector{typeof(n)}(n)
+function randcycle!(r::AbstractRNG, a::Array{<:Integer})
+    n = length(a)
     n == 0 && return a
     @assert n <= Int64(2)^52
     a[1] = 1
     mask = 3
-    @inbounds for i = 2:Int(n)
+    @inbounds for i = 2:n
         j = 1 + rand_lt(r, i-1, mask)
         a[i] = a[j]
         a[j] = i
         i == 1+mask && (mask = 2mask + 1)
     end
     return a
 end
-randcycle(n::Integer) = randcycle(GLOBAL_RNG, n)
+
+randcycle!(a::Array{<:Integer}) = randcycle!(GLOBAL_RNG, a)
 
 end # module

doc/src/stdlib/arrays.md

@@ -157,11 +157,13 @@ Base.sum_kbn
 
 ```@docs
 Base.Random.randperm
+Base.Random.randperm!
 Base.invperm
 Base.isperm
 Base.permute!(::Any, ::AbstractVector)
 Base.ipermute!
 Base.Random.randcycle
+Base.Random.randcycle!
 Base.Random.shuffle
 Base.Random.shuffle!
 Base.reverse

test/random.jl

@@ -459,9 +459,17 @@ let mta = MersenneTwister(42), mtb = MersenneTwister(42)
     @test sort!(randperm(10)) == sort!(shuffle(1:10)) == collect(1:10)
     @test randperm(mta,big(10)) == randperm(mtb,big(10)) # cf. #16376
     @test randperm(0) == []
+    @test eltype(randperm(UInt(1))) === Int
     @test_throws ErrorException randperm(-1)
 
+    A, B = Vector{Int}(10), Vector{Int}(10)
+    @test randperm!(mta, A) == randperm!(mtb, B)
+    @test randperm!(A) === A
+
     @test randcycle(mta,10) == randcycle(mtb,10)
+    @test eltype(randcycle(UInt(1))) === Int
+    @test randcycle!(mta, A) == randcycle!(mtb, B)
+    @test randcycle!(A) === A
 
     @test sprand(mta,1,1,0.9) == sprand(mtb,1,1,0.9)
     @test sprand(mta,10,10,0.3) == sprand(mtb,10,10,0.3)