# Struct rand::distributions::uniform::UniformInt

source · `pub struct UniformInt<X> { /* private fields */ }`

## Expand description

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.

## Trait Implementations§

source§### impl<X: Clone> Clone for UniformInt<X>

### impl<X: Clone> Clone for UniformInt<X>

source§#### fn clone(&self) -> UniformInt<X>

#### fn clone(&self) -> UniformInt<X>

1.0.0 · source§#### fn clone_from(&mut self, source: &Self)

#### fn clone_from(&mut self, source: &Self)

`source`

. Read moresource§### impl<X: Debug> Debug for UniformInt<X>

### impl<X: Debug> Debug for UniformInt<X>

source§### impl<'de, X> Deserialize<'de> for UniformInt<X>where
X: Deserialize<'de>,

### impl<'de, X> Deserialize<'de> for UniformInt<X>where
X: Deserialize<'de>,

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

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

source§### impl<X: PartialEq> PartialEq for UniformInt<X>

### impl<X: PartialEq> PartialEq for UniformInt<X>

source§#### fn eq(&self, other: &UniformInt<X>) -> bool

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

`self`

and `other`

values to be equal, and is used
by `==`

.source§### impl<X> Serialize for UniformInt<X>where
X: Serialize,

### impl<X> Serialize for UniformInt<X>where
X: Serialize,

source§### impl UniformSampler for UniformInt<i128>

### impl UniformSampler for UniformInt<i128>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

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

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`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<i16>

### impl UniformSampler for UniformInt<i16>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

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

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`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<i32>

### impl UniformSampler for UniformInt<i32>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

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

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`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<i64>

### impl UniformSampler for UniformInt<i64>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

Sample single value, Canon’s method, biased

`2^n`

samples where n is
56 (`i8`

), 48 (`i16`

), 96 (`i32`

), 64 (`i64`

), 128 (`i128`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<i8>

### impl UniformSampler for UniformInt<i8>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

Sample single value, Canon’s method, biased

`2^n`

samples where n is
56 (`i8`

), 48 (`i16`

), 96 (`i32`

), 64 (`i64`

), 128 (`i128`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<isize>

### impl UniformSampler for UniformInt<isize>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

Sample single value, Canon’s method, biased

`2^n`

samples where n is
56 (`i8`

), 48 (`i16`

), 96 (`i32`

), 64 (`i64`

), 128 (`i128`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<u128>

### impl UniformSampler for UniformInt<u128>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

Sample single value, Canon’s method, biased

`2^n`

samples where n is
56 (`i8`

), 48 (`i16`

), 96 (`i32`

), 64 (`i64`

), 128 (`i128`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<u16>

### impl UniformSampler for UniformInt<u16>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

Sample single value, Canon’s method, biased

`2^n`

samples where n is
56 (`i8`

), 48 (`i16`

), 96 (`i32`

), 64 (`i64`

), 128 (`i128`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<u32>

### impl UniformSampler for UniformInt<u32>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

Sample single value, Canon’s method, biased

`2^n`

samples where n is
56 (`i8`

), 48 (`i16`

), 96 (`i32`

), 64 (`i64`

), 128 (`i128`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<u64>

### impl UniformSampler for UniformInt<u64>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

Sample single value, Canon’s method, biased

`2^n`

samples where n is
56 (`i8`

), 48 (`i16`

), 96 (`i32`

), 64 (`i64`

), 128 (`i128`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<u8>

### impl UniformSampler for UniformInt<u8>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

Sample single value, Canon’s method, biased

`2^n`

samples where n is
56 (`i8`

), 48 (`i16`

), 96 (`i32`

), 64 (`i64`

), 128 (`i128`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read moresource§### impl UniformSampler for UniformInt<usize>

### impl UniformSampler for UniformInt<usize>

source§#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

#### fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X

Sample from distribution, Lemire’s method, unbiased

source§#### fn sample_single_inclusive<R: Rng + ?Sized, B1, B2>(
low_b: B1,
high_b: B2,
rng: &mut R
) -> Result<Self::X, Error>

Sample single value, Canon’s method, biased

`2^n`

samples where n is
56 (`i8`

), 48 (`i16`

), 96 (`i32`

), 64 (`i64`

), 128 (`i128`

).

source§#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high)`

. Read moresource§#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

#### fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Result<Self, Error>

`[low, high]`

. Read more