Generating random numbers

As described in the preface, the Rust core team left some functionality intentionally out of the standard and put it into its own external crate. Generating pseudo-random numbers is one such functionality.

How to do it...

1. Open theCargo.tomlfile that was generated earlier for you
2. Under [dependencies], add the following line:

rand = "0.3"

3. If you want, you can go to rand's crates.io page (https://crates.io/crates/rand) to check for the newest version and use that one instead

4. In the bin folder, create a file called rand.rs

5. Add the following code and run it with cargo run --bin rand:

1   extern crate rand;
2 
3   fn main() {
4     // random_num1 will be any integer between
5     // std::i32::MIN and std::i32::MAX
6     let random_num1 = rand::random::<i32>();
7     println!("random_num1: {}", random_num1);
8     let random_num2: i32 = rand::random();
9     println!("random_num2: {}", random_num2);
10    // The initialization of random_num1 and random_num2
11    // is equivalent.
12 
13    // Every primitive data type can be randomized
14    let random_char = rand::random::<char>();
15    // Altough random_char will probably not be
16    // representable on most operating systems
17    println!("random_char: {}", random_char);
18 
19 
20    use rand::Rng;
21    // We can use a reusable generator
22    let mut rng = rand::thread_rng();
23    // This is equivalent to rand::random()
24    if rng.gen() {
25      println!("This message has a 50-50 chance of being
                  printed");
26    }
27    // A generator enables us to use ranges
28    // random_num3 will be between 0 and 9
29    let random_num3 = rng.gen_range(0, 10);
30    println!("random_num3: {}", random_num3);
31 
32    // random_float will be between 0.0 and 0.999999999999...
33    let random_float = rng.gen_range(0.0, 1.0);
34    println!("random_float: {}", random_float);
35 
36    // Per default, the generator uses a uniform distribution,
37    // which should be good enough for nearly all of your
38    // use cases. If you require a particular distribution,
39    // you specify it when creating the generator:
40    let mut chacha_rng = rand::ChaChaRng::new_unseeded();
41    let random_chacha_num = chacha_rng.gen::<i32>();
42    println!("random_chacha_num: {}", random_chacha_num);
43  }

How it works...

Before you can use rand, you have to tell Rust that you're using the crate by writing:

extern crate rand;

After that, rand will provide a random generator. We can access it by either calling rand::random(); [6] or by accessing it directly with rand::thread_rng(); [22].

If we go the first route, the generator will need to be told what type to generate. You can either explicitly state the type in the method call [6] or annotate the type of the resulting variable [8]. Both are equal and result in the exact same thing. Which one you use is up to you. In this book, we will use the first convention.

As you can see in lines [29 and 33], you need neither if the type is unambiguous in the called context.

The generated value will be between its type's MIN and MAX constants. In the case of i32, this would be std::i32::MIN and std::i32::MAX, or, in concrete numbers, -2147483648 and 2147483647. You can verify these numbers easily by calling the following:

println!("min: {}, max: {}", std::i32::MIN, std::i32::MAX);

As you can see, these are very big numbers. For most purposes, you will probably want to define custom limits. You can go the second route discussed earlier and use rand::Rng for that[22]. It has a gen method, which is actually implicitly called by rand::random(), but also a gen_range() that accepts a minimum and maximum value. Keep in mind that this range is non-inclusive, which means that the maximum value can never be reached. This is why in line [29], rng.gen_range(0, 10) will only generate the numbers 0, 1, 2, 3, 4, 5, 6, 7, 8, and 9, without the 10.

All of the described ways of generating random values use uniform distribution, which means that every number in the range has the same chance of being generated. In some contexts, it makes sense to use other distributions. You can specify a generator's distribution during its creation[40]. As of the time of publication, the rand crate supports the ChaCha and ISAAC distributions.

There's more...

If you want to randomly populate an entire struct, you use the rand_derive helper crate in order to derive it from Rand. You can then generate your own struct, just as you would generate any other type.