Struct UniformInt

struct UniformInt<X> { ... }

The back-end implementing UniformSampler for integer types.

Unless you are implementing UniformSampler for your own type, this type should not be used directly, use Uniform instead.

Implementation notes

For simplicity, we use the same generic struct UniformInt<X> for all integer types X. This gives us only one field type, X; to store unsigned values of this size, we take use the fact that these conversions are no-ops.

For a closed range, the number of possible numbers we should generate is range = (high - low + 1). To avoid bias, we must ensure that the size of our sample space, zone, is a multiple of range; other values must be rejected (by replacing with a new random sample).

As a special case, we use range = 0 to represent the full range of the result type (i.e. for new_inclusive($ty::MIN, $ty::MAX)).

The optimum zone is the largest product of range which fits in our (unsigned) target type. We calculate this by calculating how many numbers we must reject: reject = (MAX + 1) % range = (MAX - range + 1) % range. Any (large) product of range will suffice, thus in sample_single we multiply by a power of 2 via bit-shifting (faster but may cause more rejections).

The smallest integer PRNGs generate is u32. For 8- and 16-bit outputs we use u32 for our zone and samples (because it's not slower and because it reduces the chance of having to reject a sample). In this case we cannot store zone in the target type since it is too large, however we know ints_to_reject < range <= $uty::MAX.

An alternative to using a modulus is widening multiply: After a widening multiply by range, the result is in the high word. Then comparing the low word against zone makes sure our distribution is uniform.

Bias

Unless the unbiased feature flag is used, outputs may have a small bias. In the worst case, bias affects 1 in 2^n samples where n is 56 (i8 and u8), 48 (i16 and u16), 96 (i32 and u32), 64 (i64 and u64), 128 (i128 and u128).

Implementations

impl UniformSampler for UniformInt<i128>

fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample<R: Rng + ?Sized>(self: &Self, rng: &mut R) -> <Self as >::X

Sample from distribution, Lemire's method, unbiased

fn sample_single<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample single value, Canon's method, biased

In the worst case, bias affects 1 in 2^n samples where n is 56 (i8), 48 (i16), 96 (i32), 64 (i64), 128 (i128).

impl UniformSampler for UniformInt<i16>

fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample<R: Rng + ?Sized>(self: &Self, rng: &mut R) -> <Self as >::X

Sample from distribution, Lemire's method, unbiased

fn sample_single<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample single value, Canon's method, biased

In the worst case, bias affects 1 in 2^n samples where n is 56 (i8), 48 (i16), 96 (i32), 64 (i64), 128 (i128).

impl UniformSampler for UniformInt<i32>

fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample<R: Rng + ?Sized>(self: &Self, rng: &mut R) -> <Self as >::X

Sample from distribution, Lemire's method, unbiased

fn sample_single<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample single value, Canon's method, biased

In the worst case, bias affects 1 in 2^n samples where n is 56 (i8), 48 (i16), 96 (i32), 64 (i64), 128 (i128).

impl UniformSampler for UniformInt<i64>

fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample<R: Rng + ?Sized>(self: &Self, rng: &mut R) -> <Self as >::X

Sample from distribution, Lemire's method, unbiased

fn sample_single<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample single value, Canon's method, biased

In the worst case, bias affects 1 in 2^n samples where n is 56 (i8), 48 (i16), 96 (i32), 64 (i64), 128 (i128).

impl UniformSampler for UniformInt<i8>

fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample<R: Rng + ?Sized>(self: &Self, rng: &mut R) -> <Self as >::X

Sample from distribution, Lemire's method, unbiased

fn sample_single<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample single value, Canon's method, biased

In the worst case, bias affects 1 in 2^n samples where n is 56 (i8), 48 (i16), 96 (i32), 64 (i64), 128 (i128).

impl UniformSampler for UniformInt<u128>

fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample<R: Rng + ?Sized>(self: &Self, rng: &mut R) -> <Self as >::X

Sample from distribution, Lemire's method, unbiased

fn sample_single<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample single value, Canon's method, biased

In the worst case, bias affects 1 in 2^n samples where n is 56 (i8), 48 (i16), 96 (i32), 64 (i64), 128 (i128).

impl UniformSampler for UniformInt<u16>

fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample<R: Rng + ?Sized>(self: &Self, rng: &mut R) -> <Self as >::X

Sample from distribution, Lemire's method, unbiased

fn sample_single<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample single value, Canon's method, biased

In the worst case, bias affects 1 in 2^n samples where n is 56 (i8), 48 (i16), 96 (i32), 64 (i64), 128 (i128).

impl UniformSampler for UniformInt<u32>

fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample<R: Rng + ?Sized>(self: &Self, rng: &mut R) -> <Self as >::X

Sample from distribution, Lemire's method, unbiased

fn sample_single<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample single value, Canon's method, biased

In the worst case, bias affects 1 in 2^n samples where n is 56 (i8), 48 (i16), 96 (i32), 64 (i64), 128 (i128).

impl UniformSampler for UniformInt<u64>

fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample<R: Rng + ?Sized>(self: &Self, rng: &mut R) -> <Self as >::X

Sample from distribution, Lemire's method, unbiased

fn sample_single<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample single value, Canon's method, biased

In the worst case, bias affects 1 in 2^n samples where n is 56 (i8), 48 (i16), 96 (i32), 64 (i64), 128 (i128).

impl UniformSampler for UniformInt<u8>

fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample<R: Rng + ?Sized>(self: &Self, rng: &mut R) -> <Self as >::X

Sample from distribution, Lemire's method, unbiased

fn sample_single<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized
fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(low_b: B1, high_b: B2, rng: &mut R) -> Result<<Self as >::X, Error>
where
    B1: SampleBorrow<<Self as >::X> + Sized,
    B2: SampleBorrow<<Self as >::X> + Sized

Sample single value, Canon's method, biased

In the worst case, bias affects 1 in 2^n samples where n is 56 (i8), 48 (i16), 96 (i32), 64 (i64), 128 (i128).

impl<'de, X> Deserialize for UniformInt<X>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, <__D as >::Error>
where
    __D: Deserializer<'de>

impl<T> Any for UniformInt<X>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for UniformInt<X>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for UniformInt<X>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for UniformInt<X>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> DeserializeOwned for UniformInt<X>

impl<T> From for UniformInt<X>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for UniformInt<X>

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for UniformInt<X>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for UniformInt<X>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for UniformInt<X>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

impl<V, T> VZip for UniformInt<X>

fn vzip(self: Self) -> V

impl<X> Freeze for UniformInt<X>

impl<X> RefUnwindSafe for UniformInt<X>

impl<X> Send for UniformInt<X>

impl<X> Serialize for UniformInt<X>

fn serialize<__S>(self: &Self, __serializer: __S) -> Result<<__S as >::Ok, <__S as >::Error>
where
    __S: Serializer

impl<X> StructuralPartialEq for UniformInt<X>

impl<X> Sync for UniformInt<X>

impl<X> Unpin for UniformInt<X>

impl<X> UnsafeUnpin for UniformInt<X>

impl<X> UnwindSafe for UniformInt<X>

impl<X: $crate::clone::Clone> Clone for UniformInt<X>

fn clone(self: &Self) -> UniformInt<X>

impl<X: $crate::cmp::Eq> Eq for UniformInt<X>

impl<X: $crate::cmp::PartialEq> PartialEq for UniformInt<X>

fn eq(self: &Self, other: &UniformInt<X>) -> bool

impl<X: $crate::fmt::Debug> Debug for UniformInt<X>

fn fmt(self: &Self, f: &mut Formatter<'_>) -> Result

impl<X: $crate::marker::Copy> Copy for UniformInt<X>