Reference

shuffle([rng=GLOBAL_RNG,], c, s::AbstractShuffle=RandomShuffle())

shuffle collection c using shuffling algorithm s. To shuffle c in-place, see shuffle!. A random-number generator rng may be supplied for random shuffling algorithms.

Examples

julia> mt = MersenneTwister(1234);

julia> shuffle(mt, [1, 2, 3, 4, 5, 6, 7, 8], GilbertShannonReeds())
8-element Vector{Int64}:
 6
 7
 1
 2
 8
 3
 4
 5

julia> shuffle([6, 5, 4, 3, 2, 1], Faro{:in}())
6-element Vector{Int64}:
 3
 6
 2
 5
 1
 4

shuffle!([rng=GLOBAL_RNG,], c, s::AbstractShuffle=RandomShuffle())

shuffle collection c in-place using shuffling algorithm s. A random-number generator rng may be supplied for random shuffling algorithms.

Examples

julia> mt = MersenneTwister(1234);

julia> a = collect(1:6);

julia> shuffle!(mt, a); a
6-element Vector{Int64}:
 2
 1
 3
 6
 4
 5

julia> shuffle!(a, Faro{:out}()); a
6-element Vector{Int64}:
 2
 6
 1
 4
 3
 5

nshuffle([rng=GLOBAL_RNG,], c, n::Integer, s::AbstractShuffle=RandomShuffle())

shuffle collection c n times using shuffling algorithm s. A random-number generator rng may be supplied for random shuffling algorithms. To shuffle c in-place see nshuffle!

Examples

julia> nshuffle(collect(1:8), 3, Faro{:in}())
8-element Vector{Int64}:
 8
 7
 6
 5
 4
 3
 2
 1

nshuffle!([rng=GLOBAL_RNG,], c, n::Integer, s::AbstractShuffle=RandomShuffle())

shuffle collection c in-place n times using shuffling algorithm s. A random-number generator rng may be supplied for random shuffling algorithms.

Examples

julia> mt = MersenneTwister(1234);

julia> a = collect(1:7);

julia> nshuffle!(mt, a, 3, GilbertShannonReeds()); a
7-element Vector{Int64}:
 5
 6
 1
 7
 2
 3
 4

AbstractShuffle

Supertype for AbstractDeterministicShuffle and AbstractRandomShuffle.

Implementation

New shuffling algorithm types should be sub types of either AbstractDeterministicShuffle or AbstractRandomShuffle. If an algorithm can be defined in-place, only shuffle! needs to be extended. shuffle, nshuffle and nshuffle! will make a copy / repeatedly call shuffle! as needed. If the algorithm can not be defined in-place, define shuffle and nshuffle!. nshuffle will make a copy and call nshuffle!.

AbstractDeterministicShuffle <: AbstractShuffle

Supertype for fully deterministic shuffle algorithms such as Faro and Cut.

Implementation

New deterministic shuffling algorithms should implement either shuffle or shuffle!, as appropriate. The new shuffle method should take a collection to be shuffled as the first argument and an instance of the new shuffling algorithm type as the second argument.

For example:

struct MyShuffle <: AbstractDeterministicShuffle
    parameter
end

function shuffle(c::AbstractArray, s::MyShuffle, prealloc_out=similar(c))
    # Do the shuffling

    return prealloc_out
end

Pre-allocating the output makes it easy to also write an efficient nshuffle! function for algorithms that cannot be written in-place.

See also: AbstractShuffle

Faro{S}
Weave{S}

Type with no fields representing the Faro (weave) card shuffle where S can be :in for an in-shuffle or :out for an out-shuffle.

See singleton instances infaro, outfaro, inweave, outweave.

Examples

julia> shuffle([1, 2, 3, 4, 5, 6, 7, 8], Faro{:out}())
8-element Vector{Int64}:
 1
 5
 2
 6
 3
 7
 4
 8

julia> nshuffle(collect(1:52), 26, inweave) == collect(52:-1:1)
true

infaro

The singleton instance of type Faro{:in}

outfaro

The singleton instance of type Faro{:out}

inweave

Alias for infaro.

outweave

Alias for outfaro.

Cut(n::Integer)

represents a cut at n, meaning elements up to and including n are moved to the bottom or end of a collection, while the rest shift up to the beginning.

No in-place shuffle! or nshuffle! exist for this shuffling type.

Examples

julia> shuffle([1, 2, 3, 4, 5, 6, 7], Cut(3))
7-element Vector{Int64}:
 4
 5
 6
 7
 1
 2
 3

AbstractRandomShuffle <: AbstractShuffle

Supertype for partly or fully random shuffle algorithms such as RandomShuffle and GilbertShannonReeds.

Implementation

New random shuffling algorithms should implement either shuffle or shuffle!, as appropriate. The new shuffle method should take a Random.AbstractRNG as the first argument, a collection to be shuffled as the second argument and an instance of the new shuffling algorithm type as the third argument.

For example:

struct MyShuffle <: AbstractRandomShuffle end

function shuffle!(r::AbstractRNG, c, s::MyShuffle)
    # Do the shuffling, passing r to any random number generating functions

    return c
end

See also: AbstractShuffle

RandomShuffle

type with no fields representing a completely random shuffle, which is guaranteed to be equivalent to Random.shuffle).

This algorithm is set as the default. See DEFAULTS and has the singleton instance randshuffle.

Examples

julia> mt1 = MersenneTwister(1234); mt2 = MersenneTwister(1234);

julia> shuffle(mt1, 1:10, randshuffle) == Random.shuffle(mt2, 1:10)
true

randshuffle

The singleton instance of type RandomShuffle

GilbertShannonReeds

type with no fields representing the Gilbert-Shannon-Reeds model of card shuffling. See singleton instance gsrshuffle.

An in-place shuffle! is not implemented for this algorithm. However, an in-place nshuffle! is implemented.

Examples

julia> mt = MersenneTwister(1234);

julia> shuffle(mt, 1:7, gsrshuffle)
7-element Vector{Int64}:
 5
 6
 1
 2
 7
 3
 4

gsrshuffle

The singleton instance of type GilbertShannonReeds.

DEFAULTS

binding to a mutable struct containing the default shuffling algorithm. RandomShuffle is set initially.

Examples

julia> Shuffle.DEFAULTS.shuffle
RandomShuffle()

julia> mt1 = MersenneTwister(1234); mt2 = MersenneTwister(1234);

julia> shuffle(mt1, collect(1:100)) == shuffle(mt2, collect(1:100), RandomShuffle())
true

julia> Shuffle.DEFAULTS.shuffle = infaro; Shuffle.DEFAULTS.shuffle
Faro{:in}()

julia> shuffle([1, 2, 3, 4, 5, 6, 7, 8])
8-element Vector{Int64}:
 5
 1
 6
 2
 7
 3
 8
 4

julia> Shuffle.DEFAULTS.shuffle = RandomShuffle();