Random: make randperm! and randcycle! accept AbstractArray (JuliaLang#58596)

Author: nsajko

NEWS.md

@@ -61,6 +61,10 @@ Standard library changes
 
 #### Profile
 
+#### Random
+
+* `randperm!` and `randcycle!` now support non-`Array` `AbstractArray` inputs, assuming they are mutable and their indices are one-based ([#58596]).
+
 #### REPL
 
 * The display of `AbstractChar`s in the main REPL mode now includes LaTeX input information like what is shown in help mode ([#58181]).

stdlib/Random/src/misc.jl

@@ -297,13 +297,16 @@ randperm(r::AbstractRNG, n::T) where {T <: Integer} = randperm!(r, Vector{T}(und
 randperm(n::Integer) = randperm(default_rng(), n)
 
 """
-    randperm!([rng=default_rng(),] A::Array{<:Integer})
+    randperm!([rng=default_rng(),] A::AbstractArray{<: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).
 
+!!! compat "Julia 1.13"
+    `A isa Array` was required prior to Julia v1.13.
+
 # Examples
 ```jldoctest
 julia> randperm!(Xoshiro(123), Vector{Int}(undef, 4))
@@ -314,8 +317,9 @@ julia> randperm!(Xoshiro(123), Vector{Int}(undef, 4))
  3
 ```
 """
-function randperm!(r::AbstractRNG, a::Array{<:Integer})
+function randperm!(r::AbstractRNG, a::AbstractArray{<:Integer})
     # keep it consistent with `shuffle!` and `randcycle!` if possible
+    Base.require_one_based_indexing(a)
     n = length(a)
     @assert n <= Int64(2)^52
     n == 0 && return a
@@ -332,7 +336,7 @@ function randperm!(r::AbstractRNG, a::Array{<:Integer})
     return a
 end
 
-randperm!(a::Array{<:Integer}) = randperm!(default_rng(), a)
+randperm!(a::AbstractArray{<:Integer}) = randperm!(default_rng(), a)
 
 
 ## randcycle & randcycle!
@@ -370,7 +374,7 @@ randcycle(r::AbstractRNG, n::T) where {T <: Integer} = randcycle!(r, Vector{T}(u
 randcycle(n::Integer) = randcycle(default_rng(), n)
 
 """
-    randcycle!([rng=default_rng(),] A::Array{<:Integer})
+    randcycle!([rng=default_rng(),] A::AbstractArray{<:Integer})
 
 Construct in `A` a random cyclic permutation of length `n = length(A)`.
 The optional `rng` argument specifies a random number generator, see
@@ -382,6 +386,9 @@ which are sampled uniformly.  If `A` is empty, `randcycle!` leaves it unchanged.
 
 [`randcycle`](@ref) is a variant of this function that allocates a new vector.
 
+!!! compat "Julia 1.13"
+    `A isa Array` was required prior to Julia v1.13.
+
 # Examples
 ```jldoctest
 julia> randcycle!(Xoshiro(123), Vector{Int}(undef, 6))
@@ -394,8 +401,9 @@ julia> randcycle!(Xoshiro(123), Vector{Int}(undef, 6))
  1
 ```
 """
-function randcycle!(r::AbstractRNG, a::Array{<:Integer})
+function randcycle!(r::AbstractRNG, a::AbstractArray{<:Integer})
     # keep it consistent with `shuffle!` and `randperm!` if possible
+    Base.require_one_based_indexing(a)
     n = length(a)
     @assert n <= Int64(2)^52
     n == 0 && return a
@@ -411,4 +419,4 @@ function randcycle!(r::AbstractRNG, a::Array{<:Integer})
     return a
 end
 
-randcycle!(a::Array{<:Integer}) = randcycle!(default_rng(), a)
+randcycle!(a::AbstractArray{<:Integer}) = randcycle!(default_rng(), a)

stdlib/Random/test/runtests.jl

@@ -554,6 +554,14 @@ end
     @test randcycle!(mta, A) == randcycle!(mtb, B)
     @test randcycle!(A) === A
 
+    @testset "non-`Array` `randperm!` and `randcycle!`" begin
+        x, y = Memory{Int}(undef, 10), Memory{Int}(undef, 10)
+        @test randperm!(mta, x) == randperm!(mtb, y)
+        @test randperm!(x) === x
+        @test randcycle!(mta, x) == randcycle!(mtb, y)
+        @test randcycle!(x) === x
+    end
+
     let p = randcycle(UInt16(10))
         @test typeof(p) ≡ Vector{UInt16}
         @test sort!(p) == 1:10