# Product OS : Random
[](https://crates.io/crates/product-os-random)
[](https://docs.rs/product-os-random)
[](https://www.rust-lang.org)
[](https://www.gnu.org/licenses/gpl-3.0)
Product OS : Random provides a suite of random generator tools for different contexts. This includes random text, number and key generators including cryptographically secure random generation.
### What is Product OS?
Product OS is a collection of packages that provide different tools and features that can work together to build products more easily for the Rust ecosystem.
## Feature Flags
### 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 (requires user-provided RNG)
- `custom` - Custom RNG support with spin locks for `no_std`
- `custom_send_only` - Custom Send-safe RNG support
### Dataset Features
- `words` - Random word generation
- `nouns` - Random noun generation
- `adjectives` - Random adjective generation
- `names` - Random full name generation
- `first_names` - Random first name generation (requires `inflections`)
- `last_names` - Random last name generation (requires `inflections`)
### Example with Features
```toml
[dependencies]
product-os-random = { version = "0.0.32", features = ["core", "names", "first_names", "last_names"] }
```
```rust
use product_os_random::RandomGenerator;
// Generate random username
let username = RandomGenerator::get_simple_random_username_one_time(
Some(2),
Some(4),
Some("_".to_string())
);
// Generate random email
let email = RandomGenerator::get_simple_random_email_one_time(
Some(2),
Some(3),
None,
vec!["example.com".to_string()]
);
// Generate random first and last names
let first_name = RandomGenerator::get_simple_random_first_name_one_time();
let last_name = RandomGenerator::get_simple_random_last_name_one_time();
```
## Installation
```toml
[dependencies]
product-os-random = "0.0.1"
```
Pin the version to match the crate `Cargo.toml` when using path or git dependencies.
## Documentation
Full API documentation is available at [docs.rs/product-os-random](https://docs.rs/product-os-random).
## Usage
## Overview
A comprehensive random number generation library providing cryptographically secure RNGs, random text/number generators, and word/name generators. Supports `no_std` environments.
## Features
- **Multiple RNG Backends**: Support for `StdRng`, `ThreadRng`, `OsRng`, and custom RNGs
- **Cryptographic Security**: Dedicated `CryptoRNG` type for security-sensitive operations
- **`no_std` Support**: Works in embedded and constrained environments
- **Rich Generators**: Random strings, passwords, keys, usernames, emails, and names
- **Large Datasets**: Built-in word lists, names, nouns, and adjectives
- **Flexible API**: Both stateful generators and one-time generation functions
## Quick Start
Add to your `Cargo.toml`:
```toml
[dependencies]
product-os-random = "0.0.32"
```
### Basic Usage (Convenience Functions)
The simplest way to generate random data -- just call the top-level functions:
```rust
// Generate a random password
let password = product_os_random::random_password(16);
// Generate random alphanumeric string
let code = product_os_random::random_alphanumeric(10);
// Generate a random number in a range
let port = product_os_random::random_usize(1025, 65535);
// Generate random bytes
let bytes = product_os_random::random_bytes(32);
// Generate a cryptographic key
let key = product_os_random::generate_random_key(32);
// Generate a random string from a custom character set
let hex = product_os_random::random_from_characters(16, "0123456789abcdef");
```
### Stateful Generator
For repeated generation, create a `RandomGenerator` instance:
```rust
use product_os_random::{RandomGenerator, RandomGeneratorTemplate};
// Create a generator (uses default RNG)
let mut gen = RandomGenerator::new(None);
// Generate multiple random values efficiently
let bytes = gen.get_random_bytes(32);
let number = gen.get_random_usize(1, 100);
let text = gen.get_random_string(20);
```
### Custom RNG (Power Users)
For reproducible results or specific RNG backends, use the explicit API:
```rust
use product_os_random::{RandomGenerator, RandomGeneratorTemplate, RNG};
use rand::SeedableRng;
// Seeded RNG for reproducible output
let rng = RNG::Std(rand::rngs::StdRng::seed_from_u64(42));
let mut gen = RandomGenerator::new(Some(rng));
let number = gen.get_random_usize(1, 100);
// Or use the one-time functions with an explicit RNG
let mut rng = Some(rand::rngs::StdRng::seed_from_u64(42));
let key = RandomGenerator::generate_key_one_time(32, &mut rng);
```
### Cryptographic RNG
```rust
use product_os_random::{CryptoRNG, RngCore};
// 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);
```
## Security Considerations
### Cryptographic vs Non-Cryptographic RNGs
- **`CryptoRNG`**: Use for passwords, keys, tokens, and any security-sensitive data
- **`RNG`**: Suitable for general-purpose randomness (simulations, games, testing)
### Thread Safety
- `RNG::Thread` uses thread-local storage
- Custom RNG wrappers use `Arc<Mutex<>>` for safe concurrent access
- All RNG types implement `Clone` for easy distribution
## Performance
- String generation pre-allocates with `String::with_capacity()`
- Helper functions optimize character filtering
- Lock-based custom RNGs may have contention under high concurrency
- Dataset features add to binary size (~400K lines of data)
## no_std Support
This crate supports `no_std` environments:
```toml
[dependencies]
product-os-random = { version = "0.0.32", default-features = false, features = ["constrained"] }
```
Note: In `constrained` mode, you must provide an RNG to all generation functions.
## Minimum Supported Rust Version (MSRV)
This crate requires Rust 1.69 or later.
## Contributing
Contributions are not currently available but will be available on a public repository soon.
## License
This project is licensed under the [GNU GPLv3](https://choosealicense.com/licenses/gpl-3.0/).