Random

Data Structures
struct	bj_pcg32

Macros
#define	BJ_RAND_MAX   0x7FFF
#define	bj_uniform_real_distribution   bj_uniform_float_distribution
#define	bj_normal_real_distribution   bj_normal_float_distribution
#define	bj_normal_real_minmax_distribution   bj_normal_float_minmax_distribution

Typedefs
typedef uint32_t(*	bj_random_u32_fn) (void *state)

Functions
void	bj_srand (unsigned int seed)
int	bj_rand (void)
void	bj_seed_pcg32 (struct bj_pcg32 *generator, uint64_t seed, uint64_t seq)
uint32_t	bj_next_pcg32 (struct bj_pcg32 *generator)
void	bj_discard_pcg32 (struct bj_pcg32 *generator, uint64_t z)
uint32_t	bj_min_pcg32 (void)
uint32_t	bj_max_pcg32 (void)
static uint32_t	bj_pcg32_generator (void *state)
int32_t	bj_uniform_int32_distribution (bj_random_u32_fn next, void *state, int32_t low, int32_t high)
float	bj_uniform_float_distribution (bj_random_u32_fn next, void *state, float low, float high)
double	bj_uniform_double_distribution (bj_random_u32_fn next, void *state, double low, double high)
long double	bj_uniform_long_double_distribution (bj_random_u32_fn next, void *state, long double low, long double high)
int	bj_bernoulli_distribution (bj_random_u32_fn next, void *state, bj_real probability)
float	bj_normal_float_distribution (bj_random_u32_fn next, void *state, float mean, float standard_deviation)
double	bj_normal_double_distribution (bj_random_u32_fn next, void *state, double mean, double standard_deviation)
long double	bj_normal_long_double_distribution (bj_random_u32_fn next, void *state, long double mean, long double standard_deviation)
float	bj_normal_float_minmax_distribution (bj_random_u32_fn next, void *state, float min, float max)
double	bj_normal_double_minmax_distribution (bj_random_u32_fn next, void *state, double min, double max)
long double	bj_normal_long_double_minmax_distribution (bj_random_u32_fn next, void *state, long double min, long double max)

Detailed Description

Generate random-looking numbers from a generator, then shape them into useful distributions.

Computers can't produce truly random numbers; they produce pseudo-random numbers: a deterministic sequence that looks random enough to be useful. The function that produces the next number from the previous one is called a pseudo-random number generator (PRNG). Banjo gives you two PRNGs to choose from, plus helpers to turn raw random numbers into the shapes you actually want (a die roll between 1 and 6, a coordinate inside a circle, a normally distributed measurement…).

Two generators: pick one

• bj_rand / bj_srand work like C's standard rand / srand: one process-wide generator state, one function call to get a number. Cheap, but its sequence has well-known weaknesses, so don't use it for anything where statistical quality matters (cryptographic anything, scientific simulation, procedural content where players might detect patterns).
• bj_pcg32 is the modern PCG32 generator. You manage one or more bj_pcg32 objects yourself (each is just a struct holding the state), initialise them with bj_seed_pcg32, and draw the next 32-bit value with bj_next_pcg32. Much better statistical quality than bj_rand, still very fast.

PCG32 supports independent streams: each bj_pcg32 can be given a different seq value at seeding time, and the resulting sequences will be independent of each other even if seeded from the same number. Useful for giving each subsystem of a game (terrain, AI, loot drops) its own generator so that adding code to one doesn't shift the randomness of the others, which makes replays and reproducible bugs much easier.

Distributions: turn raw random numbers into useful ones

A PRNG hands you flat 32-bit integers. You usually want something shaped differently: an integer in a range, a float between two bounds, a bool that's true 30% of the time, a number on a bell-curve around a mean. Each shape is called a distribution, and Banjo provides the common ones:

• Uniform integer in [low, high]: bj_uniform_int32_distribution
• Uniform real in [low, high): bj_uniform_float_distribution / _double / _long_double, plus the type-agnostic bj_uniform_real_distribution macro that picks the right one for your build's precision.
• Bernoulli (true with given probability p): bj_bernoulli_distribution
• Normal (Gaussian): bj_normal_float_distribution / _double / _long_double, plus convenience variants that take a min/max range instead of mean/stddev.

Distribution functions don't care which generator you use; they take a callback (bj_random_u32_fn) that returns the next 32-bit value, plus an opaque state pointer. For PCG32 the adapter bj_pcg32_generator does the right thing: pass that with your bj_pcg32* and the distributions work straight away:

bj_pcg32 rng;
bj_seed_pcg32(&rng, 42, 0);
 
int32_t roll  = bj_uniform_int32_distribution(bj_pcg32_generator, &rng, 1, 6);
double  noise = bj_uniform_double_distribution(bj_pcg32_generator, &rng, -1.0, 1.0);
bj_real iq    = bj_normal_real_distribution(bj_pcg32_generator, &rng, 100.0, 15.0);

See also

random.c and random_distribution.c for runnable demos.

---

Data Structure Documentation

bj_pcg32

struct bj_pcg32

PCG32 generator state.

Examples

random.c.

Definition at line 114 of file random.h.

Data Fields
uint64_t	inc	Stream selector; odd recommended, 0 allowed.
uint64_t	state	Current internal state (updated each step).

Macro Definition Documentation

bj_normal_real_distribution

#define bj_normal_real_distribution   bj_normal_float_distribution

Alias to the real-typed normal distribution for the active precision.

Maps to:

• bj_normal_long_double_distribution if BJ_API_LONG_DOUBLE
• bj_normal_double_distribution if BJ_API_FLOAT64
• bj_normal_float_distribution otherwise

Examples

random_distribution.c.

Definition at line 334 of file random.h.

Referenced by run_distributions().

bj_normal_real_minmax_distribution

#define bj_normal_real_minmax_distribution   bj_normal_float_minmax_distribution

Alias to the real-typed min/max normal for the active precision.

Maps to:

• bj_normal_long_double_minmax_distribution if BJ_API_LONG_DOUBLE
• bj_normal_double_minmax_distribution if BJ_API_FLOAT64
• bj_normal_float_minmax_distribution otherwise

Definition at line 410 of file random.h.

BJ_RAND_MAX

#define BJ_RAND_MAX   0x7FFF

Maximum value returned by bj_rand().

Matches the stdlib idea of RAND_MAX. Values from bj_rand() are distributed in [0, BJ_RAND_MAX].

Definition at line 91 of file random.h.

bj_uniform_real_distribution

#define bj_uniform_real_distribution   bj_uniform_float_distribution

Alias to the real-typed uniform distribution for the active precision.

Maps to:

• bj_uniform_long_double_distribution if BJ_API_LONG_DOUBLE
• bj_uniform_double_distribution if BJ_API_FLOAT64
• bj_uniform_float_distribution otherwise

Definition at line 259 of file random.h.

Typedef Documentation

bj_random_u32_fn

typedef uint32_t(* bj_random_u32_fn) (void *state)

RNG callback type for generator-agnostic distributions.

Parameters

state

Opaque engine state pointer.

Returns

Next 32-bit pseudo-random value.

Definition at line 183 of file random.h.

Function Documentation

bj_bernoulli_distribution()

int bj_bernoulli_distribution	(	bj_random_u32_fn	next,
		void *	state,
		bj_real	probability )

Bernoulli(probability).

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
probability	Probability in [0,1].

Returns

1 with the given probability, else 0.

Examples

random_distribution.c.

Referenced by run_distributions().

bj_discard_pcg32()

void bj_discard_pcg32	(	struct bj_pcg32 *	generator,
		uint64_t	z )

Advance the generator state by z steps.

Parameters

generator	Generator pointer (must not be NULL).
z	Number of steps to skip ahead.

Examples

random.c.

Referenced by main().

bj_max_pcg32()

uint32_t bj_max_pcg32

(

void

)

Largest possible value returned by the generator.

Returns

Always 0xFFFFFFFF.

Examples

random.c.

Referenced by main().

bj_min_pcg32()

uint32_t bj_min_pcg32

(

void

)

Smallest possible value returned by the generator.

Returns

Always 0.

Examples

random.c.

Referenced by main().

bj_next_pcg32()

uint32_t bj_next_pcg32

(

struct bj_pcg32 *

generator

)

Advance the generator and return the next 32-bit value.

Parameters

generator

Generator pointer (must not be NULL).

Returns

Next 32-bit pseudo-random value.

Examples

random.c.

Referenced by bj_pcg32_generator(), main(), and pcg32_u64().

bj_normal_double_distribution()

double bj_normal_double_distribution	(	bj_random_u32_fn	next,
		void *	state,
		double	mean,
		double	standard_deviation )

Normal double N(mean, standard_deviation^2).

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
mean	Mean.
standard_deviation	Standard deviation (>= 0).

Returns

double sample.

bj_normal_double_minmax_distribution()

double bj_normal_double_minmax_distribution	(	bj_random_u32_fn	next,
		void *	state,
		double	min,
		double	max )

Normal from min/max convenience (μ ≈ (min+max)/2, σ ≈ (max-min)/6).

Interprets min ≈ μ − 3σ and max ≈ μ + 3σ, then calls the typed normal distribution. Samples are not guaranteed to lie inside [min, max].

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
min	Approximate lower limit (treated as μ − 3σ).
max	Approximate upper limit (treated as μ + 3σ).

Returns

One sample from N(μ, σ²) with μ,σ derived from min/max.

bj_normal_float_distribution()

float bj_normal_float_distribution	(	bj_random_u32_fn	next,
		void *	state,
		float	mean,
		float	standard_deviation )

Normal float N(mean, standard_deviation^2).

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
mean	Mean.
standard_deviation	Standard deviation (>= 0).

Returns

float sample.

bj_normal_float_minmax_distribution()

float bj_normal_float_minmax_distribution	(	bj_random_u32_fn	next,
		void *	state,
		float	min,
		float	max )

Normal from min/max convenience (μ ≈ (min+max)/2, σ ≈ (max-min)/6).

Interprets min ≈ μ − 3σ and max ≈ μ + 3σ, then calls the typed normal distribution. Samples are not guaranteed to lie inside [min, max].

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
min	Approximate lower limit (treated as μ − 3σ).
max	Approximate upper limit (treated as μ + 3σ).

Returns

One sample from N(μ, σ²) with μ,σ derived from min/max.

bj_normal_long_double_distribution()

long double bj_normal_long_double_distribution	(	bj_random_u32_fn	next,
		void *	state,
		long double	mean,
		long double	standard_deviation )

Normal long double N(mean, standard_deviation^2).

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
mean	Mean.
standard_deviation	Standard deviation (>= 0).

Returns

long double sample.

bj_normal_long_double_minmax_distribution()

long double bj_normal_long_double_minmax_distribution	(	bj_random_u32_fn	next,
		void *	state,
		long double	min,
		long double	max )

Normal from min/max convenience (μ ≈ (min+max)/2, σ ≈ (max-min)/6).

Interprets min ≈ μ − 3σ and max ≈ μ + 3σ, then calls the typed normal distribution. Samples are not guaranteed to lie inside [min, max].

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
min	Approximate lower limit (treated as μ − 3σ).
max	Approximate upper limit (treated as μ + 3σ).

Returns

One sample from N(μ, σ²) with μ,σ derived from min/max.

bj_pcg32_generator()

uint32_t bj_pcg32_generator ( void * state )

inlinestatic

Adapter for distribution API (void* state).

Allows struct bj_pcg32 to be used with callbacks of type uint32_t (*)(void* state).

Parameters

state

Pointer to struct bj_pcg32.

Returns

Next 32-bit pseudo-random value.

Examples

random_distribution.c.

Definition at line 173 of file random.h.

Referenced by run_distributions().

bj_rand()

int bj_rand

(

void

)

Generate a pseudo-random integer in [0, BJ_RAND_MAX].

Linear congruential generator (LCG) using: X_{n+1} = (1103515245 * X_n + 12345) mod 2^31

Returns the high-order bits truncated to BJ_RAND_MAX range.

Returns

Integer in [0, BJ_RAND_MAX].

Examples

random.c.

Referenced by main().

bj_seed_pcg32()

void bj_seed_pcg32	(	struct bj_pcg32 *	generator,
		uint64_t	seed,
		uint64_t	seq )

Set the generator state from seed and sequence.

Parameters

generator	Generator pointer (must not be NULL).
seed	Initial seed value.
seq	Stream selector (LSB forced to 1 internally).

Examples

random.c.

Referenced by main().

bj_srand()

void bj_srand

(

unsigned int

seed

)

Seed the standard PRNG.

Parameters

seed	Seed value. Same seed reproduces the same sequence.

Examples

random.c.

Referenced by main().

bj_uniform_double_distribution()

double bj_uniform_double_distribution	(	bj_random_u32_fn	next,
		void *	state,
		double	low,
		double	high )

Uniform double in [low, high).

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
low	Inclusive lower bound.
high	Exclusive upper bound.

Returns

double in [low, high).

bj_uniform_float_distribution()

float bj_uniform_float_distribution	(	bj_random_u32_fn	next,
		void *	state,
		float	low,
		float	high )

Uniform float in [low, high).

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
low	Inclusive lower bound.
high	Exclusive upper bound.

Returns

float in [low, high).

bj_uniform_int32_distribution()

int32_t bj_uniform_int32_distribution	(	bj_random_u32_fn	next,
		void *	state,
		int32_t	low,
		int32_t	high )

Uniform 32-bit integer in [low, high].

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
low	Inclusive lower bound.
high	Inclusive upper bound.

Returns

int32 in [low, high].

Examples

random_distribution.c.

Referenced by run_distributions().

bj_uniform_long_double_distribution()

long double bj_uniform_long_double_distribution	(	bj_random_u32_fn	next,
		void *	state,
		long double	low,
		long double	high )

Uniform long double in [low, high).

Parameters

next	RNG callback (e.g., bj_pcg32_generator).
state	Opaque engine state for next.
low	Inclusive lower bound.
high	Exclusive upper bound.

Returns

long double in [low, high).