Struct rand::distributions::uniform::UniformInt

pub struct UniformInt<X> { /* fields omitted */ }

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 a closed range, the number of possible numbers we should generate is range = (high - low + 1). It is not possible to end up with a uniform distribution if we map all the random integers that can be generated to this range. We have to map integers from a zone that is a multiple of the range. The rest of the integers, that cause a bias, are rejected.

The problem with range is that to cover the full range of the type, it has to store unsigned_max + 1, which can't be represented. But if the range covers the full range of the type, no modulus is needed. A range of size 0 can't exist, so we use that to represent this special case. Wrapping arithmetic even makes representing unsigned_max + 1 as 0 simple.

We don't calculate zone directly, but first calculate the number of integers to reject. To handle unsigned_max + 1 not fitting in the type, we use: ints_to_reject = (unsigned_max + 1) % range; ints_to_reject = (unsigned_max - range + 1) % range;

The smallest integer PRNGs generate is u32. That is why for small integer sizes (i8/u8 and i16/u16) there is an optimization: don't pick the largest zone that can fit in the small type, but pick the largest zone that can fit in an u32. ints_to_reject is always less than half the size of the small integer. This means the first bit of zone is always 1, and so are all the other preceding bits of a larger integer. The easiest way to grow the zone for the larger type is to simply sign extend it.

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

impl UniformSampler for UniformInt<i8>

type X = i8

The type sampled by this implementation.

fn new(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive lower bound and exclusive upper bound [low, high).

fn new_inclusive(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive bounds [low, high].

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

Sample a value.

fn sample_single<R: Rng + ?Sized>(     low: Self::X,     high: Self::X,     rng: &mut R ) -> Self::X

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, high).

impl UniformSampler for UniformInt<i16>

type X = i16

The type sampled by this implementation.

fn new(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive lower bound and exclusive upper bound [low, high).

fn new_inclusive(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive bounds [low, high].

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

Sample a value.

fn sample_single<R: Rng + ?Sized>(     low: Self::X,     high: Self::X,     rng: &mut R ) -> Self::X

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, high).

impl UniformSampler for UniformInt<i32>

type X = i32

The type sampled by this implementation.

fn new(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive lower bound and exclusive upper bound [low, high).

fn new_inclusive(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive bounds [low, high].

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

Sample a value.

fn sample_single<R: Rng + ?Sized>(     low: Self::X,     high: Self::X,     rng: &mut R ) -> Self::X

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, high).

impl UniformSampler for UniformInt<i64>

type X = i64

The type sampled by this implementation.

fn new(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive lower bound and exclusive upper bound [low, high).

fn new_inclusive(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive bounds [low, high].

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

Sample a value.

fn sample_single<R: Rng + ?Sized>(     low: Self::X,     high: Self::X,     rng: &mut R ) -> Self::X

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, high).

impl UniformSampler for UniformInt<isize>

type X = isize

The type sampled by this implementation.

fn new(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive lower bound and exclusive upper bound [low, high).

fn new_inclusive(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive bounds [low, high].

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

Sample a value.

fn sample_single<R: Rng + ?Sized>(     low: Self::X,     high: Self::X,     rng: &mut R ) -> Self::X

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, high).

impl UniformSampler for UniformInt<u8>

type X = u8

The type sampled by this implementation.

fn new(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive lower bound and exclusive upper bound [low, high).

fn new_inclusive(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive bounds [low, high].

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

Sample a value.

fn sample_single<R: Rng + ?Sized>(     low: Self::X,     high: Self::X,     rng: &mut R ) -> Self::X

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, high).

impl UniformSampler for UniformInt<u16>

type X = u16

The type sampled by this implementation.

fn new(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive lower bound and exclusive upper bound [low, high).

fn new_inclusive(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive bounds [low, high].

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

Sample a value.

fn sample_single<R: Rng + ?Sized>(     low: Self::X,     high: Self::X,     rng: &mut R ) -> Self::X

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, high).

impl UniformSampler for UniformInt<u32>

type X = u32

The type sampled by this implementation.

fn new(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive lower bound and exclusive upper bound [low, high).

fn new_inclusive(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive bounds [low, high].

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

Sample a value.

fn sample_single<R: Rng + ?Sized>(     low: Self::X,     high: Self::X,     rng: &mut R ) -> Self::X

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, high).

impl UniformSampler for UniformInt<u64>

type X = u64

The type sampled by this implementation.

fn new(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive lower bound and exclusive upper bound [low, high).

fn new_inclusive(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive bounds [low, high].

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

Sample a value.

fn sample_single<R: Rng + ?Sized>(     low: Self::X,     high: Self::X,     rng: &mut R ) -> Self::X

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, high).

impl UniformSampler for UniformInt<usize>

type X = usize

The type sampled by this implementation.

fn new(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive lower bound and exclusive upper bound [low, high).

fn new_inclusive(low: Self::X, high: Self::X) -> Self

Construct self, with inclusive bounds [low, high].

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

Sample a value.

fn sample_single<R: Rng + ?Sized>(     low: Self::X,     high: Self::X,     rng: &mut R ) -> Self::X

Sample a single value uniformly from a range with inclusive lower bound and exclusive upper bound [low, high).

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<X: Copy> Copy for UniformInt<X>

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

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.