Randomness consumption documentation

[meithecatte]

Most functions do not document how they use their Seed internally. On one hand, these are irrelevant implementation details, but on the other hand, if they use Seed::next, the relationship between the two results might not be obvious. For example, consider:

    let seed = malachite::random::EXAMPLE_SEED;
    let low = Natural::from(1000_u32);
    let high = Natural::from(10000_u32);

    let xs = uniform_random_natural_range(seed, low.clone(), high.clone());
    let ys = uniform_random_natural_range(seed.next(), low, high);

In one conceivable implementation of uniform_random_natural_range, there exists an n such that xs.skip(n) and ys generate the same sequence. As far as I can tell from a quick test eyeball, this is not actually the case. This is of course an extreme example, other issues could be much more subtle.

Clearly, more documented guarantees around this are necessary.

[mhogrefe]

Sorry for the delayed response. I need to think about the best way to document this. One thing I would recommend is to use seed.fork("some-secret") rather than using Seed::next. The forked seed will almost certainly not be the same as any seed used internally by Malachite.