[][src]Module turtle::rand

Utilities for generating random values

This module provides a much, much simpler version of the very robust rand crate. The purpose of this is to give people teaching/learning Rust an easier target for doing interesting things with random numbers. You don't need to know very much Rust to use this module and once you get comfortable with this, you can always move to learning the rand crate as well. If the items in this module are not advanced enough for your needs, you probably want to consider using the full rand crate instead.

Random Number Generation

Computers can't generate "true" random numbers yet, however they can approximate sequences of numbers that look random. This is called pseudo-random number generation. This module provides a set of functions (and traits) for generating pseudo-random numbers.

The current set of utilities provided includes:

  • random() - for generating a single random value of a given type
  • random_range() - for generating a single random value of a given type in a certain range
  • shuffle() - for mixing up a slice of values (Vec, slices, etc.)
  • choose() - for choosing a single value from a slice of values (Vec, slices, etc.)

See the documentation for each of those functions for more on what you can use them for.

Generating Random Values

The random() function supports all of the common primitive types you would expect:

  • Booleans: bool
  • Floating-point: f32, f64
  • Integers: u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize
  • Tuples, arrays, and many more

It also supports types specific to the turtle crate:

  • Distance - f64 values greater than or equal to 0.0 and less than or equal to 1.0
  • Angle - f64 values greater than or equal to 0.0 and less than or equal to 1.0
  • Speed - any speed value in the valid range, not including instant
  • Color - colors with random red, green, blue, and alpha values (use opaque() to get a solid random color)
  • Point - a random point with two f64 values greater than or equal to 0.0 and less than or equal to 1.0

Random Custom Types

To make types within your application capable of being used with random() or random_range(), implement the Random or RandomRange traits respectively. See the documentation of those traits for more information.

You typically won't need to implement RandomSlice for yourself since it is already implemented for slices. That being said, if your type can be represented as a slice, you can implement RandomSlice so it can be used with the shuffle() and choose() functions.

use turtle::rand::RandomSlice;

// This is a "newtype" wrapper around a Vec<T> which can be represented as a slice.
#[derive(Debug, Clone)]
struct MyVec<T>(Vec<T>);

impl<T> RandomSlice for MyVec<T> {
    type Item = T;

    fn shuffle(&mut self) {
        (&mut *self.0 as &mut [T]).shuffle();
    }

    fn choose(&self) -> Option<&Self::Item> {
        (&*self.0 as &[T]).choose()
    }
}

Traits

Random

This trait represents any type that can have random values generated for it.

RandomRange

This trait represents any type that can have random values generated for it within a certain range.

RandomSlice

This trait represents useful random operations for slices.

Functions

choose

Chooses a random element from the slice and returns a reference to it.

random

Generates a single random value of the type T.

random_range

Generates a random value in the given range.

shuffle

Shuffle the elements of the given slice in place.