Document that xorshift can't be seeded with zero

[Alexander Batischev]

When seeded with zero, xorshift is silently seeded with a different value:

rngs/rand_xorshift/src/lib.rs

Lines 86 to 91 in 7cda1f8

 // Xorshift cannot be seeded with 0 and we cannot return an Error, but 
 // also do not wish to panic (because a random seed can legitimately be 
 // 0); our only option is therefore to use a preset value. 
 if seed_u32.iter().all(|&x| x == 0) { 
     seed_u32 = [0xBAD_5EED, 0xBAD_5EED, 0xBAD_5EED, 0xBAD_5EED]; 
 } 

The docs don't mention this though.

When seeding from another RNG, the situation is even worse: if the seeding RNG keeps returning zeroes, xorshift's initialization will loop forever:

rngs/rand_xorshift/src/lib.rs

Lines 102 to 108 in 7cda1f8

 let mut b = [0u8; 16]; 
 loop { 
     rng.try_fill_bytes(&mut b[..])?; 
     if !b.iter().all(|&x| x == 0) { 
         break; 
     } 
 } 

from_rng is fallible, so it could perform a limited number of iterations and fail if it can't get a non-zero seed.

I think that, at the very least, these behaviours should be documented.

[Vinzent Steinberg]

I agree that the behavior for 0 seeds should be documented. However, I disagree that we should add special code for pathological RNG implementations that always return 0. Such behavior would break a lot of code in Rand, because rejection sampling is used in many algorithms.