Rapidrand

https://docs.rs/rapidrand/0.1.2
Admin
Rapidrand is an extremely fast pseudo-random number generator in Rust, using the rapidhash mixing...
Tokens:7,140
Snippets:75
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Rapidrng Single Constant Example

Source: https://docs.rs/rapidrand/0.1.2/src/rapidrand/lib.rs.html

Illustrates the use of `rapidrng_single`, a variant that uses a single constant. It is noted to have a statistical weakness of consecutive repeats, unlike `rapidrng`.

```rust
/// Generate a pseudorandom number using rapidhash mixing, with a single constant.
///
/// This PRNG is not a cryptographic random number generator.
///
/// Prefer [`rapidrng`]: it is equally fast and avoids the statistical defect described below.
///
/// # Performance
///
/// This uses a single constant instead of two. In hot loops the compiler hoists both constants
/// into registers and the generated inner loop is identical to [`rapidrng`] (instruction-for-
/// -instruction on aarch64), so wall-time performance is the same. The single constant only helps
/// at cold call sites — one fewer 64-bit constant to materialise (a 10-byte `movabs` on x86-64,
/// `mov` + 3×`movk` on aarch64) — and frees one register under register pressure.
///
/// This implementation is equivalent in logic and performance to
/// [wyhash::w1rand](https://github.com/wangyi-fudan/wyhash).
///
/// # Statistical weakness: consecutive repeats
///
/// Reusing the increment constant as the xor constant creates exact consecutive repeats. Whenever
/// the post-increment state satisfies `state & RAPID_SECRET_ADD == 0`, the next increment carries
/// nowhere, so `state + RAPID_SECRET_ADD == state ^ RAPID_SECRET_ADD`. The folded multiply is
/// commutative in its arguments, so the *next* output exactly equals the current one.
///
/// The number of repeat states is 2^z where z is the number of zero bits in the constant, doubled
/// if its top bit is set (the wrapping add discards the carry out of bit 63, freeing that state
/// bit). `RAPID_SECRET_ADD` has 32 set bits and a clear top bit, so exactly 2^32 of the 2^64
/// states trigger this: an identical adjacent output pair once per ~2^32 draws on average — a few
/// seconds of continuous generation — where a truly random stream would produce one every 2^64
/// draws. A different constant cannot avoid this: good multiplicative constants have roughly half
/// their bits set, pinning the rate near 2^-32. Upstream `w1rand` shares the defect (33 set bits,
/// top bit set: also exactly 2^32 repeat states). PractRand and BigCrush do not test adjacent-word
/// equality and pass this generator regardless, but a dedicated test detects the bias within
/// seconds, and any use that treats consecutive outputs as unique (e.g. forming 128-bit values
/// from adjacent draws) inherits it.
///
/// [`rapidrng`]'s two-constant pair has zero states satisfying `state + RAPID_SECRET_ADD ==
/// state ^ RAPID_SECRET_XOR` (the required carry pattern is inconsistent), so it never repeats
/// consecutively.
#[inline(always)]
#[must_use]
pub const fn rapidrng_single(state: &mut u64) -> u64 {
    *state = state.wrapping_add(RAPID_SECRET_ADD);
    rapid_mix(*state, *state ^ RAPID_SECRET_ADD)
}

```

--------------------------------

### Add rapidrand and rand to Dependencies

Source: https://docs.rs/rapidrand/0.1.2/index.html

Add the rapidrand and rand crates to your Cargo.toml file to use the rapidrand generator with the rand crate API.

```toml
[dependencies]
rand = "0.10"
rapidrand = "0.1"
```

--------------------------------

### Generate Pseudorandom Number with rapidrng

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/fn.rapidrng.html

Demonstrates how to generate a pseudorandom number using the rapidrng function. Requires mutable access to a u64 state variable. This PRNG is not for cryptographic use.

```rust
use rapidrand::rapidrng;

let mut state: u64 = 42;
let value: u64 = rapidrng(&mut state);
```

--------------------------------

### RapidRng Internal Mixing Algorithm

Source: https://docs.rs/rapidrand/0.1.2/index.html

Illustrates the core mixing algorithm of `RapidRng`, which involves a Weyl counter and a 128-bit multiplication followed by XOR folding. This algorithm is designed for speed and statistical quality.

```rust
// Weyl counter: odd increment → full 2^64 period
state = state.wrapping_add(RAPID_SECRET_ADD);

// 128-bit multiply, XORing a random-looking constant to the second operand
let product = (state as u128) * ((state ^ RAPID_SECRET_XOR) as u128);

// "Fold" the high and low halves of the resulting u128 together via XOR
output = (product >> 64) ^ (product as u64) as u64;
```

--------------------------------

### RapidRng::seed_from_u64

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Creates a new RapidRng instance seeded from a `u64` value. This provides a convenient way to initialize the random number generator.

```APIDOC
## RapidRng::seed_from_u64

### Description
Create a new PRNG using a `u64` seed.

### Method
`seed_from_u64`

### Signature
`fn seed_from_u64(state: u64) -> Self`
```

--------------------------------

### Use Standalone rapidrng Function

Source: https://docs.rs/rapidrand/0.1.2/index.html

Directly use the `rapidrng` function by manually managing the state. This approach is suitable when you need fine-grained control over the RNG state.

```rust
use rapidrand::rapidrng;

let mut state: u64 = 42;
let x = rapidrng(&mut state);
```

--------------------------------

### Seed RapidRng from a Fixed Value

Source: https://docs.rs/rapidrand/0.1.2/index.html

For reproducible random number streams, seed `RapidRng` from a fixed `u64` value using `seed_from_u64`. This ensures the same sequence of random numbers is generated each time.

```rust
use rand::{RngExt, SeedableRng};
use rapidrand::RapidRng;

let mut rng = RapidRng::seed_from_u64(42);
let x: u32 = rng.random();
```

--------------------------------

### RapidRng::try_next_u64

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Returns the next random `u64` value from the generator. This method is part of the `TryRng` trait and returns a `Result` to handle potential errors.

```APIDOC
## RapidRng::try_next_u64

### Description
Return the next random `u64`.

### Method
`try_next_u64`

### Signature
`fn try_next_u64(&mut self) -> Result<u64, Self::Error>`
```

--------------------------------

### RapidRng::clone_from

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Performs copy-assignment from a source RapidRng value into the current one. This is useful for efficiently updating the state of an existing generator.

```APIDOC
## RapidRng::clone_from

### Description
Performs copy-assignment from `source`.

### Method
`clone_from`

### Signature
`fn clone_from(&mut self, source: &Self)`
```

--------------------------------

### RapidRng::try_fill_bytes

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Fills a mutable byte slice with random data from the generator. This method is part of the `TryRng` trait and returns a `Result` to handle potential errors.

```APIDOC
## RapidRng::try_fill_bytes

### Description
Fill `dst` entirely with random data.

### Method
`try_fill_bytes`

### Signature
`fn try_fill_bytes(&mut self, dst: &mut [u8]) -> Result<(), Self::Error>`
```

--------------------------------

### RapidRng::partial_cmp

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Compares two RapidRng instances and returns an Option<Ordering> if a comparison is possible. This method is part of the PartialOrd trait implementation.

```APIDOC
## RapidRng::partial_cmp

### Description
This method returns an ordering between `self` and `other` values if one exists.

### Method
`partial_cmp`

### Signature
`fn partial_cmp(&self, other: &RapidRng) -> Option<Ordering>`
```

--------------------------------

### Seed RapidRng from Thread-Local RNG

Source: https://docs.rs/rapidrand/0.1.2/index.html

Use `rand::make_rng()` to seed a `RapidRng` instance from the thread-local RNG, which is itself seeded from the OS. This is useful for general-purpose random number generation.

```rust
use rand::{RngExt};
use rapidrand::RapidRng;

let mut rng: RapidRng = rand::make_rng();

let coin: bool = rng.random();
let roll = rng.random_range(1..=6);
let x: u32 = rng.random();
```

--------------------------------

### rapidrng_single Function Signature

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/fn.rapidrng_single.html

This is the function signature for rapidrng_single. It takes a mutable reference to a u64 state and returns a u64 pseudorandom number.

```rust
pub const fn rapidrng_single(state: &mut u64) -> u64
```

--------------------------------

### rapidrng_single

Source: https://docs.rs/rapidrand/0.1.2/src/rapidrand/lib.rs.html

Generates a pseudorandom number using rapidhash mixing with a single constant. This function is faster in certain scenarios but has a statistical weakness of potential consecutive repeats. It is not cryptographically secure.

```APIDOC
## rapidrng_single(state: &mut u64) -> u64

### Description
Generates a pseudorandom number using rapidhash mixing with a single constant. This PRNG is not a cryptographic random number generator. It is equivalent in logic and performance to wyhash::w1rand. Prefer `rapidrng` for better statistical properties.

### Method
`const fn` (public function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let mut state: u64 = 42;
let value: u64 = rapidrand::rapidrng_single(&mut state);
```

### Response
#### Success Response
- **u64**: The generated pseudorandom 64-bit unsigned integer.

#### Response Example
```rust
// Example output (will vary based on initial state)
let value: u64 = 9876543210987654321;
```

### Statistical Weakness
This generator has a statistical weakness where consecutive outputs can be identical under certain conditions, occurring approximately once every 2^32 draws on average. This is due to reusing the increment constant as the XOR constant.
```

--------------------------------

### RapidRng::try_next_u32

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Returns the next random `u32` value from the generator. This method is part of the `TryRng` trait and returns a `Result` to handle potential errors.

```APIDOC
## RapidRng::try_next_u32

### Description
Return the next random `u32`.

### Method
`try_next_u32`

### Signature
`fn try_next_u32(&mut self) -> Result<u32, Self::Error>`
```

--------------------------------

### RapidRng::from_rng

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Creates a new RapidRng instance seeded from an infallible `Rng`. This method is useful for seeding with a source of randomness that is guaranteed to succeed.

```APIDOC
## RapidRng::from_rng

### Description
Create a new PRNG seeded from an infallible `Rng`.

### Method
`from_rng`

### Signature
`fn from_rng<R>(rng: &mut R) -> Self where R: Rng + ?Sized`
```

--------------------------------

### RapidRng::try_from_rng

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Creates a new RapidRng instance seeded from a potentially fallible `Rng`. This method returns a Result, allowing for error handling if the seeding process fails.

```APIDOC
## RapidRng::try_from_rng

### Description
Create a new PRNG seeded from a potentially fallible `Rng`.

### Method
`try_from_rng`

### Signature
`fn try_from_rng<R>(rng: &mut R) -> Result<Self, <R as TryRng>::Error> where R: TryRng + ?Sized`
```

--------------------------------

### RapidRng::try_fork

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Attempts to fork the current RapidRng instance, returning a Result. This method is used when the `TryRng` trait is implemented and forking might fail.

```APIDOC
## RapidRng::try_fork

### Description
Fork this PRNG.

### Method
`try_fork`

### Signature
`fn try_fork(&mut self) -> Result<Self, Self::Error> where Self: TryRng`
```

--------------------------------

### RapidRng::fmt

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Formats the RapidRng value using the given formatter. This is primarily used for debugging and display purposes.

```APIDOC
## RapidRng::fmt

### Description
Formats the value using the given formatter.

### Method
`fmt`

### Signature
`fn fmt(&self, f: &mut Formatter<'_>) -> Result`
```

--------------------------------

### RapidRng::from_seed

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Creates a new RapidRng instance using a seed value. The seed type is restricted to types that can be mutably dereferenced as `u8` arrays.

```APIDOC
## RapidRng::from_seed

### Description
Create a new PRNG using the given seed.

### Method
`from_seed`

### Signature
`fn from_seed(seed: Self::Seed) -> Self`

### Type Alias
`Seed = [u8; 8]`
```

--------------------------------

### RapidRng::hash_slice

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Feeds a slice of RapidRng values into a given Hasher. This is an efficient way to hash multiple random number generator states.

```APIDOC
## RapidRng::hash_slice

### Description
Feeds a slice of this type into the given `Hasher`.

### Method
`hash_slice`

### Signature
`fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher, Self: Sized`
```

--------------------------------

### RapidRng::cmp

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Compares two RapidRng instances and returns an Ordering. This method is part of the Ord trait implementation.

```APIDOC
## RapidRng::cmp

### Description
This method returns an `Ordering` between `self` and `other`.

### Method
`cmp`

### Signature
`fn cmp(&self, other: &RapidRng) -> Ordering`
```

--------------------------------

### rapidrng Function

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/fn.rapidrng.html

Generates a pseudorandom number using rapidhash mixing. This is not a cryptographic random number generator and is equivalent in logic and performance to wyhash::wyrand and fastrand.

```APIDOC
## rapidrng

### Description
Generates a pseudorandom number using rapidhash mixing. This PRNG is not a cryptographic random number generator. This implementation is equivalent in logic and performance to wyhash::wyrand and fastrand, but uses rapidhash constants/secrets.

### Function Signature
```rust
pub const fn rapidrng(state: &mut u64) -> u64
```

### Parameters
#### Path Parameters
- **state** (*&mut u64*) - Description: A mutable reference to a u64 used as the state for the pseudorandom number generator.

### Return Value
- **u64**: A pseudorandom u64 number.

### Example
```rust
use rapidrand::rapidrng;

let mut state: u64 = 42;
let value: u64 = rapidrng(&mut state);
```
```

--------------------------------

### RapidRng::min

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Compares two RapidRng instances and returns the minimum of the two. This method is part of the Ord trait implementation.

```APIDOC
## RapidRng::min

### Description
Compares and returns the minimum of two values.

### Method
`min`

### Signature
`fn min(self, other: Self) -> Self where Self: Sized`
```

--------------------------------

### RapidRng::fork

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Forks the current RapidRng instance, creating a new independent generator with a potentially different state. This is useful for parallel computations or scenarios where independent random sequences are needed.

```APIDOC
## RapidRng::fork

### Description
Fork this PRNG.

### Method
`fork`

### Signature
`fn fork(&mut self) -> Self where Self: Rng`
```

--------------------------------

### RapidRng::le

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Tests if the first RapidRng is less than or equal to the second. This method is used by the `<=` operator and is part of the PartialOrd trait implementation.

```APIDOC
## RapidRng::le

### Description
Tests less than or equal to (for `self` and `other`) and is used by the `<=` operator.

### Method
`le`

### Signature
`fn le(&self, other: &Rhs) -> bool`
```

--------------------------------

### RapidRng::eq

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Tests if two RapidRng instances are equal. This method is used by the `==` operator and is part of the PartialEq trait implementation.

```APIDOC
## RapidRng::eq

### Description
Tests for `self` and `other` values to be equal, and is used by `==`.

### Method
`eq`

### Signature
`fn eq(&self, other: &RapidRng) -> bool`
```

--------------------------------

### RapidRng::ge

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Tests if the first RapidRng is greater than or equal to the second. This method is used by the `>=` operator and is part of the PartialOrd trait implementation.

```APIDOC
## RapidRng::ge

### Description
Tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator.

### Method
`ge`

### Signature
`fn ge(&self, other: &Rhs) -> bool`
```

--------------------------------

### RapidRng::hash

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Feeds the RapidRng value into a given Hasher. This method is part of the Hash trait implementation, used for calculating hash values.

```APIDOC
## RapidRng::hash

### Description
Feeds this value into the given `Hasher`.

### Method
`hash`

### Signature
`fn hash<__H: Hasher>(&self, state: &mut __H)`
```

--------------------------------

### RapidRng::ne

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Tests if two RapidRng instances are not equal. This method is used by the `!=` operator and is part of the PartialEq trait implementation.

```APIDOC
## RapidRng::ne

### Description
Tests for `!=`.

### Method
`ne`

### Signature
`fn ne(&self, other: &Rhs) -> bool`
```

--------------------------------

### RapidRng::clone

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Returns a duplicate of the RapidRng value. This method allows for creating an independent copy of the random number generator state.

```APIDOC
## RapidRng::clone

### Description
Returns a duplicate of the value.

### Method
`clone`

### Signature
`fn clone(&self) -> RapidRng`
```

--------------------------------

### RapidRng::lt

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Tests if the first RapidRng is less than the second. This method is used by the `<` operator and is part of the PartialOrd trait implementation.

```APIDOC
## RapidRng::lt

### Description
Tests less than (for `self` and `other`) and is used by the `<` operator.

### Method
`lt`

### Signature
`fn lt(&self, other: &Rhs) -> bool`
```

--------------------------------

### RapidRng::clamp

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Restricts a RapidRng value to a certain interval defined by minimum and maximum bounds. This method is part of the Ord trait implementation.

```APIDOC
## RapidRng::clamp

### Description
Restrict a value to a certain interval.

### Method
`clamp`

### Signature
`fn clamp(self, min: Self, max: Self) -> Self where Self: Sized`
```

--------------------------------

### RapidRng::gt

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Tests if the first RapidRng is greater than the second. This method is used by the `>` operator and is part of the PartialOrd trait implementation.

```APIDOC
## RapidRng::gt

### Description
Tests greater than (for `self` and `other`) and is used by the `>` operator.

### Method
`gt`

### Signature
`fn gt(&self, other: &Rhs) -> bool`
```

--------------------------------

### RapidRng::max

Source: https://docs.rs/rapidrand/0.1.2/rapidrand/struct.RapidRng.html

Compares two RapidRng instances and returns the maximum of the two. This method is part of the Ord trait implementation.

```APIDOC
## RapidRng::max

### Description
Compares and returns the maximum of two values.

### Method
`max`

### Signature
`fn max(self, other: Self) -> Self where Self: Sized`
```
Tokens:
Raw