From 4b7d3634955ca6c7f4632d2c74ccc0137438e744 Mon Sep 17 00:00:00 2001 From: Dan Luu Date: Wed, 10 Apr 2013 15:08:19 -0400 Subject: [PATCH 1/3] Add examples for Rng functions. --- src/libcore/rand.rs | 184 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 176 insertions(+), 8 deletions(-) diff --git a/src/libcore/rand.rs b/src/libcore/rand.rs index a4e53418fc8..df08c370546 100644 --- a/src/libcore/rand.rs +++ b/src/libcore/rand.rs @@ -150,7 +150,21 @@ pub struct Weighted { pub trait RngUtil { fn gen(&self) -> T; - /// Return a random int + /** + * Return a random int + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * println(fmt!("%d",rng.gen_int())); + * } + * ~~~ + */ fn gen_int(&self) -> int; fn gen_int_range(&self, start: int, end: int) -> int; /// Return a random i8 @@ -176,7 +190,21 @@ pub trait RngUtil { fn gen_u32(&self) -> u32; /// Return a random u64 fn gen_u64(&self) -> u64; - /// Return a random float in the interval [0,1] + /** + * Return random float in the interval [0,1] + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * println(fmt!("%f",rng.gen_float())); + * } + * ~~~ + */ fn gen_float(&self) -> float; /// Return a random f32 in the interval [0,1] fn gen_f32(&self) -> f32; @@ -188,38 +216,178 @@ pub trait RngUtil { * Return a char randomly chosen from chars, failing if chars is empty */ fn gen_char_from(&self, chars: &str) -> char; - /// Return a random bool + /** + * Return a random bool + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * println(fmt!("%b",rng.gen_bool())); + * } + * ~~~ + */ fn gen_bool(&self) -> bool; - /// Return a bool with a 1 in n chance of true + /** + * Return a bool with a 1 in n chance of true + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * println(fmt!("%b",rng.gen_weighted_bool(3))); + * } + * ~~~ + */ fn gen_weighted_bool(&self, n: uint) -> bool; /** * Return a random string of the specified length composed of A-Z,a-z,0-9 + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * println(rng.gen_str(8)); + * } + * ~~~ */ fn gen_str(&self, len: uint) -> ~str; - /// Return a random byte string of the specified length + /** + * Return a random byte string of the specified length + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * println(fmt!("%?",rng.gen_bytes(8))); + * } + * ~~~ + */ fn gen_bytes(&self, len: uint) -> ~[u8]; - /// Choose an item randomly, failing if values is empty + /// + /** + * Choose an item randomly, failing if values is empty + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * println(fmt!("%d",rng.choose([1,2,4,8,16,32]))); + * } + * ~~~ + */ fn choose(&self, values: &[T]) -> T; /// Choose Some(item) randomly, returning None if values is empty fn choose_option(&self, values: &[T]) -> Option; /** * Choose an item respecting the relative weights, failing if the sum of * the weights is 0 + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * let x = [rand::Weighted {weight: 4, item: 'a'}, rand::Weighted {weight: 2, item: 'b'}, rand::Weighted {weight: 2, item: 'c'}]; + * println(fmt!("%c",rng.choose_weighted(x))); + * } + * ~~~ */ fn choose_weighted(&self, v : &[Weighted]) -> T; /** * Choose Some(item) respecting the relative weights, returning none if * the sum of the weights is 0 + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * let x = [rand::Weighted {weight: 4, item: 'a'}, rand::Weighted {weight: 2, item: 'b'}, rand::Weighted {weight: 2, item: 'c'}]; + * println(fmt!("%?",rng.choose_weighted_option(x))); + * } + * ~~~ */ fn choose_weighted_option(&self, v: &[Weighted]) -> Option; /** * Return a vec containing copies of the items, in order, where * the weight of the item determines how many copies there are + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * let x = [rand::Weighted {weight: 4, item: 'a'}, rand::Weighted {weight: 2, item: 'b'}, rand::Weighted {weight: 2, item: 'c'}]; + * println(fmt!("%?",rng.weighted_vec(x))); + * } + * ~~~ */ fn weighted_vec(&self, v: &[Weighted]) -> ~[T]; - /// Shuffle a vec + /** + * Shuffle a vec + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * println(fmt!("%?",rng.shuffle([1,2,3]))); + * } + * ~~~ + */ fn shuffle(&self, values: &[T]) -> ~[T]; - /// Shuffle a mutable vec in place + /** + * Shuffle a mutable vec in place + * + * *Example* + * + * ~~~ + * + * use core::rand::RngUtil; + * + * fn main() { + * rng = rand::Rng(); + * let mut y = [1,2,3]; + * rng.shuffle_mut(y); + * println(fmt!("%?",y)); + * rng.shuffle_mut(y); + * println(fmt!("%?",y)); + * } + * ~~~ + */ fn shuffle_mut(&self, values: &mut [T]); } From ccae209b0db58db1054ede13acfc79c84e0221f3 Mon Sep 17 00:00:00 2001 From: Dan Luu Date: Wed, 10 Apr 2013 15:54:28 -0400 Subject: [PATCH 2/3] Clarify comment --- src/libcore/rand.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/rand.rs b/src/libcore/rand.rs index df08c370546..2ee280ff159 100644 --- a/src/libcore/rand.rs +++ b/src/libcore/rand.rs @@ -505,7 +505,7 @@ impl RngUtil for @Rng { self.next() & 1u32 == 1u32 } - /// Return a bool with a 1 in n chance of true + /// Return a bool with a 1-in-n chance of true fn gen_weighted_bool(&self, n: uint) -> bool { if n == 0u { true From aff558998ef98b4c80cace32538ba23ee67a4d6d Mon Sep 17 00:00:00 2001 From: Dan Luu Date: Thu, 11 Apr 2013 09:12:26 -0400 Subject: [PATCH 3/3] Fix formatting --- src/libcore/rand.rs | 74 ++++++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 34 deletions(-) diff --git a/src/libcore/rand.rs b/src/libcore/rand.rs index 2ee280ff159..c6400ccded8 100644 --- a/src/libcore/rand.rs +++ b/src/libcore/rand.rs @@ -157,11 +157,11 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); - * println(fmt!("%d",rng.gen_int())); + * rng = rand::Rng(); + * println(fmt!("%d",rng.gen_int())); * } * ~~~ */ @@ -197,11 +197,11 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); - * println(fmt!("%f",rng.gen_float())); + * rng = rand::Rng(); + * println(fmt!("%f",rng.gen_float())); * } * ~~~ */ @@ -223,10 +223,10 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); + * rng = rand::Rng(); * println(fmt!("%b",rng.gen_bool())); * } * ~~~ @@ -239,11 +239,11 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); - * println(fmt!("%b",rng.gen_weighted_bool(3))); + * rng = rand::Rng(); + * println(fmt!("%b",rng.gen_weighted_bool(3))); * } * ~~~ */ @@ -255,11 +255,11 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); - * println(rng.gen_str(8)); + * rng = rand::Rng(); + * println(rng.gen_str(8)); * } * ~~~ */ @@ -271,16 +271,16 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); - * println(fmt!("%?",rng.gen_bytes(8))); + * rng = rand::Rng(); + * println(fmt!("%?",rng.gen_bytes(8))); * } * ~~~ */ fn gen_bytes(&self, len: uint) -> ~[u8]; - /// + /// /** * Choose an item randomly, failing if values is empty * @@ -288,11 +288,11 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); - * println(fmt!("%d",rng.choose([1,2,4,8,16,32]))); + * rng = rand::Rng(); + * println(fmt!("%d",rng.choose([1,2,4,8,16,32]))); * } * ~~~ */ @@ -307,11 +307,13 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); - * let x = [rand::Weighted {weight: 4, item: 'a'}, rand::Weighted {weight: 2, item: 'b'}, rand::Weighted {weight: 2, item: 'c'}]; + * rng = rand::Rng(); + * let x = [rand::Weighted {weight: 4, item: 'a'}, + * rand::Weighted {weight: 2, item: 'b'}, + * rand::Weighted {weight: 2, item: 'c'}]; * println(fmt!("%c",rng.choose_weighted(x))); * } * ~~~ @@ -325,11 +327,13 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); - * let x = [rand::Weighted {weight: 4, item: 'a'}, rand::Weighted {weight: 2, item: 'b'}, rand::Weighted {weight: 2, item: 'c'}]; + * rng = rand::Rng(); + * let x = [rand::Weighted {weight: 4, item: 'a'}, + * rand::Weighted {weight: 2, item: 'b'}, + * rand::Weighted {weight: 2, item: 'c'}]; * println(fmt!("%?",rng.choose_weighted_option(x))); * } * ~~~ @@ -343,11 +347,13 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); - * let x = [rand::Weighted {weight: 4, item: 'a'}, rand::Weighted {weight: 2, item: 'b'}, rand::Weighted {weight: 2, item: 'c'}]; + * rng = rand::Rng(); + * let x = [rand::Weighted {weight: 4, item: 'a'}, + * rand::Weighted {weight: 2, item: 'b'}, + * rand::Weighted {weight: 2, item: 'c'}]; * println(fmt!("%?",rng.weighted_vec(x))); * } * ~~~ @@ -360,10 +366,10 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); + * rng = rand::Rng(); * println(fmt!("%?",rng.shuffle([1,2,3]))); * } * ~~~ @@ -376,10 +382,10 @@ pub trait RngUtil { * * ~~~ * - * use core::rand::RngUtil; + * use core::rand::RngUtil; * * fn main() { - * rng = rand::Rng(); + * rng = rand::Rng(); * let mut y = [1,2,3]; * rng.shuffle_mut(y); * println(fmt!("%?",y));