# [−] [src] Module rand::distributions::uniform

A distribution uniformly sampling numbers within a given range.

[`Uniform`] is the standard distribution to sample uniformly from a range; e.g. `Uniform::new_inclusive(1, 6)` can sample integers from 1 to 6, like a standard die. [`Rng::gen_range`] supports any type supported by [`Uniform`].

This distribution is provided with support for several primitive types (all integer and floating-point types) as well as [`std::time::Duration`], and supports extension to user-defined types via a type-specific back-end implementation.

The types `UniformInt`, `UniformFloat` and `UniformDuration` are the back-ends supporting sampling from primitive integer and floating-point ranges as well as from [`std::time::Duration`]; these types do not normally need to be used directly (unless implementing a derived back-end).

# Example usage

    use rand::{Rng, thread_rng};
    use rand::distributions::Uniform;

    let mut rng = thread_rng();
    let side = Uniform::new(-10.0, 10.0);

    // sample between 1 and 10 points
    for _ in 0..rng.gen_range(1, 11) {
        // sample a point from the square with sides -10 - 10 in two dimensions
        let (x, y) = (rng.sample(side), rng.sample(side));
        println!("Point: {}, {}", x, y);
    }

# Extending `Uniform` to support a custom type

To extend [`Uniform`] to support your own types, write a back-end which implements the `UniformSampler` trait, then implement the `SampleUniform` helper trait to "register" your back-end. See the `MyF32` example below.

At a minimum, the back-end needs to store any parameters needed for sampling (e.g. the target range) and implement `new`, `new_inclusive` and `sample`. Those methods should include an assert to check the range is valid (i.e. `low < high`). The example below merely wraps another back-end.

The `new`, `new_inclusive` and `sample_single` functions use arguments of type SampleBorrow<X> in order to support passing in values by reference or by value. In the implementation of these functions, you can choose to simply use the reference returned by `SampleBorrow::borrow`, or you can choose to copy or clone the value, whatever is appropriate for your type.

    use rand::prelude::*;
    use rand::distributions::uniform::{Uniform, SampleUniform,
            UniformSampler, UniformFloat, SampleBorrow};

    struct MyF32(f32);

    #[derive(Clone, Copy, Debug)]
    struct UniformMyF32 {
        inner: UniformFloat<f32>,
    }

    impl UniformSampler for UniformMyF32 {
        type X = MyF32;
        fn new<B1, B2>(low: B1, high: B2) -> Self
            where B1: SampleBorrow<Self::X> + Sized,
                  B2: SampleBorrow<Self::X> + Sized
        {
            UniformMyF32 {
                inner: UniformFloat::<f32>::new(low.borrow().0, high.borrow().0),
            }
        }
        fn new_inclusive<B1, B2>(low: B1, high: B2) -> Self
            where B1: SampleBorrow<Self::X> + Sized,
                  B2: SampleBorrow<Self::X> + Sized
        {
            UniformSampler::new(low, high)
        }
        fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X {
            MyF32(self.inner.sample(rng))
        }
    }

    impl SampleUniform for MyF32 {
        type Sampler = UniformMyF32;
    }

    let (low, high) = (MyF32(17.0f32), MyF32(22.0f32));
    let uniform = Uniform::new(low, high);
    let x = uniform.sample(&mut thread_rng());

## Structs

Uniform | Sample values uniformly between two bounds.
UniformDuration | The back-end implementing [`UniformSampler`] for `Duration`.
UniformFloat | The back-end implementing [`UniformSampler`] for floating-point types.
UniformInt | The back-end implementing [`UniformSampler`] for integer types.

## Traits

SampleBorrow | Helper trait similar to `Borrow` but implemented only for SampleUniform and references to SampleUniform in order to resolve ambiguity issues.
SampleUniform | Helper trait for creating objects using the correct implementation of [`UniformSampler`] for the sampling type.
UniformSampler | Helper trait handling actual uniform sampling.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)