# [−][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 |

random_range | Generates a random value in the given range. |

shuffle | Shuffle the elements of the given slice in place. |