Crate perchance

perchance is a simple random number generation library, tuned for ease of use: create an instance of PerchanceContext and go.

Note that perchance is not cryptographically secure and should not be used in any context where security is a concern.

When the std feature is enabled (by default), there’s a global PerchanceContext provided, too.

Example

First, create a PerchanceContext:

let mut rng = perchance::PerchanceContext::new(my_seed);

Or, if you have the std feature enabled, obtain the global PerchanceContext object:

// Seed the global context first. You may do so manually, or, on platforms that support it,
// obtain a seed to pass into it by calling `perchance::gen_time_seed()`.
perchance::seed_global(0x5F3759DF); // ;)

let mut rng = perchance::global();

Then, start letting things happen perchance!

let between_0_and_1 = rng.uniform_f32();
let dice_roll = rng.uniform_range_i32(1..=6);
let random_direction = rng.uniform_sphere_surface_vec3();
let thing_should_happen = rng.get_bool();

enum Event {
    Thing1,
    Thing2,
    Thing3,
}
let which_should_happen = rng.choose(&[Event::Thing1, Event::Thing2, Event::Thing3]);

Some of the convenience functions exist in multiple flavors with different return types.

Perchance does NOT guarantee the same random number generator across new versions of the crate.

Structs

PerchanceContext

WeightedSampler

Functions

gen_time_seed

Generates a seed that may be passed to perchance::seed_global based on the system clock.

global

Returns the global PerchanceContext. You must seed it by calling perchance::seed_global at least once before calling this function or else it will panic.

global_has_been_seeded

Returns true if perchance::seed_global has been called at least once.

seed_global

Seed (or reseed) the global PerchanceContext returned by perchance::global.