change argument order for rand! (fix JuliaLang#8246)

The API to fill randomly an array A is changed
from rand!([rng], [::Range], A) to rand!([rng], A, [::AbstractArray]).
Enabling [::AbstractArray] instead of only [::Range] depended on choosing first
the argument order.

base/deprecated.jl

@@ -220,3 +220,6 @@ const String = AbstractString
 @deprecate zero{T}(x::Ptr{T})      Ptr{T}(0)
 @deprecate one{T}(::Type{Ptr{T}})  Ptr{T}(1)
 @deprecate one{T}(x::Ptr{T})       Ptr{T}(1)
+
+@deprecate rand!(r::Range, A::AbstractArray) rand!(A, r)
+@deprecate rand!(mt::MersenneTwister, r::Range, A::AbstractArray) rand!(mt, A, r)

base/random.jl

@@ -151,7 +151,7 @@ rand(T::Type, d1::Int, dims::Int...) = rand(T, tuple(d1, dims...))
 rand!(A::AbstractArray) = rand!(GLOBAL_RNG, A)
 
 rand(r::AbstractArray) = rand(GLOBAL_RNG, r)
-rand!(r::Range, A::AbstractArray) = rand!(GLOBAL_RNG, r, A)
+rand!(A::AbstractArray, r::AbstractArray) = rand!(GLOBAL_RNG, A, r)
 
 rand(r::AbstractArray, dims::Dims) = rand(GLOBAL_RNG, r, dims)
 rand(r::AbstractArray, dims::Int...) = rand(GLOBAL_RNG, r, dims)
@@ -233,7 +233,7 @@ rand!(r::MersenneTwister, A::AbstractArray{Float64}) = rand_AbstractArray_Float6
 fill_array!(s::DSFMT_state, A::Ptr{Float64}, n::Int, ::Type{CloseOpen}) = dsfmt_fill_array_close_open!(s, A, n)
 fill_array!(s::DSFMT_state, A::Ptr{Float64}, n::Int, ::Type{Close1Open2}) = dsfmt_fill_array_close1_open2!(s, A, n)
 
-function rand!{I<:FloatInterval}(r::MersenneTwister, A::Array{Float64}, n=length(A), ::Type{I}=CloseOpen)
+function rand!{I<:FloatInterval}(r::MersenneTwister, A::Array{Float64}, n::Int=length(A), ::Type{I}=CloseOpen)
     # depending on the alignment of A, the data written by fill_array! may have
     # to be left-shifted by up to 15 bytes (cf. unsafe_copy! below) for
     # reproducibility purposes;
@@ -299,7 +299,7 @@ end
 rand!{T<:Union(Float16, Float32)}(r::MersenneTwister, A::Array{T}) = rand!(r, A, CloseOpen)
 
 
-function rand!(r::MersenneTwister, A::Array{UInt128}, n=length(A))
+function rand!(r::MersenneTwister, A::Array{UInt128}, n::Int=length(A))
     Af = pointer_to_array(convert(Ptr{Float64}, pointer(A)), 2n)
     i = n
     while true
@@ -403,27 +403,24 @@ rand{T<:Union(Signed,Unsigned,Bool,Char)}(mt::MersenneTwister, r::UnitRange{T})
 # (e.g. r is a range 0:2:8 or a vector [2, 3, 5, 7])
 rand(mt::MersenneTwister, r::AbstractArray) = @inbounds return r[rand(mt, 1:length(r))]
 
-function rand!(mt::MersenneTwister, g::RandIntGen, A::AbstractArray)
+function rand!(mt::MersenneTwister, A::AbstractArray, g::RandIntGen)
     for i = 1 : length(A)
         @inbounds A[i] = rand(mt, g)
     end
     return A
 end
 
-rand!{T<:Union(Signed,Unsigned,Bool,Char)}(mt::MersenneTwister, r::UnitRange{T}, A::AbstractArray) = rand!(mt, RandIntGen(r), A)
+rand!{T<:Union(Signed,Unsigned,Bool,Char)}(mt::MersenneTwister, A::AbstractArray, r::UnitRange{T}) = rand!(mt, A, RandIntGen(r))
 
-rand!(mt::MersenneTwister, r::Range, A::AbstractArray) = _rand!(mt, r, A)
-
-# TODO: this more general version is "disabled" until #8246 is resolved
-function _rand!(mt::MersenneTwister, r::AbstractArray, A::AbstractArray)
+function rand!(mt::MersenneTwister, A::AbstractArray, r::AbstractArray)
     g = RandIntGen(1:(length(r)))
     for i = 1 : length(A)
         @inbounds A[i] = r[rand(mt, g)]
     end
     return A
 end
 
-rand{T}(mt::MersenneTwister, r::AbstractArray{T}, dims::Dims) = _rand!(mt, r, Array(T, dims))
+rand{T}(mt::MersenneTwister, r::AbstractArray{T}, dims::Dims) = rand!(mt, Array(T, dims), r)
 rand(mt::MersenneTwister, r::AbstractArray, dims::Int...) = rand(mt, r, dims)
 
 ## random BitArrays (AbstractRNG)

doc/stdlib/base.rst

@@ -4081,13 +4081,9 @@ A ``MersenneTwister`` RNG can generate random numbers of the following types: ``
 
    ``S`` defaults to ``Float64``.
 
-.. function:: rand!([rng], A)
+.. function:: rand!([rng], A ,[coll])
 
-   Populate the array A with random values.
-
-.. function:: rand!([rng], r, A)
-
-   Populate the array A with random values drawn uniformly from the range ``r``.
+   Populate the array A with random values. If the indexable collection ``coll`` is specified, the values are picked randomly from ``coll``. This is equivalent to ``copy!(A, rand(rng, coll, size(A)))`` or ``copy!(A, rand(rng, eltype(A), size(A)))`` but without allocating a new array.
 
 .. function:: randbool([rng], [dims...])
 

test/bitarray.jl

@@ -46,7 +46,7 @@ for (sz,T) in allsizes
     @test isequal(convert(AbstractArray{Float64,ndims(b1)}, b1),
                   convert(AbstractArray{Float64,ndims(b1)}, bitunpack(b1)))
 
-    i1 = rand!(false:true, zeros(Bool, sz...))
+    i1 = rand!(zeros(Bool, sz...), false:true)
     @test isequal(bitunpack(bitpack(i1)), i1)
 end
 

test/perf/sort/perf.jl

@@ -8,7 +8,7 @@ include("../perfutil.jl")
 sorts = [InsertionSort, QuickSort, MergeSort, HeapSort, RadixSort, TimSort]
 
 randstr_fn!(str_len::Int) = d -> (for i = 1:length(d); d[i] = randstring(str_len); end; d)
-randint_fn!(m::Int) = d -> rand!(1:m,d)
+randint_fn!(m::Int) = d -> rand!(d, 1:m)
 
 # If we're reporting to codespeed, only do a few tests.
 if codespeed

test/random.jl

@@ -35,14 +35,14 @@ rand!(MersenneTwister(0), A)
 let mt = MersenneTwister()
     srand(mt)
     @test rand(mt, 0:3:1000) in 0:3:1000
-    @test issubset(rand!(mt, 0:3:1000, Array(Int, 100)), 0:3:1000)
+    @test issubset(rand!(mt, Array(Int, 100), 0:3:1000), 0:3:1000)
     coll = Any[2, UInt128(128), big(619), "string", 'c']
     @test rand(mt, coll) in coll
     @test issubset(rand(mt, coll, 2, 3), coll)
 
     # check API with default RNG:
     rand(0:3:1000)
-    rand!(0:3:1000, Array(Int, 100))
+    rand!(Array(Int, 100), 0:3:1000)
     rand(coll)
     rand(coll, 2, 3)
 end
@@ -253,3 +253,15 @@ let mt = MersenneTwister()
         @test A[end-4:end] == [0.49508297796349776,0.3408340446375888,0.3211229457075784,0.9103565379264364,0.16456579813368521]
     end
 end
+
+# test rand! API: rand!([rng], A, [coll])
+let mt = MersenneTwister(0)
+    for T in [Base.IntTypes..., Float16, Float32, Float64]
+        for A in (Array(T, 5), Array(T, 2, 2))
+            rand!(A)
+            rand!(mt, A)
+            rand!(A, T[1,2,3])
+            rand!(mt, A, T[1,2,3])
+        end
+    end
+end