product_os_random/

lib.rs

//! # Product OS Random
//!
//! A random number generation library providing cryptographically secure RNGs,
//! random text/number generators, and word/name generators. Supports `no_std` environments.
//!
//! ## Features
//!
//! This crate provides multiple feature flags to control functionality and dependencies:
//!
//! ### Core Features
//! - `default` - Basic random generation with `StdRng` and getrandom support
//! - `core` - Full standard library support with `StdRng`, `ThreadRng`, and `OsRng`
//! - `send_only` - Send-safe RNG variants only
//! - `constrained` - Minimal allocation-only mode (no default RNG, user must provide)
//! - `custom` - Custom RNG support with spin locks for `no_std` environments
//! - `custom_send_only` - Custom Send-safe RNG support
//!
//! ### Dataset Features
//! - `words` - Enable random word generation
//! - `nouns` - Enable random noun generation
//! - `adjectives` - Enable random adjective generation
//! - `names` - Enable random full name generation
//! - `first_names` - Enable random first name generation
//! - `last_names` - Enable random last name generation
//!
//! ## Security Considerations
//!
//! ### Cryptographic vs Non-Cryptographic RNGs
//!
//! - **`CryptoRNG`**: Use for security-sensitive operations (passwords, keys, tokens).
//!   Implements `CryptoRng` marker trait indicating cryptographic security.
//! - **`RNG`**: General-purpose random generation. Some variants are cryptographically
//!   secure (like `OsRng`), others are not (like seeded `StdRng`).
//!
//! ### Thread Safety
//!
//! - `RNG::Thread` uses `ThreadRng` which is thread-local
//! - Custom RNG wrappers use `Arc<Mutex<>>` for thread-safe access
//! - All RNG variants implement `Clone` for easy distribution
//!
//! ## Usage Examples
//!
//! ### Convenience Functions (Recommended)
//!
//! The simplest way to generate random data:
//!
//! ```rust
//! # #[cfg(feature = "core")]
//! # {
//! let password = product_os_random::random_password(16);
//! let code = product_os_random::random_alphanumeric(10);
//! let port = product_os_random::random_usize(1025, 65535);
//! let bytes = product_os_random::random_bytes(32);
//! let key = product_os_random::generate_random_key(32);
//! # }
//! ```
//!
//! ### Stateful Generator with Custom RNG
//!
//! ```rust
//! # #[cfg(feature = "core")]
//! # {
//! use product_os_random::{RandomGenerator, RandomGeneratorTemplate, RNG};
//! use rand::SeedableRng;
//!
//! // Create a seeded RNG for reproducible results
//! let rng = RNG::Std(rand::rngs::StdRng::seed_from_u64(42));
//! let mut gen = RandomGenerator::new(Some(rng));
//!
//! // Generate random data
//! let bytes = gen.get_random_bytes(32);
//! let number = gen.get_random_usize(1, 100);
//! let alphanumeric = gen.get_random_alphanumeric(10);
//! # }
//! ```
//!
//! ### Cryptographic Key Generation
//!
//! ```rust
//! # #[cfg(feature = "core")]
//! # {
//! use product_os_random::RandomGenerator;
//!
//! // Generate a cryptographic key
//! let key = RandomGenerator::generate_simple_key_one_time(32);
//! assert_eq!(key.len(), 32);
//! # }
//! ```
//!
//! ### Using Feature-Gated Name Generation
//!
//! ```rust
//! # #[cfg(all(feature = "core", feature = "names"))]
//! # {
//! use product_os_random::RandomGenerator;
//!
//! let username = RandomGenerator::get_simple_random_username_one_time(
//!     Some(2),
//!     Some(4),
//!     Some("_".to_string())
//! );
//!
//! let email = RandomGenerator::get_simple_random_email_one_time(
//!     Some(2),
//!     Some(3),
//!     None,
//!     vec!["example.com".to_string()]
//! );
//! # }
//! ```
//!
//! ### Custom RNG Implementation
//!
//! ```rust
//! # #[cfg(feature = "custom")]
//! # {
//! use product_os_random::{CustomRng, RNG};
//! use rand::SeedableRng;
//!
//! let seed_rng = rand::rngs::StdRng::seed_from_u64(42);
//! let custom = CustomRng::new(seed_rng);
//! let rng = RNG::Custom(custom);
//! # }
//! ```
//!
//! ## Performance Characteristics
//!
//! - **String Generation**: Pre-allocates with `String::with_capacity` for efficiency
//! - **Large Datasets**: Names datasets are large (~400K lines total), consider binary size
//! - **Lock Contention**: Custom RNGs use mutexes, may have contention under high concurrency
//! - **`no_std` Support**: Minimal overhead when used without standard library features

#![no_std]
// Clippy configuration
#![warn(clippy::all, clippy::pedantic, clippy::cargo)]
#![warn(missing_docs)]
// Allow certain patterns that are intentional
#![allow(clippy::module_name_repetitions)] // RandomGenerator naming is intentional
#![allow(clippy::similar_names)] // rng, gen are standard in RNG code
#![allow(unreachable_patterns)] // Patterns may be unreachable with certain feature combinations
#![allow(clippy::too_many_lines)] // Large file is acceptable for now, will refactor later
#![allow(clippy::must_use_candidate)] // Many functions could use #[must_use], will add gradually
#![allow(clippy::missing_errors_doc)] // Error docs will be added with try_ variants
#![allow(clippy::missing_panics_doc)] // Panic docs exist in main documentation
#![allow(clippy::missing_docs_in_private_items)] // Private items don't need docs
#![allow(clippy::if_same_then_else)] // Feature-gated code may look identical but isn't

extern crate alloc;

use alloc::string::String;
#[cfg(any(feature = "custom", feature = "custom_send_only"))]
use alloc::sync::Arc;
#[cfg(feature = "rand")]
use alloc::vec;
use alloc::vec::Vec;

#[cfg(feature = "adjectives")]
mod adjectives;
#[cfg(feature = "first_names")]
mod first_names;
#[cfg(feature = "last_names")]
mod last_names;
#[cfg(feature = "names")]
mod names;
#[cfg(feature = "nouns")]
mod nouns;
#[cfg(feature = "words")]
mod words;

#[cfg(any(feature = "core", feature = "send_only"))]
pub use rand::rngs::StdRng;

#[cfg(all(feature = "core", not(feature = "send_only")))]
pub use rand::rngs::ThreadRng;

#[cfg(feature = "core")]
pub use rand::rngs::OsRng;

#[cfg(feature = "custom")]
pub use getrandom::register_custom_getrandom;

#[cfg(feature = "rand")]
pub use rand::{CryptoRng, Error, Rng, RngCore, SeedableRng};

// Helper functions for character filtering and range operations
// These reduce code duplication and fix clippy warnings

/// Filters a character value to exclude certain special characters.
/// Used in random string generation to ensure printable, alphanumeric-focused output.
///
/// Character ranges that get shifted:
/// - 33-37 → +20 (shifts to 53-57, which are '5' to '9')
/// - 38-47 → +10 (shifts to 48-57, which are '0' to '9')
/// - 58-64 → +10 (shifts to 68-74, which are 'D' to 'J')
/// - 91-96 → +10 (shifts to 101-106, which are 'e' to 'j')
#[cfg(feature = "rand")]
#[inline]
fn filter_printable_char(mut value: u8) -> u8 {
    if (33..=37).contains(&value) {
        value += 20;
    } else if (38..=47).contains(&value) {
        value += 10;
    } else if (58..=64).contains(&value) {
        value += 10;
    } else if (91..=96).contains(&value) {
        value += 10;
    }
    value
}

/// Filters a character value for alphanumeric output (0-9, a-z, A-Z).
///
/// Character ranges that get shifted:
/// - 58-64 → +10 (shifts to A-Z range)
/// - 91-96 → +10 (shifts to a-z range)
#[cfg(feature = "rand")]
#[inline]
fn filter_alphanumeric_char(mut value: u8) -> u8 {
    if (58..=64).contains(&value) {
        value += 10;
    } else if (91..=96).contains(&value) {
        value += 10;
    }
    value
}

/// Converts a string to title case (first letter uppercase, rest lowercase).
///
/// This is a simple implementation for single-word name data, replacing the
/// `inflections` crate dependency. Handles Unicode correctly via `char::to_uppercase`
/// and `char::to_lowercase`.
#[cfg(any(feature = "first_names", feature = "last_names"))]
#[allow(dead_code)]
fn to_title_case(s: &str) -> String {
    let mut chars = s.chars();
    match chars.next() {
        None => String::new(),
        Some(first) => {
            let mut result = String::with_capacity(s.len());
            for c in first.to_uppercase() {
                result.push(c);
            }
            for c in chars {
                for lc in c.to_lowercase() {
                    result.push(lc);
                }
            }
            result
        }
    }
}

/// A thread-safe wrapper around any `RngCore` implementation for use in `no_std` environments.
///
/// This type wraps an RNG in `Arc<Mutex<>>` using a spin lock, making it shareable across
/// threads in `no_std` contexts. The mutex ensures safe concurrent access to the underlying RNG.
///
/// # Thread Safety
///
/// Uses spin locks from the `spin` crate, which are suitable for `no_std` environments.
/// Under high contention, spin locks may consume CPU cycles waiting for the lock.
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "custom")]
/// # {
/// use product_os_random::CustomRng;
/// use rand::SeedableRng;
///
/// let seed_rng = rand::rngs::StdRng::seed_from_u64(42);
/// let custom = CustomRng::new(seed_rng);
/// # }
/// ```
#[cfg(feature = "custom")]
#[derive(Clone)]
pub struct CustomRng {
    rng: Arc<spin::mutex::Mutex<dyn RngCore>>,
}

#[cfg(feature = "custom")]
impl CustomRng {
    /// Creates a new `CustomRng` wrapping the provided RNG.
    ///
    /// The RNG is wrapped in `Arc<Mutex<>>` to enable thread-safe cloning and concurrent access.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(feature = "custom")]
    /// # {
    /// use product_os_random::CustomRng;
    /// use rand::SeedableRng;
    ///
    /// let rng = rand::rngs::StdRng::seed_from_u64(42);
    /// let custom = CustomRng::new(rng);
    /// # }
    /// ```
    pub fn new(rng: impl RngCore + 'static) -> Self {
        Self {
            rng: Arc::new(spin::mutex::Mutex::new(rng)),
        }
    }
}

#[cfg(feature = "custom")]
impl RngCore for CustomRng {
    fn next_u32(&mut self) -> u32 {
        let mut rl = self.rng.lock();
        rl.next_u32()
    }

    fn next_u64(&mut self) -> u64 {
        let mut rl = self.rng.lock();
        rl.next_u64()
    }

    fn fill_bytes(&mut self, dest: &mut [u8]) {
        let mut rl = self.rng.lock();
        rl.fill_bytes(dest);
    }

    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
        let mut rl = self.rng.lock();
        rl.try_fill_bytes(dest)
    }
}

/// Marker trait for cryptographically secure RNGs.
///
/// This trait combines `RngCore` and `CryptoRng` to indicate that an RNG is suitable
/// for security-sensitive operations like key generation, password creation, and token generation.
///
/// # Security
///
/// Implementors of this trait must provide cryptographically secure random number generation.
/// This typically means:
/// - Output is indistinguishable from true randomness
/// - Past outputs don't reveal future outputs
/// - Sufficient entropy from a secure source
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "custom")]
/// # {
/// use product_os_random::{RngCore, CryptoRng, RngCrypto, Error};
/// use rand::SeedableRng;
///
/// struct MyCryptoRng(rand::rngs::StdRng);
///
/// impl RngCore for MyCryptoRng {
///     fn next_u32(&mut self) -> u32 { self.0.next_u32() }
///     fn next_u64(&mut self) -> u64 { self.0.next_u64() }
///     fn fill_bytes(&mut self, dest: &mut [u8]) { self.0.fill_bytes(dest) }
///     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
///         self.0.try_fill_bytes(dest)
///     }
/// }
///
/// impl CryptoRng for MyCryptoRng {}
/// impl RngCrypto for MyCryptoRng {}
/// # }
/// ```
#[cfg(any(feature = "custom", feature = "custom_send_only"))]
pub trait RngCrypto: RngCore + CryptoRng {}

/// A thread-safe wrapper around cryptographically secure RNGs for use in `no_std` environments.
///
/// Similar to `CustomRng`, but specifically for RNGs that implement the `RngCrypto` trait,
/// providing additional type safety for cryptographic operations.
///
/// # Security
///
/// This type should only wrap RNGs that are cryptographically secure. The wrapper itself
/// doesn't add or remove security properties, it only provides thread-safe access.
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "custom")]
/// # {
/// use product_os_random::{CustomCryptoRng, RngCore, CryptoRng, RngCrypto, Error};
/// use rand::SeedableRng;
///
/// #[derive(Clone)]
/// struct MyCryptoRng(rand::rngs::StdRng);
///
/// impl RngCore for MyCryptoRng {
///     fn next_u32(&mut self) -> u32 { self.0.next_u32() }
///     fn next_u64(&mut self) -> u64 { self.0.next_u64() }
///     fn fill_bytes(&mut self, dest: &mut [u8]) { self.0.fill_bytes(dest) }
///     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
///         self.0.try_fill_bytes(dest)
///     }
/// }
///
/// impl CryptoRng for MyCryptoRng {}
/// impl RngCrypto for MyCryptoRng {}
///
/// let rng = MyCryptoRng(rand::rngs::StdRng::seed_from_u64(42));
/// let custom = CustomCryptoRng::new(rng);
/// # }
/// ```
#[derive(Clone)]
#[cfg(feature = "custom")]
pub struct CustomCryptoRng {
    rng: Arc<spin::mutex::Mutex<dyn RngCrypto>>,
}

#[cfg(feature = "custom")]
impl CustomCryptoRng {
    /// Creates a new `CustomCryptoRng` wrapping the provided cryptographic RNG.
    ///
    /// # Security
    ///
    /// The provided RNG must implement `RngCrypto`, ensuring it's suitable for
    /// cryptographic operations.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(feature = "custom")]
    /// # {
    /// use product_os_random::{CustomCryptoRng, RngCore, CryptoRng, RngCrypto, Error};
    /// use rand::SeedableRng;
    ///
    /// #[derive(Clone)]
    /// struct MyCryptoRng(rand::rngs::StdRng);
    ///
    /// impl RngCore for MyCryptoRng {
    ///     fn next_u32(&mut self) -> u32 { self.0.next_u32() }
    ///     fn next_u64(&mut self) -> u64 { self.0.next_u64() }
    ///     fn fill_bytes(&mut self, dest: &mut [u8]) { self.0.fill_bytes(dest) }
    ///     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
    ///         self.0.try_fill_bytes(dest)
    ///     }
    /// }
    ///
    /// impl CryptoRng for MyCryptoRng {}
    /// impl RngCrypto for MyCryptoRng {}
    ///
    /// let rng = MyCryptoRng(rand::rngs::StdRng::seed_from_u64(42));
    /// let custom = CustomCryptoRng::new(rng);
    /// # }
    /// ```
    pub fn new(rng: impl RngCrypto + 'static) -> Self {
        Self {
            rng: Arc::new(spin::mutex::Mutex::new(rng)),
        }
    }
}

#[cfg(feature = "custom")]
impl RngCrypto for CustomCryptoRng {}

#[cfg(feature = "custom")]
impl CryptoRng for CustomCryptoRng {}

#[cfg(feature = "custom")]
impl RngCore for CustomCryptoRng {
    fn next_u32(&mut self) -> u32 {
        let mut rl = self.rng.lock();
        rl.next_u32()
    }

    fn next_u64(&mut self) -> u64 {
        let mut rl = self.rng.lock();
        rl.next_u64()
    }

    fn fill_bytes(&mut self, dest: &mut [u8]) {
        let mut rl = self.rng.lock();
        rl.fill_bytes(dest);
    }

    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
        let mut rl = self.rng.lock();
        rl.try_fill_bytes(dest)
    }
}

/// Unified RNG enum supporting multiple random number generator backends.
///
/// This enum provides a common interface over different RNG implementations, allowing
/// users to choose the appropriate RNG for their use case while maintaining a consistent API.
///
/// # Variants
///
/// - `Std` - Standard RNG (`StdRng`) - Fast, suitable for general use, can be seeded for reproducibility
/// - `Thread` - Thread-local RNG (`ThreadRng`) - Convenient, automatically seeded, thread-local
/// - `OS` - Operating system RNG (`OsRng`) - Cryptographically secure, uses OS entropy
/// - `Custom` - Custom RNG wrapper - For user-provided RNG implementations
/// - `CustomRaw` - Raw custom RNG with Arc/Mutex - For advanced use cases
/// - `CustomRawSend` - Send-safe raw custom RNG - For concurrent scenarios
/// - `CustomCrypto` - Custom cryptographic RNG - For custom crypto implementations
/// - `CustomCryptoRaw` - Raw custom crypto RNG - Advanced crypto use cases
/// - `CustomCryptoRawSend` - Send-safe raw custom crypto RNG - Concurrent crypto scenarios
///
/// # Feature Flags
///
/// Different variants are available under different feature flags:
/// - `Std` requires `core` or `send_only`
/// - `Thread` and `OS` require `core`
/// - Custom variants require `custom` or `custom_send_only`
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// use product_os_random::{RNG, RngCore};
/// use rand::SeedableRng;
///
/// // Create a seeded RNG for reproducible results
/// let rng = RNG::Std(rand::rngs::StdRng::seed_from_u64(42));
///
/// // Or use OS randomness for cryptographic security
/// let crypto_rng = RNG::OS(rand::rngs::OsRng);
/// # }
/// ```
///
/// # Performance
///
/// - `StdRng`: Fast, suitable for simulations and general use
/// - `ThreadRng`: Fast, convenient, good default choice
/// - `OsRng`: Slower but cryptographically secure
/// - Custom variants: Performance depends on the wrapped RNG
///
/// # Size Note
///
/// This enum has a large size difference between variants (`StdRng` is ~312 bytes while others
/// are ~16 bytes). This is intentional to avoid boxing and maintain API compatibility.
#[cfg(feature = "rand")]
#[allow(clippy::large_enum_variant)]
#[derive(Clone)]
pub enum RNG {
    /// Standard RNG (`StdRng`) - Fast, can be seeded for reproducible results.
    #[cfg(any(feature = "core", feature = "send_only"))]
    Std(StdRng),
    /// Thread-local RNG (`ThreadRng`) - Convenient, automatically seeded, thread-local.
    /// Excluded when `send_only` is active since `ThreadRng` is not `Send`.
    #[cfg(all(feature = "core", not(feature = "send_only")))]
    Thread(ThreadRng),
    /// Operating system RNG (`OsRng`) - Cryptographically secure, uses OS entropy.
    #[cfg(feature = "core")]
    OS(OsRng),
    /// Custom RNG wrapper - For user-provided RNG implementations.
    #[cfg(feature = "custom")]
    Custom(CustomRng),
    /// Raw custom RNG with Arc/Mutex - For advanced use cases.
    #[cfg(feature = "custom")]
    CustomRaw(Arc<spin::mutex::Mutex<dyn RngCore>>),
    /// Send-safe raw custom RNG - For concurrent scenarios.
    #[cfg(any(feature = "custom", feature = "custom_send_only"))]
    CustomRawSend(Arc<spin::mutex::Mutex<dyn RngCore + Send>>),
    /// Custom cryptographic RNG - For custom crypto implementations.
    #[cfg(feature = "custom")]
    CustomCrypto(CustomCryptoRng),
    /// Raw custom crypto RNG - Advanced crypto use cases.
    #[cfg(feature = "custom")]
    CustomCryptoRaw(Arc<spin::mutex::Mutex<dyn RngCrypto>>),
    /// Send-safe raw custom crypto RNG - Concurrent crypto scenarios.
    #[cfg(any(feature = "custom", feature = "custom_send_only"))]
    CustomCryptoRawSend(Arc<spin::mutex::Mutex<dyn RngCrypto + Send>>),
}

#[cfg(feature = "rand")]
impl RngCore for RNG {
    fn next_u32(&mut self) -> u32 {
        match self {
            #[cfg(any(feature = "core", feature = "send_only"))]
            RNG::Std(r) => r.next_u32(),
            #[cfg(all(feature = "core", not(feature = "send_only")))]
            RNG::Thread(r) => r.next_u32(),
            #[cfg(feature = "core")]
            RNG::OS(r) => r.next_u32(),
            #[cfg(feature = "custom")]
            RNG::Custom(r) => r.next_u32(),
            #[cfg(feature = "custom")]
            RNG::CustomRaw(r) => {
                let mut rl = r.lock();
                rl.next_u32()
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            RNG::CustomRawSend(r) => {
                let mut rl = r.lock();
                rl.next_u32()
            }
            #[cfg(feature = "custom")]
            RNG::CustomCrypto(r) => r.next_u32(),
            #[cfg(feature = "custom")]
            RNG::CustomCryptoRaw(r) => {
                let mut rl = r.lock();
                rl.next_u32()
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            RNG::CustomCryptoRawSend(r) => {
                let mut rl = r.lock();
                rl.next_u32()
            }
            _ => panic!("No known random generator"),
        }
    }

    fn next_u64(&mut self) -> u64 {
        match self {
            #[cfg(any(feature = "core", feature = "send_only"))]
            RNG::Std(r) => r.next_u64(),
            #[cfg(all(feature = "core", not(feature = "send_only")))]
            RNG::Thread(r) => r.next_u64(),
            #[cfg(feature = "core")]
            RNG::OS(r) => r.next_u64(),
            #[cfg(feature = "custom")]
            RNG::Custom(r) => r.next_u64(),
            #[cfg(feature = "custom")]
            RNG::CustomRaw(r) => {
                let mut rl = r.lock();
                rl.next_u64()
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            RNG::CustomRawSend(r) => {
                let mut rl = r.lock();
                rl.next_u64()
            }
            #[cfg(feature = "custom")]
            RNG::CustomCrypto(r) => r.next_u64(),
            #[cfg(feature = "custom")]
            RNG::CustomCryptoRaw(r) => {
                let mut rl = r.lock();
                rl.next_u64()
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            RNG::CustomCryptoRawSend(r) => {
                let mut rl = r.lock();
                rl.next_u64()
            }
            _ => panic!("No known random generator"),
        }
    }

    #[allow(unused_variables)]
    fn fill_bytes(&mut self, dest: &mut [u8]) {
        match self {
            #[cfg(any(feature = "core", feature = "send_only"))]
            RNG::Std(r) => r.fill_bytes(dest),
            #[cfg(all(feature = "core", not(feature = "send_only")))]
            RNG::Thread(r) => r.fill_bytes(dest),
            #[cfg(feature = "core")]
            RNG::OS(r) => r.fill_bytes(dest),
            #[cfg(feature = "custom")]
            RNG::Custom(r) => r.fill_bytes(dest),
            #[cfg(feature = "custom")]
            RNG::CustomRaw(r) => {
                let mut rl = r.lock();
                rl.fill_bytes(dest);
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            RNG::CustomRawSend(r) => {
                let mut rl = r.lock();
                rl.fill_bytes(dest);
            }
            #[cfg(feature = "custom")]
            RNG::CustomCrypto(r) => r.fill_bytes(dest),
            #[cfg(feature = "custom")]
            RNG::CustomCryptoRaw(r) => {
                let mut rl = r.lock();
                rl.fill_bytes(dest);
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            RNG::CustomCryptoRawSend(r) => {
                let mut rl = r.lock();
                rl.fill_bytes(dest);
            }
            _ => panic!("No known random generator"),
        }
    }

    #[allow(unused_variables)]
    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
        match self {
            #[cfg(any(feature = "core", feature = "send_only"))]
            RNG::Std(r) => r.try_fill_bytes(dest),
            #[cfg(all(feature = "core", not(feature = "send_only")))]
            RNG::Thread(r) => r.try_fill_bytes(dest),
            #[cfg(feature = "core")]
            RNG::OS(r) => r.try_fill_bytes(dest),
            #[cfg(feature = "custom")]
            RNG::Custom(r) => r.try_fill_bytes(dest),
            #[cfg(feature = "custom")]
            RNG::CustomRaw(r) => {
                let mut rl = r.lock();
                rl.try_fill_bytes(dest)
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            RNG::CustomRawSend(r) => {
                let mut rl = r.lock();
                rl.try_fill_bytes(dest)
            }
            #[cfg(feature = "custom")]
            RNG::CustomCrypto(r) => r.try_fill_bytes(dest),
            #[cfg(feature = "custom")]
            RNG::CustomCryptoRaw(r) => {
                let mut rl = r.lock();
                rl.try_fill_bytes(dest)
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            RNG::CustomCryptoRawSend(r) => {
                let mut rl = r.lock();
                rl.try_fill_bytes(dest)
            }
            _ => panic!("No known random generator"),
        }
    }
}

/// Unified cryptographically secure RNG enum.
///
/// Similar to `RNG`, but all variants implement the `CryptoRng` marker trait, indicating
/// they are suitable for security-sensitive operations.
///
/// # Security Guarantee
///
/// All variants of this enum provide cryptographically secure random number generation,
/// suitable for:
/// - Key generation
/// - Password creation
/// - Security tokens
/// - Cryptographic nonces
/// - Any security-critical random data
///
/// # Variants
///
/// - `Std` - `StdRng` (when used with proper entropy source)
/// - `Thread` - `ThreadRng` (cryptographically secure)
/// - `OS` - `OsRng` (uses OS-provided cryptographic RNG)
/// - `CustomCrypto` - Custom crypto RNG wrapper
/// - `CustomCryptoRaw` - Raw custom crypto RNG
/// - `CustomCryptoRawSend` - Send-safe raw custom crypto RNG
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// use product_os_random::{CryptoRNG, RngCore, CryptoRng};
///
/// // Use OS randomness for maximum security
/// let mut rng = CryptoRNG::OS(rand::rngs::OsRng);
///
/// // Generate cryptographically secure random bytes
/// let mut key = [0u8; 32];
/// rng.fill_bytes(&mut key);
/// # }
/// ```
///
/// # Performance
///
/// Cryptographic RNGs are generally slower than non-cryptographic ones, as they
/// must maintain security properties. `OsRng` may block if entropy is not available.
///
/// # Size Note
///
/// This enum has a large size difference between variants (`StdRng` is ~312 bytes while others
/// are ~16 bytes). This is intentional to avoid boxing and maintain API compatibility.
#[cfg(feature = "rand")]
#[allow(clippy::large_enum_variant)]
#[derive(Clone)]
pub enum CryptoRNG {
    /// Standard RNG (`StdRng`) - When used with proper entropy source.
    #[cfg(any(feature = "core", feature = "send_only"))]
    Std(StdRng),
    /// Thread-local RNG (`ThreadRng`) - Cryptographically secure.
    /// Excluded when `send_only` is active since `ThreadRng` is not `Send`.
    #[cfg(all(feature = "core", not(feature = "send_only")))]
    Thread(ThreadRng),
    /// Operating system RNG (`OsRng`) - Uses OS-provided cryptographic RNG.
    #[cfg(feature = "core")]
    OS(OsRng),
    /// Custom cryptographic RNG wrapper.
    #[cfg(feature = "custom")]
    CustomCrypto(CustomCryptoRng),
    /// Raw custom crypto RNG with Arc/Mutex.
    #[cfg(feature = "custom")]
    CustomCryptoRaw(Arc<spin::mutex::Mutex<dyn RngCrypto>>),
    /// Send-safe raw custom crypto RNG.
    #[cfg(any(feature = "custom", feature = "custom_send_only"))]
    CustomCryptoRawSend(Arc<spin::mutex::Mutex<dyn RngCrypto + Send>>),
}

#[cfg(feature = "rand")]
impl CryptoRng for CryptoRNG {}

#[cfg(feature = "rand")]
impl RngCore for CryptoRNG {
    fn next_u32(&mut self) -> u32 {
        match self {
            #[cfg(any(feature = "core", feature = "send_only"))]
            CryptoRNG::Std(r) => r.next_u32(),
            #[cfg(all(feature = "core", not(feature = "send_only")))]
            CryptoRNG::Thread(r) => r.next_u32(),
            #[cfg(feature = "core")]
            CryptoRNG::OS(r) => r.next_u32(),
            #[cfg(feature = "custom")]
            CryptoRNG::CustomCrypto(r) => r.next_u32(),
            #[cfg(feature = "custom")]
            CryptoRNG::CustomCryptoRaw(r) => {
                let mut rl = r.lock();
                rl.next_u32()
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            CryptoRNG::CustomCryptoRawSend(r) => {
                let mut rl = r.lock();
                rl.next_u32()
            }
            _ => panic!("No known random generator"),
        }
    }

    fn next_u64(&mut self) -> u64 {
        match self {
            #[cfg(any(feature = "core", feature = "send_only"))]
            CryptoRNG::Std(r) => r.next_u64(),
            #[cfg(all(feature = "core", not(feature = "send_only")))]
            CryptoRNG::Thread(r) => r.next_u64(),
            #[cfg(feature = "core")]
            CryptoRNG::OS(r) => r.next_u64(),
            #[cfg(feature = "custom")]
            CryptoRNG::CustomCrypto(r) => r.next_u64(),
            #[cfg(feature = "custom")]
            CryptoRNG::CustomCryptoRaw(r) => {
                let mut rl = r.lock();
                rl.next_u64()
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            CryptoRNG::CustomCryptoRawSend(r) => {
                let mut rl = r.lock();
                rl.next_u64()
            }
            _ => panic!("No known random generator"),
        }
    }

    #[allow(unused_variables)]
    fn fill_bytes(&mut self, dest: &mut [u8]) {
        match self {
            #[cfg(any(feature = "core", feature = "send_only"))]
            CryptoRNG::Std(r) => r.fill_bytes(dest),
            #[cfg(all(feature = "core", not(feature = "send_only")))]
            CryptoRNG::Thread(r) => r.fill_bytes(dest),
            #[cfg(feature = "core")]
            CryptoRNG::OS(r) => r.fill_bytes(dest),
            #[cfg(feature = "custom")]
            CryptoRNG::CustomCrypto(r) => r.fill_bytes(dest),
            #[cfg(feature = "custom")]
            CryptoRNG::CustomCryptoRaw(r) => {
                let mut rl = r.lock();
                rl.fill_bytes(dest);
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            CryptoRNG::CustomCryptoRawSend(r) => {
                let mut rl = r.lock();
                rl.fill_bytes(dest);
            }
            _ => panic!("No known random generator"),
        }
    }

    #[allow(unused_variables)]
    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
        match self {
            #[cfg(any(feature = "core", feature = "send_only"))]
            CryptoRNG::Std(r) => r.try_fill_bytes(dest),
            #[cfg(all(feature = "core", not(feature = "send_only")))]
            CryptoRNG::Thread(r) => r.try_fill_bytes(dest),
            #[cfg(feature = "core")]
            CryptoRNG::OS(r) => r.try_fill_bytes(dest),
            #[cfg(feature = "custom")]
            CryptoRNG::CustomCrypto(r) => r.try_fill_bytes(dest),
            #[cfg(feature = "custom")]
            CryptoRNG::CustomCryptoRaw(r) => {
                let mut rl = r.lock();
                rl.try_fill_bytes(dest)
            }
            #[cfg(any(feature = "custom", feature = "custom_send_only"))]
            CryptoRNG::CustomCryptoRawSend(r) => {
                let mut rl = r.lock();
                rl.try_fill_bytes(dest)
            }
            _ => panic!("No known random generator"),
        }
    }
}

/// High-level random data generator with stateful RNG.
///
/// `RandomGenerator` provides convenient methods for generating various types of random data
/// while maintaining an internal RNG state. It implements the `RandomGeneratorTemplate` trait
/// for instance methods and provides static methods for one-time generation.
///
/// # Usage Patterns
///
/// ## Stateful Generation
///
/// Create a generator once and reuse it for multiple operations:
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// use product_os_random::{RandomGenerator, RandomGeneratorTemplate};
///
/// let mut gen = RandomGenerator::new(None); // Uses default RNG
/// let bytes1 = gen.get_random_bytes(10);
/// let bytes2 = gen.get_random_bytes(10);
/// let number = gen.get_random_usize(1, 100);
/// # }
/// ```
///
/// ## One-Time Generation
///
/// Use static methods for single random values without maintaining state:
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// use product_os_random::RandomGenerator;
///
/// let password = RandomGenerator::get_simple_random_password_one_time(16);
/// let alphanumeric = RandomGenerator::get_simple_random_alphanumeric_one_time(10);
/// # }
/// ```
///
/// # Feature-Gated Behavior
///
/// - With `core` or `send_only`: Can create generator without providing RNG (uses `StdRng::from_entropy()`)
/// - With `constrained` only: Must provide an RNG, panics if None given
///
/// # Panics
///
/// Methods will panic in `constrained` mode if no RNG is provided. In `core` or `send_only` modes,
/// a default RNG is used when None is provided.
#[cfg(feature = "rand")]
#[derive(Clone)]
pub struct RandomGenerator {
    generator: RNG,
}

#[cfg(any(feature = "constrained", feature = "core", feature = "send_only"))]
impl RandomGenerator {
    /// Creates a new `RandomGenerator` with the provided RNG, or uses a default RNG.
    ///
    /// # Arguments
    ///
    /// * `gen` - Optional RNG to use. If `None` is provided:
    ///   - In `core` or `send_only` mode: Uses `StdRng::from_entropy()`
    ///   - In `constrained` mode: Panics with "No generator provided"
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(feature = "core")]
    /// # {
    /// use product_os_random::{RandomGenerator, RNG};
    /// use rand::SeedableRng;
    ///
    /// // With custom RNG
    /// let rng = RNG::Std(rand::rngs::StdRng::seed_from_u64(42));
    /// let gen = RandomGenerator::new(Some(rng));
    ///
    /// // With default RNG (core/send_only only)
    /// let gen2 = RandomGenerator::new(None);
    /// # }
    /// ```
    ///
    /// # Panics
    ///
    /// Panics in `constrained` mode if `gen` is `None`.
    pub fn new(gen: Option<RNG>) -> Self {
        let generator = {
            #[cfg(all(
                feature = "constrained",
                all(not(feature = "core"), not(feature = "send_only"))
            ))]
            {
                match gen {
                    Some(g) => g,
                    None => panic!("No generator provided"),
                }
            }
            #[cfg(any(feature = "core", feature = "send_only"))]
            {
                gen.unwrap_or_else(|| RNG::Std(StdRng::from_entropy()))
            }
        };

        Self { generator }
    }

    /// Generates a cryptographic key of the specified length (simple version, no custom RNG).
    ///
    /// This is a convenience method that generates a key without requiring an RNG parameter.
    /// Uses `StdRng::from_entropy()` in `core`/`send_only` mode.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the key in bytes
    ///
    /// # Returns
    ///
    /// A `Vec<u8>` containing `len` random bytes suitable for cryptographic use.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(feature = "core")]
    /// # {
    /// use product_os_random::RandomGenerator;
    ///
    /// let key = RandomGenerator::generate_simple_key_one_time(32);
    /// assert_eq!(key.len(), 32);
    /// # }
    /// ```
    pub fn generate_simple_key_one_time(len: usize) -> Vec<u8> {
        RandomGenerator::generate_key_one_time(len, &mut None::<RNG>)
    }

    /// Generates a cryptographic key of the specified length with an optional custom RNG.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the key in bytes
    /// * `gen` - Optional RNG to use. If `None`, uses default RNG (in `core`/`send_only` mode)
    ///
    /// # Returns
    ///
    /// A `Vec<u8>` containing `len` random bytes.
    ///
    /// # Panics
    ///
    /// Panics in `constrained` mode if `gen` is `None`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(feature = "core")]
    /// # {
    /// use product_os_random::RandomGenerator;
    /// use rand::SeedableRng;
    ///
    /// let mut rng = Some(rand::rngs::StdRng::seed_from_u64(42));
    /// let key = RandomGenerator::generate_key_one_time(32, &mut rng);
    /// assert_eq!(key.len(), 32);
    /// # }
    /// ```
    pub fn generate_key_one_time(len: usize, gen: &mut Option<impl RngCore>) -> Vec<u8> {
        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    let mut key = Vec::with_capacity(len);
                    for _ in 0..len {
                        key.push(rng.gen());
                    }
                    key
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                let mut key = Vec::with_capacity(len);
                for _ in 0..len {
                    key.push(rng.gen());
                }
                key
            } else {
                let mut rng = StdRng::from_entropy();
                let mut key = Vec::with_capacity(len);
                for _ in 0..len {
                    key.push(rng.gen());
                }
                key
            }
        }
    }

    /// Generates random bytes (simple version, no custom RNG needed).
    ///
    /// This is a convenience wrapper around `get_random_bytes_one_time` that uses the default RNG.
    ///
    /// # Arguments
    ///
    /// * `len` - Number of bytes to generate
    ///
    /// # Returns
    ///
    /// A `Vec<u8>` containing `len` random bytes (0-255).
    pub fn get_simple_random_bytes_one_time(len: usize) -> Vec<u8> {
        RandomGenerator::get_random_bytes_one_time(len, &mut None::<RNG>)
    }

    /// Generates random bytes with an optional custom RNG.
    ///
    /// # Arguments
    ///
    /// * `len` - Number of bytes to generate
    /// * `gen` - Optional RNG to use. If `None`, uses default RNG (in `core`/`send_only` mode)
    ///
    /// # Returns
    ///
    /// A `Vec<u8>` containing `len` random bytes (0-255).
    ///
    /// # Panics
    ///
    /// Panics in `constrained` mode if `gen` is `None`.
    pub fn get_random_bytes_one_time(len: usize, gen: &mut Option<impl RngCore>) -> Vec<u8> {
        let mut bytes = vec![0u8; len];
        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    rng.fill_bytes(&mut bytes);
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                rng.fill_bytes(&mut bytes);
            } else {
                let mut rng = StdRng::from_entropy();
                rng.fill_bytes(&mut bytes);
            }
        }
        bytes
    }

    /// Generates a random `usize` within range (simple version, no custom RNG).
    ///
    /// This is a convenience method that generates a random number without requiring an RNG parameter.
    ///
    /// # Arguments
    ///
    /// * `min` - Minimum value (inclusive)
    /// * `max` - Maximum value (inclusive)
    ///
    /// # Returns
    ///
    /// A random `usize` in the range `[min, max]`.
    pub fn get_simple_random_usize_one_time(min: usize, max: usize) -> usize {
        RandomGenerator::get_random_usize_one_time(min, max, &mut None::<RNG>)
    }

    /// Generates a random `usize` within range with an optional custom RNG.
    ///
    /// # Arguments
    ///
    /// * `min` - Minimum value (inclusive)
    /// * `max` - Maximum value (inclusive)
    /// * `gen` - Optional RNG to use. If `None`, uses default RNG (in `core`/`send_only` mode)
    ///
    /// # Returns
    ///
    /// A random `usize` in the range `[min, max]`.
    ///
    /// # Panics
    ///
    /// Panics in `constrained` mode if `gen` is `None`.
    pub fn get_random_usize_one_time(
        min: usize,
        max: usize,
        gen: &mut Option<impl RngCore>,
    ) -> usize {
        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => rng.gen_range(min..=max),
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                rng.gen_range(min..=max)
            } else {
                let mut rng = StdRng::from_entropy();
                rng.gen_range(min..=max)
            }
        }
    }

    /// Generates a random string of printable ASCII characters (simple version).
    ///
    /// Generates a string containing random printable ASCII characters in the ranges:
    /// - Letters (a-z, A-Z)
    /// - Numbers (0-9)
    ///
    /// Special characters and symbols are excluded through character range filtering.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the string
    ///
    /// # Returns
    ///
    /// A `String` of length `len` containing random printable characters.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(feature = "core")]
    /// # {
    /// use product_os_random::RandomGenerator;
    ///
    /// let s = RandomGenerator::get_simple_random_string_one_time(10);
    /// assert_eq!(s.len(), 10);
    /// # }
    /// ```
    pub fn get_simple_random_string_one_time(len: usize) -> String {
        RandomGenerator::get_random_string_one_time(len, &mut None::<RNG>)
    }

    /// Generates a random string of printable ASCII characters with optional custom RNG.
    ///
    /// Character generation uses ASCII codes 33-122, with filtering to exclude certain
    /// special characters and symbols, resulting in alphanumeric and common punctuation.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the string
    /// * `gen` - Optional RNG to use. If `None`, uses default RNG (in `core`/`send_only` mode)
    ///
    /// # Returns
    ///
    /// A `String` of length `len` containing random characters.
    ///
    /// # Panics
    ///
    /// Panics in `constrained` mode if `gen` is `None`.
    pub fn get_random_string_one_time(len: usize, gen: &mut Option<impl RngCore>) -> String {
        let mut str = String::with_capacity(len);
        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    for _ in 0..len {
                        let value: u8 = rng.gen_range(33..=122);
                        let filtered = filter_printable_char(value);
                        str.push(char::from(filtered));
                    }
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                for _ in 0..len {
                    let value: u8 = rng.gen_range(33..=122);
                    let filtered = filter_printable_char(value);
                    str.push(char::from(filtered));
                }
            } else {
                let mut rng = StdRng::from_entropy();
                for _ in 0..len {
                    let value: u8 = rng.gen_range(33..=122);
                    let filtered = filter_printable_char(value);
                    str.push(char::from(filtered));
                }
            }
        }
        str
    }

    /// Generates a random string from a character set (simple version, no custom RNG).
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the string
    /// * `characters` - String containing the character set to choose from
    ///
    /// # Returns
    ///
    /// A `String` of length `len` with characters randomly selected from `characters`.
    pub fn get_simple_random_from_characters_one_time(len: usize, characters: &str) -> String {
        RandomGenerator::get_random_from_characters_one_time(len, characters, &mut None::<RNG>)
    }

    /// Generates a random string from a character set with an optional custom RNG.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the string
    /// * `characters` - String containing the character set to choose from
    /// * `gen` - Optional RNG to use. If `None`, uses default RNG (in `core`/`send_only` mode)
    ///
    /// # Returns
    ///
    /// A `String` of length `len` with characters randomly selected from `characters`.
    ///
    /// # Panics
    ///
    /// Panics in `constrained` mode if `gen` is `None`.
    /// May panic if `characters` is empty.
    pub fn get_random_from_characters_one_time(
        len: usize,
        characters: &str,
        gen: &mut Option<impl RngCore>,
    ) -> String {
        let mut str = String::with_capacity(len);
        let char_vec: Vec<char> = characters.chars().collect();
        let char_count = char_vec.len();

        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    for _ in 0..len {
                        let ch = char_vec[rng.gen_range(0..char_count)];
                        str.push(ch);
                    }
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                for _ in 0..len {
                    let ch = char_vec[rng.gen_range(0..char_count)];
                    str.push(ch);
                }
            } else {
                let mut rng = StdRng::from_entropy();
                for _ in 0..len {
                    let ch = char_vec[rng.gen_range(0..char_count)];
                    str.push(ch);
                }
            }
        }

        str
    }

    /// Generates a random alphanumeric string (simple version).
    ///
    /// Creates a string containing only letters (a-z, A-Z) and digits (0-9).
    /// Suitable for identifiers, codes, and non-security-critical tokens.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the string
    ///
    /// # Returns
    ///
    /// A `String` of length `len` containing random alphanumeric characters.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(feature = "core")]
    /// # {
    /// use product_os_random::RandomGenerator;
    ///
    /// let code = RandomGenerator::get_simple_random_alphanumeric_one_time(10);
    /// assert_eq!(code.len(), 10);
    /// assert!(code.chars().all(|c| c.is_alphanumeric()));
    /// # }
    /// ```
    pub fn get_simple_random_alphanumeric_one_time(len: usize) -> String {
        RandomGenerator::get_random_alphanumeric_one_time(len, &mut None::<RNG>)
    }

    /// Generates a random alphanumeric string with an optional custom RNG.
    ///
    /// Creates a string containing only letters (a-z, A-Z) and digits (0-9).
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the string
    /// * `gen` - Optional RNG to use. If `None`, uses default RNG (in `core`/`send_only` mode)
    ///
    /// # Returns
    ///
    /// A `String` of length `len` containing only alphanumeric characters.
    ///
    /// # Panics
    ///
    /// Panics in `constrained` mode if `gen` is `None`.
    pub fn get_random_alphanumeric_one_time(len: usize, gen: &mut Option<impl RngCore>) -> String {
        let mut str = String::with_capacity(len);
        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    for _ in 0..len {
                        let value: u8 = rng.gen_range(48..=122);
                        let filtered = filter_alphanumeric_char(value);
                        str.push(char::from(filtered));
                    }
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                for _ in 0..len {
                    let value: u8 = rng.gen_range(48..=122);
                    let filtered = filter_alphanumeric_char(value);
                    str.push(char::from(filtered));
                }
            } else {
                let mut rng = StdRng::from_entropy();
                for _ in 0..len {
                    let value: u8 = rng.gen_range(48..=122);
                    let filtered = filter_alphanumeric_char(value);
                    str.push(char::from(filtered));
                }
            }
        }
        str
    }

    /// Generates a random password string (simple version).
    ///
    /// Creates a password containing a wide range of printable ASCII characters (33-122),
    /// including letters, digits, and special characters.
    ///
    /// # Security Note
    ///
    /// For production password generation, consider using `CryptoRNG` with `OsRng` to ensure
    /// cryptographic security.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the password
    ///
    /// # Returns
    ///
    /// A `String` of length `len` containing random password characters.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(feature = "core")]
    /// # {
    /// use product_os_random::RandomGenerator;
    ///
    /// let password = RandomGenerator::get_simple_random_password_one_time(16);
    /// assert_eq!(password.len(), 16);
    /// # }
    /// ```
    pub fn get_simple_random_password_one_time(len: usize) -> String {
        RandomGenerator::get_random_password_one_time(len, &mut None::<RNG>)
    }

    /// Generates a random password string with an optional custom RNG.
    ///
    /// Creates a password containing a wide range of printable ASCII characters (33-122),
    /// including letters, digits, and special characters.
    ///
    /// # Security Note
    ///
    /// For production password generation, consider using `CryptoRNG` with `OsRng` to ensure
    /// cryptographic security.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the password
    /// * `gen` - Optional RNG to use. If `None`, uses default RNG (in `core`/`send_only` mode)
    ///
    /// # Returns
    ///
    /// A `String` of length `len` containing random password characters.
    ///
    /// # Panics
    ///
    /// Panics in `constrained` mode if `gen` is `None`.
    pub fn get_random_password_one_time(len: usize, gen: &mut Option<impl RngCore>) -> String {
        let mut str = String::with_capacity(len);
        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    for _ in 0..len {
                        let value: u8 = rng.gen_range(33..=122);
                        str.push(char::from(value));
                    }
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                for _ in 0..len {
                    let value: u8 = rng.gen_range(33..=122);
                    str.push(char::from(value));
                }
            } else {
                let mut rng = StdRng::from_entropy();
                for _ in 0..len {
                    let value: u8 = rng.gen_range(33..=122);
                    str.push(char::from(value));
                }
            }
        }
        str
    }

    /// Generates a random email address using a default RNG.
    ///
    /// This is a convenience wrapper around `get_random_email_one_time` that uses
    /// a default RNG instance.
    ///
    /// # Arguments
    ///
    /// * `num_names` - Optional number of name components (default: 2)
    /// * `num_numbers` - Optional number of numeric components (default: 0)
    /// * `separator` - Optional separator between components (default: ".")
    /// * `domains` - List of possible email domains to choose from
    ///
    /// # Returns
    ///
    /// A random email address string
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(all(feature = "core", feature = "names"))]
    /// # {
    /// use product_os_random::RandomGenerator;
    ///
    /// let email = RandomGenerator::get_simple_random_email_one_time(
    ///     Some(2), Some(0), Some(".".to_string()), vec!["example.com".to_string()]
    /// );
    /// println!("Random email: {}", email);
    /// # }
    /// ```
    #[cfg(feature = "names")]
    pub fn get_simple_random_email_one_time(
        num_names: Option<usize>,
        num_numbers: Option<usize>,
        separator: Option<String>,
        domains: Vec<String>,
    ) -> String {
        RandomGenerator::get_random_email_one_time(
            num_names,
            num_numbers,
            separator,
            domains,
            &mut None::<RNG>,
        )
    }

    /// Generates a random email address using the provided RNG.
    ///
    /// Creates an email address by combining random names, optional numbers, and
    /// a domain from the provided list.
    ///
    /// # Arguments
    ///
    /// * `num_names` - Optional number of name components (default: 2)
    /// * `num_numbers` - Optional number of numeric components (default: 0)
    /// * `separator` - Optional separator between components (default: ".")
    /// * `domains` - List of possible email domains to choose from
    /// * `gen` - Mutable reference to an optional RNG instance
    ///
    /// # Returns
    ///
    /// A random email address string
    #[cfg(feature = "names")]
    #[allow(clippy::needless_pass_by_value)] // Keep Vec<String> for API compatibility
    pub fn get_random_email_one_time(
        num_names: Option<usize>,
        num_numbers: Option<usize>,
        separator: Option<String>,
        domains: Vec<String>,
        gen: &mut Option<impl RngCore>,
    ) -> String {
        let num_names = num_names.unwrap_or(2);

        let num_numbers = num_numbers.unwrap_or(3);

        let separator = separator.unwrap_or_default();

        let mut str = String::new();

        let username = RandomGenerator::get_random_username_one_time(
            Some(num_names),
            Some(num_numbers),
            Some(separator.clone()),
            gen,
        );

        str.push_str(username.as_str());
        str.push('@');

        let num_domains = domains.len();

        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    let pick_domain = rng.gen_range(0..num_domains);
                    str.push_str(domains.get(pick_domain).unwrap().as_str());
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                let pick_domain = rng.gen_range(0..num_domains);
                str.push_str(domains.get(pick_domain).unwrap().as_str());
            } else {
                let mut rng = StdRng::from_entropy();
                let pick_domain = rng.gen_range(0..num_domains);
                str.push_str(domains.get(pick_domain).unwrap().as_str());
            }
        }

        str
    }

    /// Generates a random username using a default RNG.
    ///
    /// This is a convenience wrapper around `get_random_username_one_time` that uses
    /// a default RNG instance.
    ///
    /// # Arguments
    ///
    /// * `num_names` - Optional number of name components (default: 2)
    /// * `num_numbers` - Optional number of numeric components (default: 0)
    /// * `separator` - Optional separator between components (default: "_")
    ///
    /// # Returns
    ///
    /// A random username string
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(all(feature = "core", feature = "names"))]
    /// # {
    /// use product_os_random::RandomGenerator;
    ///
    /// let username = RandomGenerator::get_simple_random_username_one_time(
    ///     Some(2), Some(3), Some("_".to_string())
    /// );
    /// println!("Random username: {}", username);
    /// # }
    /// ```
    #[cfg(feature = "names")]
    pub fn get_simple_random_username_one_time(
        num_names: Option<usize>,
        num_numbers: Option<usize>,
        separator: Option<String>,
    ) -> String {
        RandomGenerator::get_random_username_one_time(
            num_names,
            num_numbers,
            separator,
            &mut None::<RNG>,
        )
    }

    /// Generates a random username using the provided RNG.
    ///
    /// Creates a username by combining random names and optional numbers with a separator.
    ///
    /// # Arguments
    ///
    /// * `num_names` - Optional number of name components (default: 2)
    /// * `num_numbers` - Optional number of numeric components (default: 0)
    /// * `separator` - Optional separator between components (default: "_")
    /// * `gen` - Mutable reference to an optional RNG instance
    ///
    /// # Returns
    ///
    /// A random username string
    #[cfg(feature = "names")]
    pub fn get_random_username_one_time(
        num_names: Option<usize>,
        num_numbers: Option<usize>,
        separator: Option<String>,
        gen: &mut Option<impl RngCore>,
    ) -> String {
        let names_count = names::NAMES.len();

        let num_names = num_names.unwrap_or(2);

        let num_numbers = num_numbers.unwrap_or(5);

        let separator = separator.unwrap_or_default();

        let mut str = String::new();

        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    for counter in 0..num_names {
                        let value: usize = rng.gen_range(0..names_count);
                        if counter > 0 {
                            str.push_str(separator.as_str());
                        }
                        str.push_str(names::NAMES[value].to_lowercase().as_str());
                    }

                    if num_numbers > 0 {
                        str.push_str(separator.as_str());
                    }

                    for _ in 0..num_numbers {
                        let value: u8 = rng.gen_range(48..57);
                        str.push(char::from(value));
                    }
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                for counter in 0..num_names {
                    let value: usize = rng.gen_range(0..names_count);
                    if counter > 0 {
                        str.push_str(separator.as_str());
                    }
                    str.push_str(names::NAMES[value].to_lowercase().as_str());
                }

                if num_numbers > 0 {
                    str.push_str(separator.as_str());
                }

                for _ in 0..num_numbers {
                    let value: u8 = rng.gen_range(48..57);
                    str.push(char::from(value));
                }
            } else {
                let mut rng = StdRng::from_entropy();
                for counter in 0..num_names {
                    let value: usize = rng.gen_range(0..names_count);
                    if counter > 0 {
                        str.push_str(separator.as_str());
                    }
                    str.push_str(names::NAMES[value].to_lowercase().as_str());
                }

                if num_numbers > 0 {
                    str.push_str(separator.as_str());
                }

                for _ in 0..num_numbers {
                    let value: u8 = rng.gen_range(48..57);
                    str.push(char::from(value));
                }
            }
        }

        str
    }

    /// Generates a random full name using a default RNG.
    ///
    /// This is a convenience wrapper around `get_random_name_one_time` that uses
    /// a default RNG instance.
    ///
    /// # Returns
    ///
    /// A random full name string (first name + last name)
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(all(feature = "core", feature = "names", feature = "first_names", feature = "last_names"))]
    /// # {
    /// use product_os_random::RandomGenerator;
    ///
    /// let name = RandomGenerator::get_simple_random_name_one_time();
    /// println!("Random name: {}", name);
    /// # }
    /// ```
    #[cfg(feature = "names")]
    pub fn get_simple_random_name_one_time() -> String {
        RandomGenerator::get_random_name_one_time(&mut None::<RNG>)
    }

    /// Generates a random full name using the provided RNG.
    ///
    /// Creates a full name by combining a random first name and last name.
    ///
    /// # Arguments
    ///
    /// * `gen` - Mutable reference to an optional RNG instance
    ///
    /// # Returns
    ///
    /// A random full name string (first name + last name)
    #[cfg(feature = "names")]
    pub fn get_random_name_one_time(gen: &mut Option<impl RngCore>) -> String {
        let names_count = names::NAMES.len();

        let mut str = String::new();

        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    let value: usize = rng.gen_range(0..names_count);
                    str.push_str(names::NAMES[value]);
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                let value: usize = rng.gen_range(0..names_count);
                str.push_str(names::NAMES[value]);
            } else {
                let mut rng = StdRng::from_entropy();
                let value: usize = rng.gen_range(0..names_count);
                str.push_str(names::NAMES[value]);
            }
        }
        str
    }

    /// Generates a random first name using a default RNG.
    ///
    /// This is a convenience wrapper around `get_random_first_name_one_time` that uses
    /// a default RNG instance.
    ///
    /// # Returns
    ///
    /// A random first name string (capitalized)
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(all(feature = "core", feature = "names", feature = "first_names"))]
    /// # {
    /// use product_os_random::RandomGenerator;
    ///
    /// let first_name = RandomGenerator::get_simple_random_first_name_one_time();
    /// println!("Random first name: {}", first_name);
    /// # }
    /// ```
    #[cfg(feature = "names")]
    pub fn get_simple_random_first_name_one_time() -> String {
        RandomGenerator::get_random_first_name_one_time(&mut None::<RNG>)
    }

    /// Generates a random first name using the provided RNG.
    ///
    /// Selects a random first name from the built-in dataset and capitalizes it.
    ///
    /// # Arguments
    ///
    /// * `gen` - Mutable reference to an optional RNG instance
    ///
    /// # Returns
    ///
    /// A random first name string (capitalized)
    #[cfg(feature = "first_names")]
    pub fn get_random_first_name_one_time(gen: &mut Option<impl RngCore>) -> String {
        let names_count = first_names::FIRSTNAMES.len();

        let mut str = String::new();

        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    let value: usize = rng.gen_range(0..names_count);
                    str.push_str(to_title_case(first_names::FIRSTNAMES[value]).as_str());
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                let value: usize = rng.gen_range(0..names_count);
                str.push_str(to_title_case(first_names::FIRSTNAMES[value]).as_str());
            } else {
                let mut rng = StdRng::from_entropy();
                let value: usize = rng.gen_range(0..names_count);
                str.push_str(to_title_case(first_names::FIRSTNAMES[value]).as_str());
            }
        }

        str
    }

    /// Generates a random last name using a default RNG.
    ///
    /// This is a convenience wrapper around `get_random_last_name_one_time` that uses
    /// a default RNG instance.
    ///
    /// # Returns
    ///
    /// A random last name string (capitalized)
    ///
    /// # Examples
    ///
    /// ```rust
    /// # #[cfg(all(feature = "core", feature = "names", feature = "last_names"))]
    /// # {
    /// use product_os_random::RandomGenerator;
    ///
    /// let last_name = RandomGenerator::get_simple_random_last_name_one_time();
    /// println!("Random last name: {}", last_name);
    /// # }
    /// ```
    #[cfg(feature = "names")]
    pub fn get_simple_random_last_name_one_time() -> String {
        RandomGenerator::get_random_last_name_one_time(&mut None::<RNG>)
    }

    /// Generates a random last name using the provided RNG.
    ///
    /// Selects a random last name from the built-in dataset and capitalizes it.
    ///
    /// # Arguments
    ///
    /// * `gen` - Mutable reference to an optional RNG instance
    ///
    /// # Returns
    ///
    /// A random last name string (capitalized)
    #[cfg(feature = "last_names")]
    pub fn get_random_last_name_one_time(gen: &mut Option<impl RngCore>) -> String {
        let names_count = last_names::LASTNAMES.len();

        let mut str = String::new();

        #[cfg(all(
            feature = "constrained",
            all(not(feature = "core"), not(feature = "send_only"))
        ))]
        {
            match gen {
                Some(rng) => {
                    let value: usize = rng.gen_range(0..names_count);
                    str.push_str(to_title_case(last_names::LASTNAMES[value]).as_str());
                }
                None => panic!("No generator provided"),
            }
        }
        #[cfg(any(feature = "core", feature = "send_only"))]
        {
            if let Some(rng) = gen {
                let value: usize = rng.gen_range(0..names_count);
                str.push_str(to_title_case(last_names::LASTNAMES[value]).as_str());
            } else {
                let mut rng = StdRng::from_entropy();
                let value: usize = rng.gen_range(0..names_count);
                str.push_str(to_title_case(last_names::LASTNAMES[value]).as_str());
            }
        }

        str
    }
}

#[cfg(feature = "rand")]
impl RandomGeneratorTemplate for RandomGenerator {
    fn get_random_bytes(&mut self, len: usize) -> Vec<u8> {
        let mut bytes = vec![0u8; len];
        self.generator.fill_bytes(&mut bytes);
        bytes
    }

    fn get_random_usize(&mut self, min: usize, max: usize) -> usize {
        self.generator.gen_range(min..=max)
    }

    fn get_random_u32(&mut self) -> u32 {
        self.generator.next_u32()
    }

    fn get_random_u64(&mut self) -> u64 {
        self.generator.next_u64()
    }

    fn get_random_string(&mut self, len: usize) -> String {
        let mut str = String::with_capacity(len);
        for _ in 0..len {
            let value: u8 = self.generator.gen_range(33..=122);
            let filtered = filter_printable_char(value);
            str.push(char::from(filtered));
        }
        str
    }

    fn get_random_from_characters(&mut self, len: usize, characters: &str) -> String {
        let mut str = String::with_capacity(len);
        let char_vec: Vec<char> = characters.chars().collect();
        let char_count = char_vec.len();

        for _ in 0..len {
            let ch = char_vec[self.generator.gen_range(0..char_count)];
            str.push(ch);
        }

        str
    }

    fn get_random_alphanumeric(&mut self, len: usize) -> String {
        let mut str = String::with_capacity(len);
        for _ in 0..len {
            let value: u8 = self.generator.gen_range(48..=122);
            let filtered = filter_alphanumeric_char(value);
            str.push(char::from(filtered));
        }
        str
    }

    fn generate_key(&mut self, len: usize) -> Vec<u8> {
        let mut key = Vec::with_capacity(len);
        for _ in 0..len {
            key.push(self.generator.gen());
        }
        key
    }
}

/// Template trait defining instance methods for random data generation.
///
/// This trait defines the interface for stateful random generation. Types implementing
/// this trait maintain an internal RNG state and provide methods for generating various
/// types of random data.
///
/// # Implementation
///
/// `RandomGenerator` implements this trait, providing all these methods as instance methods
/// that use the generator's internal RNG.
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// use product_os_random::{RandomGenerator, RandomGeneratorTemplate};
///
/// let mut gen = RandomGenerator::new(None);
///
/// // Generate various random data
/// let bytes = gen.get_random_bytes(16);
/// let number = gen.get_random_usize(1, 100);
/// let text = gen.get_random_string(20);
/// let alphanum = gen.get_random_alphanumeric(10);
/// let key = gen.generate_key(32);
/// # }
/// ```
pub trait RandomGeneratorTemplate {
    /// Generates a vector of random bytes.
    ///
    /// # Arguments
    ///
    /// * `len` - Number of bytes to generate
    ///
    /// # Returns
    ///
    /// A `Vec<u8>` containing `len` random bytes (0-255).
    fn get_random_bytes(&mut self, len: usize) -> Vec<u8>;

    /// Generates a random `usize` within the specified range (inclusive).
    ///
    /// # Arguments
    ///
    /// * `min` - Minimum value (inclusive)
    /// * `max` - Maximum value (inclusive)
    ///
    /// # Returns
    ///
    /// A random `usize` in the range `[min, max]`.
    fn get_random_usize(&mut self, min: usize, max: usize) -> usize;

    /// Generates a random `u32`.
    ///
    /// # Returns
    ///
    /// A random 32-bit unsigned integer.
    fn get_random_u32(&mut self) -> u32;

    /// Generates a random `u64`.
    ///
    /// # Returns
    ///
    /// A random 64-bit unsigned integer.
    fn get_random_u64(&mut self) -> u64;

    /// Generates a random string of printable characters.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the string
    ///
    /// # Returns
    ///
    /// A `String` containing `len` random printable characters.
    fn get_random_string(&mut self, len: usize) -> String;

    /// Generates a random string from the provided character set.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the string
    /// * `characters` - String containing the character set to choose from
    ///
    /// # Returns
    ///
    /// A `String` of length `len` with characters randomly selected from `characters`.
    ///
    /// # Panics
    ///
    /// May panic if `characters` is empty or contains invalid UTF-8.
    fn get_random_from_characters(&mut self, len: usize, characters: &str) -> String;

    /// Generates a random alphanumeric string.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the string
    ///
    /// # Returns
    ///
    /// A `String` of length `len` containing only letters (a-z, A-Z) and digits (0-9).
    fn get_random_alphanumeric(&mut self, len: usize) -> String;

    /// Generates a cryptographic key.
    ///
    /// # Arguments
    ///
    /// * `len` - Length of the key in bytes
    ///
    /// # Returns
    ///
    /// A `Vec<u8>` containing `len` random bytes suitable for use as a cryptographic key.
    fn generate_key(&mut self, len: usize) -> Vec<u8>;
}

// =============================================================================
// Top-level convenience functions
// =============================================================================
//
// These free functions provide the simplest possible API for one-time random
// generation. They use the default RNG internally and require no parameters
// beyond the generation settings.

/// Generates a random `usize` within the specified range (inclusive).
///
/// # Arguments
///
/// * `min` - Minimum value (inclusive)
/// * `max` - Maximum value (inclusive)
///
/// # Returns
///
/// A random `usize` in the range `[min, max]`.
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// let value = product_os_random::random_usize(1, 100);
/// assert!((1..=100).contains(&value));
/// # }
/// ```
#[cfg(any(feature = "core", feature = "send_only", feature = "constrained"))]
pub fn random_usize(min: usize, max: usize) -> usize {
    RandomGenerator::get_simple_random_usize_one_time(min, max)
}

/// Generates a random string of printable ASCII characters.
///
/// # Arguments
///
/// * `len` - Length of the string
///
/// # Returns
///
/// A `String` of length `len` containing random printable characters.
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// let s = product_os_random::random_string(10);
/// assert_eq!(s.len(), 10);
/// # }
/// ```
#[cfg(any(feature = "core", feature = "send_only", feature = "constrained"))]
pub fn random_string(len: usize) -> String {
    RandomGenerator::get_simple_random_string_one_time(len)
}

/// Generates a random alphanumeric string (a-z, A-Z, 0-9).
///
/// # Arguments
///
/// * `len` - Length of the string
///
/// # Returns
///
/// A `String` of length `len` containing only alphanumeric characters.
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// let s = product_os_random::random_alphanumeric(10);
/// assert_eq!(s.len(), 10);
/// assert!(s.chars().all(|c| c.is_alphanumeric()));
/// # }
/// ```
#[cfg(any(feature = "core", feature = "send_only", feature = "constrained"))]
pub fn random_alphanumeric(len: usize) -> String {
    RandomGenerator::get_simple_random_alphanumeric_one_time(len)
}

/// Generates random bytes.
///
/// # Arguments
///
/// * `len` - Number of bytes to generate
///
/// # Returns
///
/// A `Vec<u8>` containing `len` random bytes (0-255).
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// let bytes = product_os_random::random_bytes(16);
/// assert_eq!(bytes.len(), 16);
/// # }
/// ```
#[cfg(any(feature = "core", feature = "send_only", feature = "constrained"))]
pub fn random_bytes(len: usize) -> Vec<u8> {
    RandomGenerator::get_simple_random_bytes_one_time(len)
}

/// Generates a random password string of printable ASCII characters.
///
/// # Arguments
///
/// * `len` - Length of the password
///
/// # Returns
///
/// A `String` of length `len` containing random characters suitable for passwords.
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// let pw = product_os_random::random_password(16);
/// assert_eq!(pw.len(), 16);
/// # }
/// ```
#[cfg(any(feature = "core", feature = "send_only", feature = "constrained"))]
pub fn random_password(len: usize) -> String {
    RandomGenerator::get_simple_random_password_one_time(len)
}

/// Generates a random string from a given character set.
///
/// # Arguments
///
/// * `len` - Length of the string
/// * `characters` - String containing the character set to choose from
///
/// # Returns
///
/// A `String` of length `len` with characters randomly selected from `characters`.
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// let s = product_os_random::random_from_characters(8, "abc123");
/// assert_eq!(s.len(), 8);
/// assert!(s.chars().all(|c| "abc123".contains(c)));
/// # }
/// ```
#[cfg(any(feature = "core", feature = "send_only", feature = "constrained"))]
pub fn random_from_characters(len: usize, characters: &str) -> String {
    RandomGenerator::get_simple_random_from_characters_one_time(len, characters)
}

/// Generates a cryptographic key of the specified length.
///
/// # Arguments
///
/// * `len` - Length of the key in bytes
///
/// # Returns
///
/// A `Vec<u8>` containing `len` random bytes suitable for cryptographic use.
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "core")]
/// # {
/// let key = product_os_random::generate_random_key(32);
/// assert_eq!(key.len(), 32);
/// # }
/// ```
#[cfg(any(feature = "core", feature = "send_only", feature = "constrained"))]
pub fn generate_random_key(len: usize) -> Vec<u8> {
    RandomGenerator::generate_simple_key_one_time(len)
}