Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Basics: improve random number examples #255

Closed
wants to merge 2 commits into from
Closed

Basics: improve random number examples #255

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
53d15ed
Basics: improve random number examples
dhardy Jul 22, 2017
ccd43b4
Basics: update random number distributions; tweaks to other prior ran…
dhardy Jul 24, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
70 changes: 58 additions & 12 deletions src/basics.md
View file
Open in desktop
Expand Up @@ -4,9 +4,9 @@
|--------|--------|------------|
| [Read lines of strings from a file][ex-std-read-lines] | [![std-badge]][std] | [![cat-filesystem-badge]][cat-filesystem] |
| [Read and write integers in little-endian byte order][ex-byteorder-le] | [![byteorder-badge]][byteorder] | [![cat-encoding-badge]][cat-encoding] |
| [Generate random floating point numbers][ex-rand-float] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Generate random numbers][ex-rand] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Generate random numbers within a range][ex-rand-range] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Generate random numbers with normal distribution][ex-rand-dist] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Generate random distributions][ex-rand-dist] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Generate random values of a custom type][ex-rand-custom] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Run an external command and process stdout][ex-parse-subprocess-output] | [![regex-badge]][regex] | [![cat-os-badge]][cat-os] [![cat-text-processing-badge]][cat-text-processing] |
| [Declare lazily evaluated constant][ex-lazy-constant] | [![lazy_static-badge]][lazy_static] | [![cat-caching-badge]][cat-caching] [![cat-rust-patterns-badge]][cat-rust-patterns] |
Expand Down Expand Up @@ -111,9 +111,11 @@ fn decode(mut bytes: &[u8]) -> Result<Payload> {
# quick_main!(run);
```

[ex-rand-float]: #ex-rand-float
<a name="ex-rand-float"></a>
## Generate random floating point numbers
[ex-rand]: #ex-rand
<a name="ex-rand"></a>
## Generate random numbers

The [`rand`] crate provides a convenient source of psuedo-random numbers.

[![rand-badge]][rand] [![cat-science-badge]][cat-science]

Expand All @@ -122,8 +124,17 @@ extern crate rand;
use rand::Rng;

fn main() {
// Each thread has an automatically-initialised random number generator:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

generally such information would be conveyed in the textual description mentioning key code identifiers linked to crate docs instead of comments (we try to keep comments to absolute minimum striving to make descriptions and code as self explanatory as possible)

let mut rng = rand::thread_rng();
println!("Random f64: {}", rng.gen::<f64>());

// Integers are uniformly distributed over the type's whole range:
let n1: u8 = rng.gen();
let n2: u16 = rng.gen();
println!("Random u8: {}; random u16: {}", n1, n2);
println!("Random i32: {}", rng.gen::<i32>());

// Floating point numbers are uniformly distributed in the half-open range [0, 1)
println!("Random float: {}", rng.gen::<f64>());
}
```

Expand All @@ -142,29 +153,61 @@ use rand::Rng;

fn main() {
let mut rng = rand::thread_rng();
println!("{}", rng.gen_range(0, 10));
println!("Integer: {}", rng.gen_range(0, 10));
println!("Float: {}", rng.gen_range(0.0, 10.0));
}
```

Alternatively, one can use the [`Range`] distribution (otherwise known as uniform).
This has the same effect, but may be faster when repeatedly generating numbers
in the same range.

```rust
extern crate rand;

use rand::distributions::{Range, IndependentSample};

fn main() {
let mut rng = rand::thread_rng();
let die = Range::new(1, 7);

loop {
let throw = die.ind_sample(&mut rng);
println!("Roll the die: {}", throw);
if throw == 6 {
break;
}
}
}
```


[ex-rand-dist]: #ex-rand-dist
<a name="ex-rand-dist"></a>
## Generate random numbers with normal distribution
## Random number distributions

[![rand-badge]][rand] [![cat-science-badge]][cat-science]

Creates a [`Normal`] distribution with mean `3` and standard deviation `5`
and generates a random value with [`IndependentSample::ind_sample`].
You've already seen how to create numbers with uniform distribution [above][ex-rand-range]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we don't aim to make the cookbook into a tutorial (what I've meant by "progression" was if there is any missing information between examples or if these are not sorted by their difficulty). We strive for problem solution (hence cookbook) approach of self-contained examples.

I would roll back the original description here as it was short and to the point and just link to alternative distributions.

(using [`Range`]). Other distributions are used in the same way: create a distribution, then
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

most of this description is obvious from the trivial code below no need to be verbose here.

sample from that distribution (using [`IndependentSample::ind_sample`]) with the help of
a random-number generator (`rng`).

The [distributions available are documented here][rand-distributions]. An example using the
[`Normal`] distribution is shown below.

```rust
extern crate rand;

use rand::distributions::{Normal, IndependentSample};

fn main() {
let normal = Normal::new(3.0, 5.0);
let mut rng = rand::thread_rng();

// mean 2, standard deviation 3:
let normal = Normal::new(2.0, 3.0);
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

any reason to change the order of statements or distribution parameters?

let v = normal.ind_sample(&mut rng);
println!("{} is from a N(3, 25) distribution", v)
println!("{} is from a N(2, 9) distribution", v)
}
```

Expand Down Expand Up @@ -520,8 +563,11 @@ fn main() {
[`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
[`Normal`]: https://doc.rust-lang.org/rand/rand/distributions/normal/struct.Normal.html
[`IndependentSample::ind_sample`]: https://doc.rust-lang.org/rand/rand/distributions/trait.IndependentSample.html#tymethod.ind_sample
[`rand`]: https://doc.rust-lang.org/rand
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is already a link to rand crate with proper form.

[normal link]
`code`
[`linked code`]

[`Rng::gen_range`]: https://doc.rust-lang.org/rand/rand/trait.Rng.html#method.gen_range
[`rand::Rand`]: https://doc.rust-lang.org/rand/rand/trait.Rand.html
[`Range`]: https://doc.rust-lang.org/rand/rand/distributions/range/struct.Range.html
[rand-distributions]: https://doc.rust-lang.org/rand/rand/distributions/index.html
[`Regex`]: https://doc.rust-lang.org/regex/regex/struct.Regex.html
[`Output`]: https://doc.rust-lang.org/std/process/struct.Output.html
[`Command`]: https://doc.rust-lang.org/std/process/struct.Command.html
Expand Down
6 changes: 3 additions & 3 deletions src/intro.md
View file
Open in desktop
Expand Up @@ -22,9 +22,9 @@ community. It needs and welcomes help. For details see
|--------|--------|------------|
| [Read lines of strings from a file][ex-std-read-lines] | [![std-badge]][std] | [![cat-filesystem-badge]][cat-filesystem] |
| [Read and write integers in little-endian byte order][ex-byteorder-le] | [![byteorder-badge]][byteorder] | [![cat-encoding-badge]][cat-encoding] |
| [Generate random floating point numbers][ex-rand-float] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Generate random numbers][ex-rand] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Generate random numbers within a range][ex-rand-range] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Generate random numbers with normal distribution][ex-rand-dist] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Generate random number distributions][ex-rand-dist] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Generate random number distributions" is slightly inaccurate. We are not generating distributions but rather random number with/of/described by given distribution. I would suggest to rewrite the title as:
"Generate random number with given distribution"

| [Generate random values of a custom type][ex-rand-custom] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
| [Run an external command and process stdout][ex-parse-subprocess-output] | [![regex-badge]][regex] | [![cat-os-badge]][cat-os] [![cat-text-processing-badge]][cat-text-processing] |
| [Declare lazily evaluated constant][ex-lazy-constant] | [![lazy_static-badge]][lazy_static] | [![cat-caching-badge]][cat-caching] [![cat-rust-patterns-badge]][cat-rust-patterns] |
Expand Down Expand Up @@ -247,7 +247,7 @@ Keep lines sorted.
[ex-percent-encode]: encoding.html#ex-percent-encode
[ex-rand-custom]: basics.html#ex-rand-custom
[ex-rand-dist]: basics.html#ex-rand-dist
[ex-rand-float]: basics.html#ex-rand-float
[ex-rand]: basics.html#ex-rand
[ex-rand-range]: basics.html#ex-rand-range
[ex-random-port-tcp]: net.html#ex-random-port-tcp
[ex-rayon-iter-mut]: concurrency.html#ex-rayon-iter-mut
Expand Down