Struct urandom::Random

pub struct Random<R: ?Sized>(pub R);

Rich interface for consuming random number generators.

Tuple Fields

0: R

Implementations

impl<R: Rng + ?Sized> Random<R>

pub fn next_u32(&mut self) -> u32

Returns the next u32 in the sequence.

Examples

let value = urandom::new().next_u32();

pub fn next_u64(&mut self) -> u64

Returns the next u64 in the sequence.

Examples

let value = urandom::new().next_u64();

pub fn next_f32(&mut self) -> f32

Returns a uniform random f32 in the half-open interval [1.0, 2.0).

As only 23 bits are necessary to construct a random float in this range, implementations may override this method to provide a more efficient implementation.

If high quality uniform random floats are desired in open interval (0.0, 1.0) without bias see the Float01 distribution.

Examples

let value = urandom::new().next_f32();
assert!(value >= 1.0 && value < 2.0);

pub fn next_f64(&mut self) -> f64

Returns a uniform random f64 in the half-open interval [1.0, 2.0).

As only 52 bits are necessary to construct a random double in this range, implementations may override this method to provide a more efficient implementation.

If high quality uniform random floats are desired in open interval (0.0, 1.0) without bias see the Float01 distribution.

Examples

let value = urandom::new().next_f64();
assert!(value >= 1.0 && value < 2.0);

pub fn fill_u32(&mut self, buffer: &mut [u32])

Fills the destination buffer with random values from the Rng.

The underlying Rng may implement this as efficiently as possible and may not be the same as simply filling with next_u32.

Examples

let mut rng = urandom::new();
let mut buffer = [0u32; 32];
rng.fill_u32(&mut buffer);
assert_ne!(buffer, [0; 32]);

pub fn fill_u64(&mut self, buffer: &mut [u64])

Fills the destination buffer with uniform random values from the Rng.

The underlying Rng may implement this as efficiently as possible and may not be the same as simply filling with next_u64.

Examples

let mut rng = urandom::new();
let mut buffer = [0u64; 32];
rng.fill_u64(&mut buffer);
assert_ne!(buffer, [0; 32]);

pub fn fill_bytes(&mut self, buffer: &mut [u8])

Fills the destination buffer with uniform random bytes from the Rng.

The underlying Rng may implement this as efficiently as possible.

Examples

let mut rng = urandom::new();
let mut buffer = [0u8; 32];
rng.fill_bytes(&mut buffer);
assert_ne!(buffer, [0u8; 32]);

pub fn jump(&mut self)

Advances the internal state significantly.

Useful to produce deterministic independent random number generators for parallel computation.

pub fn split(&mut self) -> Selfwhere
    Self: Clone,

Clones the current instance and advances the internal state significantly.

Useful to produce deterministic independent random number generators for parallel computation.

Examples

let mut rng = urandom::new();
for _ in 0..10 {
	parallel_computation(rng.split());
}

pub fn next<T>(&mut self) -> Twhere
    Standard: Distribution<T>,

Returns a sample from the Standard distribution.

Examples

let int: i8 = urandom::new().next();

pub fn fill<T>(&mut self, buffer: &mut [T])where
    Standard: Distribution<T>,

Fills the given slice with samples from the Standard distribution.

Because of its generic nature no optimizations are applied and all values are sampled individually from the distribution.

Examples

let mut rng = urandom::new();
let mut buffer = [false; 32];
rng.fill(&mut buffer);

pub fn range<T, I>(&mut self, interval: I) -> Twhere
    T: SampleUniform,
    Uniform<T>: From<I>,

Returns a sample from the Uniform distribution within the given interval.

Examples

let eyes = urandom::new().range(1..=6);
assert!(eyes >= 1 && eyes <= 6);

If more than one sample from a specific interval is desired, it is more efficient to reuse the uniform sampler.

let mut rng = urandom::new();
let distr = urandom::distributions::Uniform::from(0..100);

loop {
	let value = rng.sample(&distr);
	assert!(value >= 0 && value < 100);
	if value == 0 {
		break;
	}
}

pub fn sample<T, D>(&mut self, distr: &D) -> Twhere
    D: Distribution<T>,

Returns a sample from the given distribution.

See the distributions documentation for a list of available distributions.

pub fn samples<T, D>(&mut self, distr: D) -> Samples<'_, R, D, T>where
    D: Distribution<T>,

Returns an iterator of samples from the given distribution.

See the distributions documentation for a list of available distributions.

pub fn chance(&mut self, p: f64) -> bool

Returns true with the given probability.

This is known as the Bernoulli distribution.

Precision

For p >= 1.0, the resulting distribution will always generate true.
For p <= 0.0, the resulting distribution will always generate false.

pub fn coin_flip(&mut self) -> bool

Flips a coin.

Returns true when heads and false when tails with 50% probability for either result.

Simply an alias for rng.next::<bool>() but describes the intent of the caller.

pub fn single<I: IntoIterator>(&mut self, collection: I) -> Option<I::Item>

Returns a random sample from the collection.

Returns None if and only if the collection is empty.

This method uses Iterator::size_hint for optimisation. With an accurate hint and where Iterator::nth is a constant-time operation this method can offer O(1) performance.

For slices, prefer choose which guarantees O(1) performance.

Examples

Sample a random fizz, buzz or fizzbuzz number up to 100:

fn is_fizzbuzz(n: &i32) -> bool {
	n % 3 == 0 || n % 5 == 0
}

let mut rng = urandom::new();
let fizzbuzz = rng.single((0..100).filter(is_fizzbuzz)).unwrap();
assert!(fizzbuzz % 3 == 0 || fizzbuzz % 5 == 0);

Pick a random emoji:

let mood = urandom::new().single("😀😎😐😕😠😢".chars()).unwrap();
println!("I am {}!", mood);

pub fn multiple<I: IntoIterator>(
    &mut self,
    collection: I,
    buffer: &mut [I::Item]
) -> usize

Collect random samples from the collection into the buffer until it is filled.

Although the elements are selected randomly, the order of elements in the buffer is neither stable nor fully random. If random ordering is desired, shuffle the result.

Returns the number of elements added to the buffer. This equals the length of the buffer unless the iterator contains insufficient elements, in which case this equals the number of elements available.

Complexity is O(n) where n is the size of the collection.

pub fn index(&mut self, len: usize) -> usize

Returns a random usize in the [0, len) interval, mostly.

If the len is zero an arbitrary value is returned directly from the Rng. When used with indexing the bounds check should fail. Do not assume this value is inbounds.

Examples

let mut rng = urandom::new();
for len in 1..12345 {
	let index = rng.index(len);
	assert!(index < len, "len:{} index:{} was not inbounds", len, index);
}

pub fn choose<'a, T>(&mut self, slice: &'a [T]) -> Option<&'a T>

Returns a shared reference to one random element of the slice, or None if the slice is empty.

pub fn choose_mut<'a, T>(&mut self, slice: &'a mut [T]) -> Option<&'a mut T>

Returns a unique reference to one random element of the slice, or None if the slice is empty.

pub fn choose_iter<'a, T>(
    &'a mut self,
    slice: &'a [T]
) -> impl 'a + Iterator<Item = &'a T>

Returns an iterator over random chosen elements of the slice with repetition.

Produces None values if the slice is empty.

pub fn shuffle<T>(&mut self, slice: &mut [T])

Standard Fisher–Yates shuffle.

Examples

let mut rng = urandom::new();
let mut array = [1, 2, 3, 4, 5];
println!("Unshuffled: {:?}", array);
rng.shuffle(&mut array);
println!("Shuffled:   {:?}", array);

pub fn partial_shuffle<T>(&mut self, slice: &mut [T], n: usize)

Shuffle only the first n elements.

This is an efficient method to select n elements at random from the slice without repetition, provided the slice may be mutated.

Trait Implementations

impl<R: Clone + ?Sized> Clone for Random<R>

fn clone(&self) -> Random<R>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<R: Rng + ?Sized> Debug for Random<R>

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

Formats the value using the given formatter.

impl<R: Rng> Read for Random<R>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_to_end(&mut self, _buf: &mut Vec<u8>) -> Result<usize>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, _buf: &mut String) -> Result<usize>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>

Read the exact number of bytes required to fill buf.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Selfwhere
    Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>where
    Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>where
    R: Read,
    Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>where
    Self: Sized,

Creates an adapter which will read at most limit bytes from it.