stdrandom 0.3.0-alpha.5

//! # stdrandom
//!
//! Random numbers generator using only Rust standard library.
//!

/*
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 slice with random bytes using the provided generator 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 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   */

/// Fast but lower-entropy `f32` in `[0, 1)`
pub fn fast_f32() -> f32 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() as f32) / (u64::MAX as f32)
}

/// Fast but lower-entropy `f64` in `[0, 1)`
pub fn fast_f64() -> f64 {
    let s = RandomState::new();
    let hasher = s.build_hasher();
    (hasher.finish() as f64) / (u64::MAX as f64)
}

/// Higher entropy `f64` in `[0, 1)`
pub fn random_f64() -> f64 {
    (random_u64() as f64) / (u64::MAX as f64)
}

/// Higher entropy `f32` in `[0, 1)`
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 *higher entropy* random u64 number in separate thread.

  Generated numbers will always have higher randomness than
  subsequent calls to fast_u64().

  Function returns same randomness for lower or upper 32-bits.
*/
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 **random `usize` number** in a separate thread.
pub fn random_usize() -> usize {
    let handle = std::thread::spawn(|| fast_usize());

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

/// Generates a higher entropy **random `i128` number** using two separate threads.
///
/// Each thread independently generates a **random `i64`** using `fast_i64()`, ensuring that
/// both the upper and lower halves of the `i128` number are truly randomized.
///
/// # Returns
/// - A **non-negative pseudo-random `i128`** number.
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 **random `i64` number** in a separate thread.
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 **random `i32` number** in a separate thread.
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 **random `i16` number** in a separate thread.
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 **random `i8` number** in a separate thread.
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 **random `isize` number** in a separate thread.
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 fill_tests;

#[cfg(test)]
mod overflow_tests;

#[cfg(test)]
mod closure_tests;