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.

Examples

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))
}

Struct 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.

Struct 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

Struct 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.

Trait Rand

A type that can be randomly generated using an Rng

Method rand

fn rand<R: Rng>(rng: &mut R) -> Self

Generates a random instance of this type using the specified source of randomness

Trait Rng

A random number generator

Method next

fn next(&mut self) -> u32

Return the next random integer

Trait RngUtil

Helper functions attached to the Rng type

Method gen

fn gen<T: Rand>(&mut self) -> T

Return a random value of a Rand type

Method 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

Method 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

Method gen_char_from

fn gen_char_from(&mut self, chars: &str) -> char

Return a char randomly chosen from chars, failing if chars is empty

Method gen_weighted_bool

fn gen_weighted_bool(&mut self, n: uint) -> bool

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)));
}

Method 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

Example


use core::rand::RngUtil;

fn main() {
    rng = rand::rng();
    println(rng.gen_str(8));
}

Method gen_bytes

fn gen_bytes(&mut self, len: uint) -> ~[u8]

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)));
}

Method choose

fn choose<T: Copy>(&mut self, values: &[T]) -> T

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])));
}

Method choose_option

fn choose_option<T: Copy>(&mut self, values: &[T]) -> Option<T>

Choose Some(item) randomly, returning None if values is empty

Method 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

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)));
}

Method 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

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)));
}

Method 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

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)));
}

Method shuffle

fn shuffle<T: Copy>(&mut self, values: &[T]) -> ~[T]

Shuffle a vec

Example


use core::rand::RngUtil;

fn main() {
    rng = rand::rng();
    println(fmt!("%?",rng.shuffle([1,2,3])));
}

Method shuffle_mut

fn shuffle_mut<T>(&mut self, values: &mut [T])

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));
}

Implementation of Rand for int

Method rand

fn rand<R: Rng>(rng: &mut R) -> int

Implementation of Rand for i8

Method rand

fn rand<R: Rng>(rng: &mut R) -> i8

Implementation of Rand for i16

Method rand

fn rand<R: Rng>(rng: &mut R) -> i16

Implementation of Rand for i32

Method rand

fn rand<R: Rng>(rng: &mut R) -> i32

Implementation of Rand for i64

Method rand

fn rand<R: Rng>(rng: &mut R) -> i64

Implementation of Rand for uint

Method rand

fn rand<R: Rng>(rng: &mut R) -> uint

Implementation of Rand for u8

Method rand

fn rand<R: Rng>(rng: &mut R) -> u8

Implementation of Rand for u16

Method rand

fn rand<R: Rng>(rng: &mut R) -> u16

Implementation of Rand for u32

Method rand

fn rand<R: Rng>(rng: &mut R) -> u32

Implementation of Rand for u64

Method rand

fn rand<R: Rng>(rng: &mut R) -> u64

Implementation of Rand for float

Method rand

fn rand<R: Rng>(rng: &mut R) -> float

Implementation of Rand for f32

Method rand

fn rand<R: Rng>(rng: &mut R) -> f32

Implementation of Rand for f64

Method rand

fn rand<R: Rng>(rng: &mut R) -> f64

Implementation of Rand for char

Method rand

fn rand<R: Rng>(rng: &mut R) -> char

Implementation of Rand for bool

Method rand

fn rand<R: Rng>(rng: &mut R) -> bool

Implementation of Rand for ()

Method rand

fn rand<R: Rng>(_: &mut R)

Implementation of Rand for (A,) where <A: Rand>

Method rand

fn rand<R: Rng>(_rng: &mut R) -> (A,)

Implementation of Rand for (A, B) where <A: Rand, B: Rand>

Method rand

fn rand<R: Rng>(_rng: &mut R) -> (A, B)

Implementation of Rand for (A, B, C) where <A: Rand, B: Rand, C: Rand>

Method rand

fn rand<R: Rng>(_rng: &mut R) -> (A, B, C)

Implementation of Rand for (A, B, C, D) where <A: Rand, B: Rand, C: Rand, D: Rand>

Method rand

fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D)

Implementation of Rand for (A, B, C, D, E) where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand>

Method rand

fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E)

Implementation of Rand for (A, B, C, D, E, F) where <A: Rand, B: Rand, C: Rand, D: Rand, E: Rand, F: Rand>

Method rand

fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E, F)

Implementation 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>

Method rand

fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E, F, G)

Implementation 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>

Method rand

fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E, F, G, H)

Implementation 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>

Method rand

fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E, F, G, H, I)

Implementation 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>

Method rand

fn rand<R: Rng>(_rng: &mut R) -> (A, B, C, D, E, F, G, H, I, J)

Implementation of Rand for Option<T> where <T: Rand>

Method rand

fn rand<R: Rng>(rng: &mut R) -> Option<T>

Implementation of Rand for ~T where <T: Rand>

Method rand

fn rand<R: Rng>(rng: &mut R) -> ~T

Implementation of Rand for @T where <T: Rand>

Method rand

fn rand<R: Rng>(rng: &mut R) -> @T

Implementation of RngUtil for R where <R: Rng>

Extension methods for random number generators

Method gen

fn gen<T: Rand>(&mut self) -> T

Return a random value for a Rand type

Method 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

Method 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

Method gen_char_from

fn gen_char_from(&mut self, chars: &str) -> char

Return a char randomly chosen from chars, failing if chars is empty

Method gen_weighted_bool

fn gen_weighted_bool(&mut self, n: uint) -> bool

Return a bool with a 1-in-n chance of true

Method 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

Method gen_bytes

fn gen_bytes(&mut self, len: uint) -> ~[u8]

Return a random byte string of the specified length

Method choose

fn choose<T: Copy>(&mut self, values: &[T]) -> T

Choose an item randomly, failing if values is empty

Method choose_option

fn choose_option<T: Copy>(&mut self, values: &[T]) -> Option<T>

Choose Some(item) randomly, returning None if values is empty

Method 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

Method 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

Method 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

Method shuffle

fn shuffle<T: Copy>(&mut self, values: &[T]) -> ~[T]

Shuffle a vec

Method shuffle_mut

fn shuffle_mut<T>(&mut self, values: &mut [T])

Shuffle a mutable vec in place

Implementation for IsaacRng

Method new

fn new() -> IsaacRng

Create an ISAAC random number generator with a random seed.

Method 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.

Method new_unseeded

fn new_unseeded() -> IsaacRng

Create an ISAAC random number generator using the default fixed seed.

Implementation of Rng for IsaacRng

Method next

fn next(&mut self) -> u32

Implementation of Rng for XorShiftRng

Method next

fn next(&mut self) -> u32

Implementation for XorShiftRng

Method new

fn new() -> XorShiftRng

Create an xor shift random number generator with a default seed.

Method 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.

Implementation of Rng for @mut R where <R: Rng>

Method next

fn next(&mut self) -> u32

Function random

fn random<T: Rand>() -> T

Returns a random value of a Rand type, using the task's random number generator.

Function rng

fn rng() -> IsaacRng

Create a random number generator with a default algorithm and seed.

Function seed

fn seed() -> ~[u8]

Create a new random seed.

Function 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>().