diff options
| -rw-r--r-- | src/libcore/rand.rs | 192 |
1 files changed, 183 insertions, 9 deletions
diff --git a/src/libcore/rand.rs b/src/libcore/rand.rs index a4e53418fc8..c6400ccded8 100644 --- a/src/libcore/rand.rs +++ b/src/libcore/rand.rs @@ -150,7 +150,21 @@ pub struct Weighted<T> { pub trait RngUtil { fn gen<T:Rand>(&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,184 @@ 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<T:Copy>(&self, values: &[T]) -> T; /// Choose Some(item) randomly, returning None if values is empty fn choose_option<T:Copy>(&self, values: &[T]) -> Option<T>; /** * 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<T:Copy>(&self, v : &[Weighted<T>]) -> 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<T:Copy>(&self, v: &[Weighted<T>]) -> Option<T>; /** * 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<T:Copy>(&self, v: &[Weighted<T>]) -> ~[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<T:Copy>(&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<T>(&self, values: &mut [T]); } @@ -337,7 +511,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 |