stdrandom 0.3.0-alpha.6

//! # stdrandom
//!
//! Random numbers generator using only Rust standard library.
//!
//! This library have two types of generators:
//!
//! 1. *fast_* - these generators are fast but less random. They have
//!    progressively lowering entropy because they are based on incrementing
//!    seed. This is weakness of standard Rust library. Better is use one of
//!    these random numbers as seed for more reliable random number generator,
//!    even MCG will do better job.
//! 2. *random_* - these generators needs to spawn a new thread to obtain high
//!    quality randomness. This randomness is pretty good and passes benchmarks
//!    for random number generators with a good score. While it is still not
//!    crypto secure random for using in things like generating key material
//!    it will resist common attacks well.

/*
SPDX-License-Identifier: CC0-1.0 OR Unlicense

This code is released under a "No Copyright" license.

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.

See:
- https://creativecommons.org/publicdomain/zero/1.0/
- https://unlicense.org/
*/

use std::collections::hash_map::RandomState;
use std::hash::BuildHasher;
use std::hash::Hasher;

/// Fills buffer with random bytes generated by the provided function.
///
/// This function splits the buffer into chunks of up to 8 bytes and fills each chunk
/// with bytes derived from a `u64` value generated by `rng()`.
///
/// # Parameters
///
/// - `buffer`: A mutable reference to a slice of bytes (`&mut [u8]`) that will be filled with random data.
/// - `rng`: A mutable function (`FnMut() -> u64`) that generates random `u64` values.
///
/// # Examples
///
/// ```
/// let mut data = [0u8; 16];
/// stdrandom::fill_bytes(&mut data, stdrandom::fast_u64);
///
/// println!("{:?}", data); // Randomized output
/// ```
///
/// ## Safety Notes
///
/// - The randomness depends on the quality of the provided `rng()` function.
pub fn fill_bytes<F>(buffer: &mut [u8], mut rng: F)
where
    F: FnMut() -> u64,
{
    if buffer.is_empty() {
        return; // No need to process an empty slice
    }

    for chunk in buffer.chunks_mut(8) {
        let random_bytes = rng().to_le_bytes();
        chunk.copy_from_slice(&random_bytes[..chunk.len()]);
    }
}

/// Converts a value of type `S` into type `T`.
///
/// Safe conversion is ensured using `TryFrom` trait.
///
/// # Parameters
/// - `input`: The value to be converted.
///
/// # Returns
/// - The successfully converted value of type `T`.
///
/// # Panics
/// - If TryFrom conversion fails, a panic occurs with a detailed error message.
///
#[track_caller]
fn convert_to_t<S, T>(input: S) -> T
where
    T: TryFrom<S>,
    S: std::fmt::Debug + Copy,
{
    match T::try_from(input) {
        Ok(value) => value,
        Err(_) => panic!(
            "Conversion failed: Cannot convert value {:?} of {} type into target type {}",
            input,
            std::any::type_name::<S>(),
            std::any::type_name::<T>()
        ),
    }
}

use std::convert::TryFrom;

/// Fills a slice with generated numbers using the provided generator function.
///
/// This function is **generic** and supports **safe type conversion** via `TryFrom`.
///
/// # Parameters
/// - `buffer`: A mutable slice of type `T` (target type) that will be filled.
/// - `rng`: A function that generates values of type `S` (source type).
///
/// # Example
/// ```
/// fn generate_random() -> u64 { stdrandom::fast_u64() & u32::MAX as u64}
///
/// let mut data = [0u32; 5];
/// stdrandom::fill_numbers(&mut data, generate_random);
/// println!("{:?}", data);
/// ```
#[track_caller]
pub fn fill_numbers<S, T, F>(buffer: &mut [T], mut rng: F)
where
    F: FnMut() -> S,
    T: Copy + TryFrom<S>,
    S: std::fmt::Debug + Copy,
{
    if buffer.is_empty() {
        return; // No need to process an empty slice
    }

    for item in buffer.iter_mut() {
        *item = convert_to_t(rng()); // Ensures safe conversion
    }
}

use std::ops::{Bound, RangeBounds};

/**
  Generates random number in specified range using supplied generator.

  Requested range must fit into target type.
*/
#[track_caller]
pub fn gen_range<R, F, T>(range: R, mut rng: F) -> T
where
    R: RangeBounds<u64>,
    F: FnMut() -> u64,
    T: TryFrom<u64> + 'static, // Enables conversion from `u64` to any smaller integer type (`u32`, `u16`, etc.)
{
    let start = match range.start_bound() {
        Bound::Included(s) => *s,
        _ => panic!("Invalid range: Start must be included."),
    };

    let (end, is_inclusive) = match range.end_bound() {
        Bound::Included(e) => (*e, true),
        Bound::Excluded(e) => (*e, false),
        _ => panic!("Invalid range: End must be bounded."),
    };

    if end < start {
        panic!("Invalid range: End must be greater than or equal to start.");
    }

    let range_size = if is_inclusive {
        if end == u64::MAX {
            if start == 0 {
                u64::MAX
            } else {
                u64::MAX - start + 1
            }
        } else {
            end - start + 1
        }
    } else {
        end - start
    };

    if range_size == 0 {
        panic!("Invalid range: Cannot generate a number from an empty range.");
    }

    let raw_random = rng();
    let mapped_to_zero_based_range = raw_random % range_size;
    let final_result = start + mapped_to_zero_based_range;

    convert_to_t(final_result)
}

/// Fills a mutable slice with random numbers in the specified range using the supplied generator.
///
/// The requested range must fit into the target type of the slice elements.
///
/// # Arguments
///
/// * `slice`: A mutable slice (`&mut [T]`) to be filled with random numbers.
/// * `range`: A range (`R`) specifying the inclusive start and exclusive end for the random numbers.
/// * `rng`: A mutable closure or function (`F`) that generates a `u64` random number.
///
/// # Panics
///
/// This function will panic if:
///
/// * The start of the range is not inclusive.
/// * The end of the range is not bounded (inclusive or exclusive).
/// * The end of the range is less than the start.
/// * The range is empty (start >= end).
/// * A generated `u64` cannot be converted to the target type `T`.
///
/// # Example
///
/// ```
/// use std::collections::hash_map::RandomState;
/// use std::hash::{BuildHasher, Hasher};
/// use std::ops::Range;
///
/// fn fast_u64() -> u64 {
///     let s = RandomState::new();
///     let hasher = s.build_hasher();
///     hasher.finish()
/// }
///
/// fn main() {
///     let mut data = [0u32; 10];
///     let range = 10..20; // Generates numbers from 10 (inclusive) to 20 (exclusive)
///     stdrandom::fill_range(&mut data, range, || fast_u64());
///     println!("Filled data: {:?}", data);
/// }
/// ```
#[track_caller]
pub fn fill_range<R, F, T>(slice: &mut [T], range: R, mut rng: F)
where
    R: RangeBounds<u64>,
    F: FnMut() -> u64,
    T: TryFrom<u64> + Copy,
{
    let start = match range.start_bound() {
        Bound::Included(s) => *s,
        _ => panic!("Invalid range: Start must be included."),
    };

    let (end, is_inclusive) = match range.end_bound() {
        Bound::Included(e) => (*e, true),
        Bound::Excluded(e) => (*e, false),
        _ => panic!("Invalid range: End must be bounded."),
    };

    if end < start {
        panic!("Invalid range: End must be greater than or equal to start.");
    }

    let range_size = if is_inclusive {
        if end == u64::MAX {
            if start == 0 {
                u64::MAX
            } else {
                u64::MAX - start + 1
            }
        } else {
            end - start + 1
        }
    } else {
        end - start
    };

    if range_size == 0 {
        panic!("Invalid range: Cannot generate a number from an empty range.");
    }

    for i in 0..slice.len() {
        let raw_random = rng();
        let mapped_to_zero_based_range = raw_random % range_size;
        let final_result = start + mapped_to_zero_based_range;

        slice[i] = convert_to_t(final_result);
    }
}

/*   fast random numbers   */

/// Generates a `u128` random number using the current thread's `RandomState`s.
///
/// The first number generated in the current thread is more **random**.
/// Subsequent numbers are derived from an **incremented seed**, leading to progressively
/// lower randomness.
///
/// # Returns
/// - A pseudo-random `u128` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_u128();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_u128() -> u128 {
    let low = RandomState::new().build_hasher().finish(); // First random `u64`
    let high = RandomState::new().build_hasher().finish(); // Second random `u64`

    ((high as u128) << 64) | (low as u128) // Combine two `u64` values into a full `u128`
}

/// Generates a `u64` random number using the current thread's `RandomState`.
///
/// The first number generated in the thread is **random**. Subsequent numbers
/// are derived from an **incremented seed**, leading to progressively
/// lower randomness.
///
/// # Returns
/// - A pseudo-random `u64` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_u64();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_u64() -> u64 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    hasher.finish()
}

/// Generates a `u32` random number using the current thread's `RandomState`.
///
/// The first number generated in the thread is **random**. Subsequent numbers
/// are derived from an **incremented seed**, leading to progressively
/// lower randomness.
///
/// # Returns
/// - A pseudo-random `u32` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_u32();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_u32() -> u32 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() & 0xFFFFFFFF) as u32
}

/// Generates a `u16` random number using the current thread's `RandomState`.
///
/// The first number generated in the thread is **random**. Subsequent numbers
/// are derived from an **incremented seed**, leading to progressively
/// lower randomness.
///
/// # Returns
/// - A pseudo-random `u16` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_u16();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_u16() -> u16 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() & 0xFFFF) as u16
}

/// Generates a `u8` random number using the current thread's `RandomState`.
///
/// The first number generated in the thread is **random**. Subsequent numbers
/// are derived from an **incremented seed**, leading to progressively
/// lower randomness.
///
/// # Returns
/// - A pseudo-random `u8` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_u8();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_u8() -> u8 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() & 0xFF) as u8
}

/// Generates a `usize` random number using the current thread's `RandomState`.
///
/// The first number generated in the thread is **random**. Subsequent numbers
/// are derived from an **incremented seed**, leading to progressively
/// lower randomness.
///
/// # Returns
/// - A pseudo-random `usize` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_usize();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_usize() -> usize {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    hasher.finish() as usize
}

/// Generates a **non-negative** `i128` random number using two separate instances of `RandomState`.
///
/// The first number generated in the thread is more **random**.
/// Subsequent numbers are derived from an **incremented seed**, leading to progressively
/// lower randomness.
///
/// # Returns
/// - A **non-negative** pseudo-random `i128` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_i128();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_i128() -> i128 {
    let low = RandomState::new().build_hasher().finish() as i128; // First random `i64`
    let high = RandomState::new().build_hasher().finish() as i128; // Second random `i64`

    let full_value = (high << 64) | low; // Combine two `i64` values into a full `i128`

    full_value.abs() // Ensure non-negative result
}

/// Generates a **non-negative** `i64` random number using the current thread's `RandomState`.
///
/// The first number generated in the thread is **random**, while subsequent numbers
/// are derived from an **incremented seed**, leading to progressively lower randomness.
///
/// # Returns
/// - A **non-negative** pseudo-random `i64` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_i64();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_i64() -> i64 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() & 0x7FFFFFFFFFFFFFFF) as i64 // Mask to ensure non-negative `i64`
}

/// Generates a **non-negative** `i32` random number using the current thread's `RandomState`.
///
/// The first number generated in the thread is **random**, while subsequent numbers
/// are derived from an **incremented seed**, leading to progressively lower randomness.
///
/// # Returns
/// - A **non-negative** pseudo-random `i32` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_i32();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_i32() -> i32 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() & 0x7FFFFFFF) as i32 // Mask to ensure non-negative `i32`
}

/// Generates a **non-negative** `i16` random number using the current thread's `RandomState`.
///
/// The first number generated in the thread is **random**, while subsequent numbers
/// are derived from an **incremented seed**, leading to progressively lower randomness.
///
/// # Returns
/// - A **non-negative** pseudo-random `i16` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_i16();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_i16() -> i16 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() & 0x7FFF) as i16 // Mask to ensure non-negative `i16`
}

/// Generates a **non-negative** `i8` random number using the current thread's `RandomState`.
///
/// The first number generated in the thread is **random**, while subsequent numbers
/// are derived from an **incremented seed**, leading to progressively lower randomness.
///
/// # Returns
/// - A **non-negative** pseudo-random `i8` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_i8();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_i8() -> i8 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() & 0x7F) as i8 // Mask to ensure non-negative `i8`
}

/// Generates a **non-negative** `isize` random number using the current thread's `RandomState`.
///
/// The first number generated in the thread is **random**, while subsequent numbers
/// are derived from an **incremented seed**, leading to progressively lower randomness.
///
/// # Returns
/// - A **non-negative** pseudo-random `isize` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_isize();
/// println!("Generated: {}", random_value);
/// ```
pub fn fast_isize() -> isize {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() & (isize::MAX as u64)) as isize // Mask ensures non-negative `isize`
}

/*   floating point randoms   */

/// Generates a **fast** but lower-entropy `f64` pseudo-random number in the range `[0.0, 1.0)`.
///
/// This function leverages the current thread's `RandomState` to create a hasher.
/// The first number generated in the thread is typically **random**, while subsequent numbers
/// are derived from an **incremented internal seed** within `RandomState`, potentially
/// leading to progressively lower statistical randomness or predictability.
///
/// # Returns
/// - A **non-negative** pseudo-random `f64` number within the half-open interval `[0.0, 1.0)`.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_f64();
/// println!("Generated f64: {}", random_value);
/// ```
pub fn fast_f64() -> f64 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() as f64) / (u64::MAX as f64)
}

/// Generates a **fast** but lower-entropy `f32` pseudo-random number in the range `[0.0, 1.0)`.
///
/// This function leverages the current thread's `RandomState` to create a hasher.
/// The first number generated in the thread is typically **random**, while subsequent numbers
/// are derived from an **incremented internal seed** within `RandomState`, potentially
/// leading to progressively lower statistical randomness or predictability.
///
/// # Returns
/// - A **non-negative** pseudo-random `f32` number within the half-open interval `[0.0, 1.0)`.
///
/// # Example
/// ```
/// let random_value = stdrandom::fast_f32();
/// println!("Generated f32: {}", random_value);
/// ```
pub fn fast_f32() -> f32 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() as f32) / (u64::MAX as f32)
}

/// Generates a **higher entropy** `f64` pseudo-random number in the range `[0.0, 1.0)`.
///
/// This function achieves higher randomness by leveraging a source like `random_u64()`,
/// which is designed to provide better statistical properties and less predictability
/// by generating values in a separate thread.
/// It results in numbers with **significantly higher entropy** compared to `fast_f64()`.
///
/// # Returns
/// - A **non-negative** pseudo-random `f64` number within the half-open interval `[0.0, 1.0)`.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_f64();
/// println!("Generated higher entropy f64: {}", random_value);
/// ```
pub fn random_f64() -> f64 {
    (random_u64() as f64) / (u64::MAX as f64)
}

/// Generates a **higher entropy** `f32` pseudo-random number in the range `[0.0, 1.0)`.
///
/// This function achieves higher randomness by leveraging a source like `random_u64()`,
/// which is designed to provide better statistical properties and less predictability
/// by generating values in a separate thread.
/// It results in numbers with **significantly higher entropy** compared to `fast_f32()`.
///
/// # Returns
/// - A **non-negative** pseudo-random `f32` number within the half-open interval `[0.0, 1.0)`.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_f32();
/// println!("Generated higher entropy f32: {}", random_value);
/// ```
pub fn random_f32() -> f32 {
    (random_u64() as f32) / (u64::MAX as f32)
}

/*   High entropy random numbers   */

/// Generates a higher entropy **random `u128`** number using two separate threads.
///
/// Each thread independently generates a **random `u64`** using `fast_u64()`, ensuring that
/// both the upper and lower halves of the `u128` number are truly randomized.
///
/// # Returns
/// - A high entropy **pseudo-random `u128`** number.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_u128();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_u128() -> u128 {
    // Spawn two independent threads to generate `u64` values separately
    let lower_thread = std::thread::spawn(|| fast_u64());
    let upper_thread = std::thread::spawn(|| fast_u64());

    // Handle potential thread failures
    let low = match lower_thread.join() {
        Ok(value) => value,
        Err(_) => fast_u64(), // Fallback: Generate in the main thread
    };

    let high = match upper_thread.join() {
        Ok(value) => value,
        Err(_) => fast_u64(), // Fallback: Generate in the main thread
    };

    // Combine the two `u64` values into a full `u128`
    ((high as u128) << 64) | (low as u128)
}

/// Generates a **higher entropy** pseudo-random `u64` number.
///
/// This function generates a `u64` pseudo-random number with **higher entropy**
/// compared to `fast_u64()`. It typically achieves this by performing the
/// generation in a separate thread, similar to `random_u32()`.
///
/// The randomness is distributed uniformly across all 64 bits of the generated
/// number, meaning both the lower and upper 32-bit halves of the `u64` are
/// considered equally random.
///
/// # Returns
/// - A pseudo-random `u64` number with higher entropy.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_u64();
/// println!("Generated higher entropy u64: {}", random_value);
/// ```
pub fn random_u64() -> u64 {
    // Generate random number inside the new thread to get unique RandomState
    let handle = std::thread::spawn(|| fast_u64());

    // Handle potential thread failure
    match handle.join() {
        Ok(randomness) => randomness, // Successfully got randomness from the spawned thread
        Err(_) => {
            // eprintln!("Error joining thread, using less random number from current thread.");
            // Fallback: Generate randomness in the main thread
            fast_u64()
        }
    }
}

/// Generates a higher entropy **random `u32` number** in a separate thread.
///
/// The generated number will have **higher randomness** compared to subsequent
/// calls to `fast_u32()` in the same thread.
///
/// # Returns
/// - A **pseudo-random `u32`** number.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_u32();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_u32() -> u32 {
    // Spawn a thread to generate a random `u32`
    let handle = std::thread::spawn(|| fast_u32());

    // Handle potential thread failure
    match handle.join() {
        Ok(randomness) => randomness, // Successfully retrieved randomness
        Err(_) => {
            // eprintln!("Error joining thread, using less random number from current thread.");
            fast_u32() // Fallback: Generate in the main thread
        }
    }
}

/// Generates a higher entropy **random `u16` number** in a separate thread.
///
/// The generated number will have **higher randomness** compared to subsequent
/// calls to `fast_u16()` in the same thread.
///
/// # Returns
/// - A **pseudo-random `u16`** number.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_u16();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_u16() -> u16 {
    let handle = std::thread::spawn(|| fast_u16());

    match handle.join() {
        Ok(randomness) => randomness,
        Err(_) => fast_u16(), // Fallback in case the thread fails
    }
}

/// Generates a higher entropy **random `u8` number** in a separate thread.
///
/// The generated number will have **higher randomness** compared to subsequent
/// calls to `fast_u8()` in the same thread.
///
/// # Returns
/// - A **pseudo-random `u8`** number.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_u8();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_u8() -> u8 {
    let handle = std::thread::spawn(|| fast_u8());

    match handle.join() {
        Ok(randomness) => randomness,
        Err(_) => fast_u8(), // Fallback in case the thread fails
    }
}

/// Generates a **higher entropy** pseudo-random `usize` number.
///
/// This function generates a `usize` pseudo-random number with **higher entropy**
/// compared to `fast_usize()`. It achieves this by performing the generation
/// in a separate thread, which can help mitigate the issues of predictable
/// or lower randomness often associated with sequential calls within the same thread
/// (as seen with `fast_usize()` using `RandomState`).
///
/// In case the thread fails to spawn or join, it gracefully falls back to
/// generating a `usize` number in the current thread using `fast_usize()`,
/// which will have lower entropy.
///
/// # Returns
/// - A pseudo-random `usize` number with higher entropy, or a lower-entropy fallback.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_usize();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_usize() -> usize {
    let handle = std::thread::spawn(|| fast_usize());

    match handle.join() {
        Ok(randomness) => randomness,
        Err(_) => {
            // eprintln!("Error joining thread, using less random number from current thread.");
            fast_usize() // Fallback: Generate in the main thread
        }
    }
}

/// Generates a **higher entropy** pseudo-random `i128` number using two separate threads.
///
/// This function creates a `i128` pseudo-random number with **significantly higher entropy**
/// compared to single-threaded generation methods. It achieves this by concurrently
/// generating the upper 64 bits and lower 64 bits of the `i128` in two distinct threads.
///
/// Each thread independently utilizes a `RandomState` based generator,
/// reducing the predictability and potential for patterns that might emerge from repeated calls
/// to a single-threaded generator within the same thread.
///
/// In case either thread fails to spawn or join, the respective value
/// is generated as a fallback directly in the current thread, which would result in lower entropy.
///
/// # Returns
/// - A **non-negative** pseudo-random `i128` number.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_i128();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_i128() -> i128 {
    // lower thread is using u64 to get full range of values
    let lower_thread = std::thread::spawn(|| fast_u64());
    let upper_thread = std::thread::spawn(|| fast_i64());

    let low = match lower_thread.join() {
        Ok(value) => value as i128,
        Err(_) => fast_u64() as i128,
    };

    let high = match upper_thread.join() {
        Ok(value) => value as i128,
        Err(_) => fast_i64() as i128,
    };

    (high << 64) | low
}

/// Generates a **higher entropy** pseudo-random `i64` number.
///
/// This function generates an `i64` pseudo-random number with **higher entropy**
/// compared to `fast_i64()`. It achieves this by performing the generation
/// in a separate thread, which can help mitigate the issues of predictable
/// or lower randomness often associated with sequential calls within the same thread
/// (as seen with `fast_i64()` using `RandomState`).
///
/// In case the thread fails to spawn or join, it gracefully falls back to
/// generating an `i64` number in the current thread using `fast_i64()`,
/// which will have lower entropy.
///
/// # Returns
/// - A **non-negative** pseudo-random `i64` number with higher entropy, or a lower-entropy fallback.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_i64();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_i64() -> i64 {
    let handle = std::thread::spawn(|| fast_i64());

    match handle.join() {
        Ok(randomness) => randomness,
        Err(_) => fast_i64(),
    }
}

/// Generates a **higher entropy** pseudo-random `i32` number.
///
/// This function generates an `i32` pseudo-random number with **higher entropy**
/// compared to `fast_i32()`. It achieves this by performing the generation
/// in a separate thread, which can help mitigate the issues of predictable
/// or lower randomness often associated with sequential calls within the same thread
/// (as seen with `fast_i32()` using `RandomState`).
///
/// In case the thread fails to spawn or join, it gracefully falls back to
/// generating an `i32` number in the current thread using `fast_i32()`,
/// which will have lower entropy.
///
/// # Returns
/// - A **non-negative** pseudo-random `i32` number with higher entropy, or a lower-entropy fallback.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_i32();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_i32() -> i32 {
    let handle = std::thread::spawn(|| fast_i32());

    match handle.join() {
        Ok(randomness) => randomness,
        Err(_) => fast_i32(),
    }
}

/// Generates a **higher entropy** pseudo-random `i16` number.
///
/// This function generates an `i16` pseudo-random number with **higher entropy**
/// compared to `fast_i16()`. It achieves this by performing the generation
/// in a separate thread, which can help mitigate the issues of predictable
/// or lower randomness often associated with sequential calls within the same thread
/// (as seen with `fast_i16()` using `RandomState`).
///
/// In case the thread fails to spawn or join, it gracefully falls back to
/// generating an `i16` number in the current thread using `fast_i16()`,
/// which will have lower entropy.
///
/// # Returns
/// - A **non-negative** pseudo-random `i16` number with higher entropy, or a lower-entropy fallback.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_i16();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_i16() -> i16 {
    let handle = std::thread::spawn(|| fast_i16());

    match handle.join() {
        Ok(randomness) => randomness,
        Err(_) => fast_i16(),
    }
}

/// Generates a **higher entropy** pseudo-random `i8` number.
///
/// This function generates an `i8` pseudo-random number with **higher entropy**
/// compared to `fast_i8()`. It achieves this by performing the generation
/// in a separate thread, which can help mitigate the issues of predictable
/// or lower randomness often associated with sequential calls within the same thread
/// (as seen with `fast_i8()` using `RandomState`).
///
/// In case the thread fails to spawn or join, it gracefully falls back to
/// generating an `i8` number in the current thread using `fast_i8()`,
/// which will have lower entropy.
///
/// # Returns
/// - A **non-negative** pseudo-random `i8` number with higher entropy, or a lower-entropy fallback.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_i8();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_i8() -> i8 {
    let handle = std::thread::spawn(|| fast_i8());

    match handle.join() {
        Ok(randomness) => randomness,
        Err(_) => fast_i8(),
    }
}

/// Generates a **higher entropy** pseudo-random `isize` number.
///
/// This function generates an `isize` pseudo-random number with **higher entropy**
/// compared to `fast_isize()`. It achieves this by performing the generation
/// in a separate thread, which can help mitigate the issues of predictable
/// or lower randomness often associated with sequential calls within the same thread
/// (as seen with `fast_isize()` using `RandomState`).
///
/// In case the thread fails to spawn or join, it gracefully falls back to
/// generating an `isize` number in the current thread using `fast_isize()`,
/// which will have lower entropy.
///
/// # Returns
/// - A **non-negative** pseudo-random `isize` number with higher entropy, or a lower-entropy fallback.
///
/// # Example
/// ```
/// let random_value = stdrandom::random_isize();
/// println!("Generated: {}", random_value);
/// ```
pub fn random_isize() -> isize {
    let handle = std::thread::spawn(|| fast_isize());

    match handle.join() {
        Ok(randomness) => randomness,
        Err(_) => fast_isize(),
    }
}


#[cfg(test)]
mod basic_tests;

#[cfg(test)]
mod generator_tests;

#[cfg(test)]
mod fillrange_tests;

#[cfg(test)]
mod overflow_tests;

#[cfg(test)]
mod closure_tests;