Generate random numbers using only standard library

Overview

This Rust crate provides various random number generation utilities, including:

• Random unsigned u8,u16,u32,u64,u128,usize generation.
• Non negative integer i8,i16,i32,i64,i128,isize generation
• Floating-point randomness (f32 and f64) in [0,1).
• Random byte filling for buffers.
• Random range filling for slices.
• Random number generation from range.
• High entropy random number generation by using separate thread RandomState.
• Fast but lower-entropy alternatives using thread local RandomState.

Features

• Minimal supported Rust version 1.56. Entire 2021 Rust edition is supported.
• No external dependencies beyond standard Rust library.
• Thread-based randomness: Uses separate threads for improved entropy (random_*()).
• Secure and fast implementations for generating random numbers.
• Uniform distribution ensured for floating-point values.

Functions returning random numbers

random_u128(), random_u64(), random_u32(), random_u16(), random_u8(), random_usize()

Generates a unsigned integer high entropy random number in a separate thread. These numbers are unpredictable - true randoms. Numbers have uniform distribution and pass chi square test with very good score. While they are not certified for cryptographic purposes, they are good source of randomness for seeding other random generators.

fast_u128(), fast_u64(), fast_u32(), fast_u16(), fast_u8(), fast_usize()

Generates a lower entropy random number from the current thread. This randomness is much faster and still maintains a uniform distribution. The first number generated in the thread is fully random; the rest are derived from the initial seed by a very low-quality PRNG algorithm.

Internally, the Rust library uses SipHash13 with a 2×64-bit internal state, which is incremented by one on each call, resulting in progressively lower randomness.

As expected, the chi-square test score for uniform distribution is several times worse than in the random_ family. While the chi-square test result is worse, it is still within the widely accepted limits for fast random number generators.

The generated numbers fail the independent bit test. This test focuses on relationships between bits in the output and finds patterns like: if the 1st bit is One, there is an 85% chance that the 9th bit is also One.

From fast_u32(), you can expect about 17 bits of good randomness. The original author claims 21 bits, but based on my testing, this is definitely too optimistic. Smaller output sizes have a better percentage of random bits. fast_u64() scores much worse than fast_u32(). Because the bits are not fully independent, do not XOR the generated output with itself.

These fast random numbers are definitely not suitable for generating cryptographic keys or for applications requiring hash resistance. They are suitable if you need some random bits for tasks like generating unique file names, where collisions are unlikely.

random_i128(), random_i64(), random_i32(), random_i16(), random_i8(), random_isize()

Non negative integer derived from random_u*() functions.

fast_i128(), fast_i64(), fast_i32(), fast_i16(), fast_i8(), fast_isize()

Non negative integer derived from fast_u*() functions.

random_f64(), random_f32()

Generates a high entropy random floating point number in a separate thread from in [0, 1) range. These numbers have uniform distribution and pass chi square test.

fast_f32(), fast_f64()

Generates a lower entropy random floating point number in [0, 1).

Helper Functions

fill_bytes(), fill_numbers()

Fills slice with random numbers from provided random number generator.

gen_range(), fill_range()

Generate random number from specified range and fill slice.

No copyright

This is free and unencumbered software released into the public domain.

You may use, modify, distribute, and contribute to this code without restriction. To the extent possible under law, the author(s) of this work waive all copyright and related rights.

Licensed under CC0-1.0 OR Unlicense.