#rand #random #no-std #entropy

no-std nanorand

A tiny, fast, zero-dep library for random number generation

13 releases (5 breaking)

0.5.2 Dec 30, 2020
0.5.1 Dec 7, 2020
0.4.4 Sep 23, 2020
0.3.0 Sep 13, 2020
0.0.0 Sep 6, 2020

#31 in Algorithms

Download history 218/week @ 2020-11-07 259/week @ 2020-11-14 821/week @ 2020-11-21 1335/week @ 2020-11-28 3333/week @ 2020-12-05 3157/week @ 2020-12-12 3037/week @ 2020-12-19 3014/week @ 2020-12-26 4662/week @ 2021-01-02 4636/week @ 2021-01-09 4533/week @ 2021-01-16 6519/week @ 2021-01-23 5964/week @ 2021-01-30 5319/week @ 2021-02-06 4878/week @ 2021-02-13 5395/week @ 2021-02-20

5,156 downloads per month
Used in 14 crates (9 directly)

Zlib license

34KB
733 lines

crates.io docs.rs License: Zlib Tests Average time to resolve an issue Percentage of issues still open Maintenance

nanorand

Current version: 0.5.2

A library meant for fast, random number generation with quick compile time, and minimal dependencies.

Examples

Generating a number with an initialized RNG

use nanorand::{RNG, WyRand};

let mut rng = WyRand::new();
println!("Random number: {}", rng.generate::<u64>());

Generating a number with a thread-local RNG

use nanorand::RNG;

let mut rng = nanorand::tls_rng();
println!("Random number: {}", rng.generate::<u64>());

Generating a number in a range

use nanorand::{RNG, WyRand};

let mut rng = WyRand::new();
println!("Random number between 1 and 100: {}", rng.generate_range::<u64>(1, 100));

Shuffling a Vec

use nanorand::{RNG, WyRand};

let mut rng = WyRand::new();
let mut items = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
rng.shuffle(&mut items);

Why should I use this over...

  • rand - The standard rand crate is a complex beast. It contains unsafe code in the core implementations, and while it has much more options than we do, that's kind of the point. We're straight to the point, while rand is everything and the kitchen sink.
  • fastrand, oorandom, random-fast-rng, or randomize - These are all minimal, zero-dep implementations of the PCG family of RNGs (Pcg32 and Pcg64). While these are decent, they are much slower than wyrand (which beats the speed of these Pcg32 implementations while providing 64 random bits), and do not provide CSPRNGs.
  • getrandom - The getrandom crate just provides OS entropy sources. It is not meant for random number generation. In fact, we provide it as an optional entropy source.

RNG Implementations

RNG nanorand type Output Size Cryptographically Secure Speed1 Notes Original Implementation
wyrand nanorand::WyRand, nanorand::tls::TlsWyRand 64 bits (u64) 🚫 10.09 GB/s https://github.com/lemire/testingRNG/blob/master/source/wyrand.h
Pcg64 nanorand::Pcg64 64 bits (u64) 🚫 2.3 GB/s https://github.com/rkern/pcg64
ChaCha nanorand::ChaCha 512 bits ([u32; 16]) 150 MB/s (ChaCha8), 70 MB/s (ChaCha20) Only works in Rust 1.47 or above https://cr.yp.to/chacha.html

1. Speed benchmarked on an Intel Core i7 8086k processor running at 5.1 GHz

Entropy Sources

Listed in order of priority

  • If the getrandom feature is enabled, then getrandom::getrandom will be called.
  • If the rdseed feature is enabled, and is running on an x86(-64) system with the RDSEED instruction, then we will attempt to source as much entropy as possible via our rdseed_entropy function
  • Linux and Android will attempt to use the getrandom syscall.
  • macOS and iOS (Darwin-based systems) will use Security.framework's SecRandomCopyBytes.
  • Windows
    • If we're targeting UWP, then the BCryptGenRandom is used with system-preferred RNG (BCRYPT_USE_SYSTEM_PREFERRED_RNG).
    • Otherwise, we'll use RtlGenRandom.
  • If all else fails, and the std feature is enabled, we'll resort to pulling bytes from the current system unix time ([entropy::emergency_system_time_entropy]), and screwing with them via XOR and endianness operations.

Feature Flags

  • std (default) - Enables Rust std lib features, such as seeding from OS entropy sources.
  • tls (default) - Enables a thread-local WyRand RNG (see below). Requires tls to be enabled.
  • wyrand (default) - Enable the wyrand RNG.
  • pcg64 (default) - Enable the Pcg64 RNG.
  • chacha - Enable the ChaCha RNG. Requires Rust 1.47 or later.
  • rdseed - On x86/x86_64 platforms, the rdseed intrinsic will be used when OS entropy isn't available.
  • zeroize - Implement the Zeroize trait for all RNGs.
  • getrandom - Use the getrandom crate as an entropy source. Works on most systems, optional due to the fact that it brings in more dependencies.

License

The zlib/libpng License

Copyright (c) 2020 aspen

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

  3. This notice may not be removed or altered from any source distribution.

Dependencies

~0–295KB