Random number generation.
The key functions are random()
and RngUtil::gen()
. These are polymorphic and so can be used to generate any type that implements Rand
. Type inference means that often a simple call to rand::random()
or rng.gen()
will suffice, but sometimes an annotation is required, e.g. rand::random::<float>()
.
See the distributions
submodule for sampling random numbers from distributions like normal and exponential.
use core::rand::RngUtil;
fn main() {
let mut rng = rand::rng();
if rng.gen() { // bool
println(fmt!("int: %d, uint: %u", rng.gen(), rng.gen()))
}
}
fn main () {
let tuple_ptr = rand::random::<~(f64, char)>();
println(fmt!("%?", tuple_ptr))
}
IsaacRng
- A random number generator that uses the [ISAAC algorithm](http://enWeighted
- A value with a particular weight compared to other valuesXorShiftRng
- An [Xorshift random number generator](http://enRand
- A type that can be randomly generated using an RngRng
- A random number generatorRngUtil
- Helper functions attached to the Rng typeof Rand for int
of Rand for i8
of Rand for i16
of Rand for i32
of Rand for i64
of Rand for uint
of Rand for u8
of Rand for u16
of Rand for u32
of Rand for u64
of Rand for float
of Rand for f32
of Rand for f64
of Rand for char
of Rand for bool
of Rand for ()
of Rand for (A,) where <A: Rand>
of Rand for (A, B) where <A: Rand, B: Rand>
of Rand for (A, B, C) where <A: Rand, B: Rand, C: Rand>
of Rand for (A, B, C, D) where <A: Rand, B: Rand, C: Rand, D: Rand>
of Rand for (A, B, C, D, E) where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand>
of Rand for (A, B, C, D, E, F) where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand>
of Rand for (A, B, C, D, E, F, G) where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand, G: Rand>
of Rand for (A, B, C, D, E, F, G, H) where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand, G: Rand, H: Rand>
of Rand for (A, B, C, D, E, F, G, H, I) where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand, G: Rand, H: Rand, I: Rand>
of Rand for (A, B, C, D, E, F, G, H, I, J) where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand, G: Rand, H: Rand, I: Rand, J: Rand>
of Rand for Option<T> where <T: Rand>
of Rand for ~T where <T: Rand>
of Rand for @T where <T: Rand>
of RngUtil for R where <R: Rng>
- Extension methods for random number generatorsfor IsaacRng
of Rng for IsaacRng
of Rng for XorShiftRng
for XorShiftRng
of Rng for @mut R where <R: Rng>
random
- Returns a random value of a Rand type, using the task's random number generator.rng
- Create a random number generator with a default algorithm and seed.seed
- Create a new random seed.task_rng
- Gives back a lazily initialized task-local random number generator, seeded by the systemrand::distributions
- Sampling from random distributionsrand::rustrt
IsaacRng
pub struct IsaacRng {
priv cnt: u32,
priv rsl: [u32, ..RAND_SIZE],
priv mem: [u32, ..RAND_SIZE],
priv a: u32,
priv b: u32,
priv c: u32,
}
A random number generator that uses the ISAAC algorithm.
Weighted
pub struct Weighted<T> {
/// The numerical weight of this item
weight: uint,
/// The actual item which is being weighted
item: T,
}
A value with a particular weight compared to other values
XorShiftRng
pub struct XorShiftRng {
priv x: u32,
priv y: u32,
priv z: u32,
priv w: u32,
}
An Xorshift random number generator. Not suitable for cryptographic purposes.
Rand
A type that can be randomly generated using an Rng
rand
fn rand<R: Rng>(rng: &mut R) -> Self
Generates a random instance of this type using the specified source of randomness
Rng
A random number generator
next
fn next(&mut self) -> u32
Return the next random integer
RngUtil
Helper functions attached to the Rng type
gen
fn gen<T: Rand>(&mut self) -> T
Return a random value of a Rand type
gen_int_range
fn gen_int_range(&mut self, start: int, end: int) -> int
Return a int randomly chosen from the range [start, end), failing if start >= end
gen_uint_range
fn gen_uint_range(&mut self, start: uint, end: uint) -> uint
Return a uint randomly chosen from the range [start, end), failing if start >= end
gen_char_from
fn gen_char_from(&mut self, chars: &str) -> char
Return a char randomly chosen from chars, failing if chars is empty
gen_weighted_bool
fn gen_weighted_bool(&mut self, n: uint) -> bool
Return a bool with a 1 in n chance of true
use core::rand::RngUtil;
fn main() {
rng = rand::rng();
println(fmt!("%b",rng.gen_weighted_bool(3)));
}
gen_str
fn gen_str(&mut self, len: uint) -> ~str
Return a random string of the specified length composed of A-Z,a-z,0-9
use core::rand::RngUtil;
fn main() {
rng = rand::rng();
println(rng.gen_str(8));
}
gen_bytes
fn gen_bytes(&mut self, len: uint) -> ~[u8]
Return a random byte string of the specified length
use core::rand::RngUtil;
fn main() {
rng = rand::rng();
println(fmt!("%?",rng.gen_bytes(8)));
}
choose
fn choose<T: Copy>(&mut self, values: &[T]) -> T
Choose an item randomly, failing if values is empty
use core::rand::RngUtil;
fn main() {
rng = rand::rng();
println(fmt!("%d",rng.choose([1,2,4,8,16,32])));
}
choose_option
fn choose_option<T: Copy>(&mut self, values: &[T]) -> Option<T>
Choose Some(item) randomly, returning None if values is empty
choose_weighted
fn choose_weighted<T: Copy>(&mut self, v: &[Weighted<T>]) -> T
Choose an item respecting the relative weights, failing if the sum of the weights is 0
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)));
}
choose_weighted_option
fn choose_weighted_option<T: Copy>(&mut self, v: &[Weighted<T>]) -> Option<T>
Choose Some(item) respecting the relative weights, returning none if the sum of the weights is 0
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)));
}
weighted_vec
fn weighted_vec<T: Copy>(&mut self, v: &[Weighted<T>]) -> ~[T]
Return a vec containing copies of the items, in order, where the weight of the item determines how many copies there are
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)));
}
shuffle
fn shuffle<T: Copy>(&mut self, values: &[T]) -> ~[T]
Shuffle a vec
use core::rand::RngUtil;
fn main() {
rng = rand::rng();
println(fmt!("%?",rng.shuffle([1,2,3])));
}
shuffle_mut
fn shuffle_mut<T>(&mut self, values: &mut [T])
Shuffle a mutable vec in place
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));
}
Rand
for int
rand
fn rand<R: Rng>(rng: &mut R) -> int
Rand
for i8
rand
fn rand<R: Rng>(rng: &mut R) -> i8
Rand
for i16
rand
fn rand<R: Rng>(rng: &mut R) -> i16
Rand
for i32
rand
fn rand<R: Rng>(rng: &mut R) -> i32
Rand
for i64
rand
fn rand<R: Rng>(rng: &mut R) -> i64
Rand
for uint
rand
fn rand<R: Rng>(rng: &mut R) -> uint
Rand
for u8
rand
fn rand<R: Rng>(rng: &mut R) -> u8
Rand
for u16
rand
fn rand<R: Rng>(rng: &mut R) -> u16
Rand
for u32
rand
fn rand<R: Rng>(rng: &mut R) -> u32
Rand
for u64
rand
fn rand<R: Rng>(rng: &mut R) -> u64
Rand
for float
rand
fn rand<R: Rng>(rng: &mut R) -> float
Rand
for f32
rand
fn rand<R: Rng>(rng: &mut R) -> f32
Rand
for f64
rand
fn rand<R: Rng>(rng: &mut R) -> f64
Rand
for char
rand
fn rand<R: Rng>(rng: &mut R) -> char
Rand
for bool
rand
fn rand<R: Rng>(rng: &mut R) -> bool
Rand
for ()
rand
fn rand<R: Rng>(_: &mut R)
Rand
for (A,)
where <A: Rand>
rand
fn rand<R: Rng>(_rng: &mut R) -> (A,)
Rand
for (A, B)
where <A: Rand, B: Rand>
rand
fn rand<R: Rng>(_rng: &mut R) -> (A, B)
Rand
for (A, B, C)
where <A: Rand, B: Rand, C: Rand>
rand
fn rand<R: Rng>(_rng: &mut R) -> (A, B, C)
Rand
for (A, B, C, D)
where <A: Rand, B: Rand, C: Rand, D: Rand>
rand
fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D)
Rand
for (A, B, C, D, E)
where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand>
rand
fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E)
Rand
for (A, B, C, D, E, F)
where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand>
rand
fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E, F)
Rand
for (A, B, C, D, E, F, G)
where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand, G: Rand>
rand
fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E, F, G)
Rand
for (A, B, C, D, E, F, G, H)
where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand, G: Rand, H: Rand>
rand
fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E, F, G, H)
Rand
for (A, B, C, D, E, F, G, H, I)
where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand, G: Rand, H: Rand, I: Rand>
rand
fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E, F, G, H, I)
Rand
for (A, B, C, D, E, F, G, H, I, J)
where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand, G: Rand, H: Rand, I: Rand, J: Rand>
rand
fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E, F, G, H, I, J)
Rand
for Option<T>
where <T: Rand>
rand
fn rand<R: Rng>(rng: &mut R) -> Option<T>
Rand
for ~T
where <T: Rand>
rand
fn rand<R: Rng>(rng: &mut R) -> ~T
Rand
for @T
where <T: Rand>
rand
fn rand<R: Rng>(rng: &mut R) -> @T
RngUtil
for R
where <R: Rng>
Extension methods for random number generators
gen
fn gen<T: Rand>(&mut self) -> T
Return a random value for a Rand type
gen_int_range
fn gen_int_range(&mut self, start: int, end: int) -> int
Return an int randomly chosen from the range [start, end), failing if start >= end
gen_uint_range
fn gen_uint_range(&mut self, start: uint, end: uint) -> uint
Return a uint randomly chosen from the range [start, end), failing if start >= end
gen_char_from
fn gen_char_from(&mut self, chars: &str) -> char
Return a char randomly chosen from chars, failing if chars is empty
gen_weighted_bool
fn gen_weighted_bool(&mut self, n: uint) -> bool
Return a bool with a 1-in-n chance of true
gen_str
fn gen_str(&mut self, len: uint) -> ~str
Return a random string of the specified length composed of A-Z,a-z,0-9
gen_bytes
fn gen_bytes(&mut self, len: uint) -> ~[u8]
Return a random byte string of the specified length
choose
fn choose<T: Copy>(&mut self, values: &[T]) -> T
Choose an item randomly, failing if values is empty
choose_option
fn choose_option<T: Copy>(&mut self, values: &[T]) -> Option<T>
Choose Some(item) randomly, returning None if values is empty
choose_weighted
fn choose_weighted<T: Copy>(&mut self, v: &[Weighted<T>]) -> T
Choose an item respecting the relative weights, failing if the sum of the weights is 0
choose_weighted_option
fn choose_weighted_option<T: Copy>(&mut self, v: &[Weighted<T>]) -> Option<T>
Choose Some(item) respecting the relative weights, returning none if the sum of the weights is 0
weighted_vec
fn weighted_vec<T: Copy>(&mut self, v: &[Weighted<T>]) -> ~[T]
Return a vec containing copies of the items, in order, where the weight of the item determines how many copies there are
shuffle
fn shuffle<T: Copy>(&mut self, values: &[T]) -> ~[T]
Shuffle a vec
shuffle_mut
fn shuffle_mut<T>(&mut self, values: &mut [T])
Shuffle a mutable vec in place
IsaacRng
new
fn new() -> IsaacRng
Create an ISAAC random number generator with a random seed.
new_seeded
fn new_seeded(seed: &[u8]) -> IsaacRng
Create an ISAAC random number generator with a seed. This can be any length, although the maximum number of bytes used is 1024 and any more will be silently ignored. A generator constructed with a given seed will generate the same sequence of values as all other generators constructed with the same seed.
new_unseeded
fn new_unseeded() -> IsaacRng
Create an ISAAC random number generator using the default fixed seed.
Rng
for IsaacRng
next
fn next(&mut self) -> u32
Rng
for XorShiftRng
next
fn next(&mut self) -> u32
XorShiftRng
new
fn new() -> XorShiftRng
Create an xor shift random number generator with a default seed.
new_seeded
fn new_seeded(x: u32, y: u32, z: u32, w: u32) -> XorShiftRng
Create a random number generator using the specified seed. A generator constructed with a given seed will generate the same sequence of values as all other generators constructed with the same seed.
Rng
for @mut R
where <R: Rng>
next
fn next(&mut self) -> u32
random
fn random<T: Rand>() -> T
Returns a random value of a Rand type, using the task's random number generator.
rng
fn rng() -> IsaacRng
Create a random number generator with a default algorithm and seed.
seed
fn seed() -> ~[u8]
Create a new random seed.
task_rng
fn task_rng() -> @mut IsaacRng
Gives back a lazily initialized task-local random number generator, seeded by the system. Intended to be used in method chaining style, ie task_rng().gen::<int>()
.