Struct randomize::PCG32

pub struct PCG32 { /* fields omitted */ }

A permuted congruential generator with 32-bits of output per step.

The generator has two values, state and inc, which are both a u64. The state controls "where" in a number stream the generator is. The inc controls which number stream that generator is within in the first place. Any state value is allowed (even 0), but only odd inc values are allowed. So there are 2^64 possible states across 2^63 different streams.

Please see the PCG paper for more info on the how and why of it all.

Methods

impl PCG32

pub fn from_time() -> Self

Makes a new PCG32 using the system time.

Repeated calls to this method in close succession are likely to generate identical generators because the creation process is too fast compared to the usual resolution of a system's clock. If you need more than one generator quickly, make the first one with this method and then after that call gen.any() on the first generator to make all the rest.

use randomize::PCG32;
let gen = PCG32::from_time();

::std::thread::sleep(::std::time::Duration::new(0,50));

let gen2 = PCG32::from_time();

assert_ne!(gen, gen2);

pub fn from_state_and_inc(state: u64, inc: u64) -> Self

Makes a PCG32 using the values given.

The inc value given is OR'd with 1, so that it is always odd in the resulting generator.

use randomize::PCG32;
let gen = PCG32::from_state_and_inc(20, 505);
assert_eq!(gen.state(), 20);
assert_eq!(gen.inc(), 505);

let gen2 = PCG32::from_state_and_inc(300, 0);
assert_eq!(gen2.state(), 300);
assert_eq!(gen2.inc(), 1);

pub fn state(&self) -> u64

Gives the current state value. This changes from use to use.

pub fn inc(&self) -> u64

Gives the inc value. This is fixed across the life of the generator.

pub fn next_u32(&mut self) -> u32

Obtains the next 32-bits of output from the generator.

This is the "actual" function that all the other functions end up calling.

pub fn any<A: AnyRandom>(&mut self) -> A

Generates a value using the AnyRandom instance for the type desired.

use randomize::PCG32;
let gen = &mut PCG32::from_time();
if gen.any() {
  let x: u32 = gen.any();
  println!("x as a u32: {}",x);
} else {
  let x: [char;3] = gen.any();
  println!("x as an array of 3 chars: {:?}",x);
}

pub fn any_ascii(&mut self) -> char

Returns a char value in the ASCII range (0-127).

use randomize::PCG32;
let gen = &mut PCG32::from_time();
for _ in 0 .. 5_000 {
  assert!((gen.any_ascii() as u8) <= 127);
}

pub fn any_f32_zero_to_one(&mut self) -> f32

Returns an f32 value in the inclusive range 0.0 to 1.0.

use randomize::PCG32;
let gen = &mut PCG32::from_time();
for _ in 0 .. 5_000 {
  let f = gen.any_f32_zero_to_one();
  assert!(f >= 0.0 && f <= 1.0);
}

pub fn percent_chance(&mut self, chance: f32) -> bool

Returns true a percentage of the time (eg: 0.3 for 30%).

With how many different floating point values there are in that range, this is "close enough" to the correct chances for most people. If you want exact odds you'll have to do some integral math, call next_u32, and potentially do re-rolls and stuff (which is what in_range does).

use randomize::PCG32;
let gen = &mut PCG32::from_time();
let mut hits = 0i32;
for _ in 0 .. 100_000 {
  if gen.percent_chance(0.3) {
    hits += 1;
  }
}
// the exact number is random, so we can only say it'll be "close enough"
assert!((hits - 30_000).abs() < 1_000);

// inputs that are "out of range" will always be `true` or `false`.
assert!(gen.percent_chance(1.0));
assert!(gen.percent_chance(1.1));
assert!(!gen.percent_chance(0.0));
assert!(!gen.percent_chance(-8.5));

pub fn in_range<R: Borrow<Range<usize>>>(&mut self, r: R) -> Option<usize>

Gives a value in the Range specified (inclusive of the bottom but exclusive of the top).

Every position within an inhabited range will have an equal chance of being the result. This is a somewhat more expensive than a single mod operation, so if you want speed over precision you can also do something like gen.any() % thing.len().

Gives None if the range is empty.

use randomize::PCG32;
let gen = &mut PCG32::from_time();
for &base in [0, 456, 93498383].iter() {
  for &width in [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 20, 40, 50].iter() {
    let range = base .. (base+width);
    let out = gen.in_range(range.clone()).unwrap();
    assert!(out >= range.start && out < range.end);
  }
}
assert_eq!(gen.in_range(7..4), None);

Trait Implementations

impl Debug for PCG32

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl PartialEq for PCG32

fn eq(&self, __arg_0: &PCG32) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, __arg_0: &PCG32) -> bool

This method tests for !=.

impl Eq for PCG32

impl Hash for PCG32

fn hash<__H: Hasher>(&self, __arg_0: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl PartialOrd<PCG32> for PCG32

fn partial_cmp(&self, other: &PCG32) -> Option<Ordering>

The ordering here is not meaningful, but it is consistent and total.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Ord for PCG32

fn cmp(&self, other: &PCG32) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

impl AnyRandom for PCG32

fn from_pcg32(gen: &mut PCG32) -> Self

Makes a value of the type from the given RNG.