[−][src]Crate randomize

Simple and minimalist randomization.

NOT FOR CRYPTOGRAPHIC PURPOSES.

Basic Usage

  • Pick a generator, PCG32 or PCG64, depending on the output type you want. PCG32 runs about 20% faster, so if you usually need 32 bits or less per use you might as well pick that.
  • Seed your generator from wherever. However you wanna do it that your platform supports. Major options would be the getrandom crate, a hardware generator if available, the CPU timing counter if there's no hardware generator, or even just a user input.
  • The generators have a state and inc value. The state will change with each call, the inc is like a stream selection value that doesn't change when you use the generator. If you don't care about stream selection just pass your seed value to both arguments and it'll all "just work".
  • Call next_u32 or next_u64 to get your numbers.
  • You can use RandRangeU32 for bounded integer randomization.

That's it, that's the whole lib. No generics, no traits, no breaking changes issued as patch releases, none of that.

Any-size Integrals

Where generating u32s or u64s is not enough, you can wrap your generator inside an AnyPCG to generate non-floating-point integral values of any size.

  • Create a fixed-size generator, e.g. let gen = PCG32::new(…);
  • Create an any-size generator from it: let any = AnyPCG::new(gen);
  • Call the provided next_* functions for the corresponding integral types, such as next_u16 to generate a u16 while only taking 16 bits out of the random bit streams.

The more efficient use of generated bits comes at a barely noticeable cost for PCG32, and a bigger one for PCG64. This only matters for batch generation of big amounts of random data, though.

Floating Point

Unfortunately, there's many possible float distributions a person might want, so you'll have to call one of the float conversion functions yourself. I've included conversions for the five most commonly used floating point ranges.

Range32-bit64-bit
[0.0, 1.0)f32_half_open_rightf64_half_open_right
(0.0, 1.0]f32_half_open_leftf64_half_open_left
(0.0, 1.0)f32_openf64_open
[0.0, 1.0]f32_closedf64_closed
[-1.0, 1.0]f32_closed_neg_posf64_closed_neg_pos

Re-exports

pub use formulas::*;

Modules

formulas

Various generator and conversion formulas. This module is a "junk drawer" of stuff.

Structs

AnyPCG

A wrapper around PCG types that generates any-size outputs without wasting random bits.

PCG32

A permuted congruential generator with 32-bit output. Pick this by default.

PCG64

A permuted congruential generator with 64-bit output. Pick this if you want to do stuff with f64 values.

RandRangeU32

An inclusive random range with a u32 low and high value.