Introduce shuffleList and shuffleListM

[lehins]

As it was described in #139 this PR implements the most basic version of random list shuffling, both stateful and pure implementations.

The way the shuffling is achieved is somewhat similar to the implementation in QuickCheck. There are better ways, but the one that I know of requires a mutable array, which would make a dependency footprint or implementation quite a bit more complicated.

We can experiment with performance and quality of alternative implementations for random-1.3, whenever that will come. Unless someone is willing to provide a better implementation (with some becnhmarks) soon enough as a PR into this branch, I think current implementation is sufficiently good enough for the initial version.

Changes in this PR are non-breaking, so I'll happily backport them into a minor random-1.2.2 release.

As a nice extra this PR also contains a pure implementation of uniformList

[Bodigrim]

LGTM!

[Shimuuar]

In general +1 but I have few comments. What are stability guarantees for the shuffle? Do we promise to change algorithm output only on major updates?

Bias

Shuffle is very slightly biased. For example let look at shuffle of [a,b]. List of indices (uniformListM n gen) will yield 2^N ties out of 2^2N possible options. Sort is stable so [a,b] will have probability of 1/2 + 2^{-N} and [b,a] — 1/2 - 2^{-N}.
Bias is negligible ~5e-20 in 64-bit case and small ~2e-10 in 32-bit case.

Analysis for n-element list is more complicated. Probability of having at least one collision in indices is subject to birthday paradox. So maybe it's possible to detect bias with 32-bit Ints. And yes Fisher-Yates shuffle is unbiased, has O(n) complexity but requires in-place mutation. It's awfully inconvenient to not having access to proper arrays

P.S. I'm not sure that uniformList warrants inclusion since we have replicateM but I'm not against it

[lehins]

Shuffle is very slightly biased. ..... It's awfully inconvenient to not having access to proper arrays

That's precisely why I didn't bother writing it using mutable arrays. I don't think this issue alone warrants a dependency on primitive.

What are stability guarantees for the shuffle? Do we promise to change algorithm output only on major updates?

Yes. That would be the case. I would rather not change the underlying semantics on non-breaking version updates.

[Shimuuar]

I'm on a fence about this. Arrays are after all very basic functionality. It's first time we run into algorithm that requires arrays. Will it be another one? Something that requires lookup tables, such as mwc-random's normal.

[Bodigrim]

If you like pain, you can use naked Data.Array.Byte, it should be enough to shuffle a list of indices. Otherwise depending on array is less of a burden than primitive, because array is preinstalled as a boot package anyways.

[lehins]

Otherwise depending on array is less of a burden

I'd rather use my own redefinition of data Array a = Array (Array# a) then suffer through using array package 😄