//! 一个小演示：调用本 crate 暴露的随机功能并打印带标签的输出。
//!
//! 这些函数底层都用到了第三方包 `rand`，但 `main` 完全感知不到——
//! 这正是「把依赖封装进库、上层只管调用」的好处。

use rt_44_rand::{generate_password, roll_die, roll_n, sum_n};

fn main() {
    println!("=== rand：引用第三方包演示 ===\n");

    println!("掷一次骰子: {}", roll_die());
    println!("连掷 5 次:   {:?}", roll_n(5));
    println!("3 颗骰子之和: {}", sum_n(3));

    println!();
    println!("随机密码(8 位):  {}", generate_password(8));
    println!("随机密码(16 位): {}", generate_password(16));
}

//! 用 `rand` 这个第三方包演示「如何引用并使用生态库」。
//!
//! 本 crate 把功能拆成几个模块，方便对照阅读：
//! - `dice`：用范围随机数模拟掷骰子。
//! - `password`：从字符集里随机挑字符，生成随机密码。
//!
//! 所有随机能力都来自 crates.io 上的 `rand` 包（见 `Cargo.toml` 的
//! `[dependencies]`）。这正是「引用第三方包」最典型的样子：声明依赖、
//! `use` 进来、调用它的 API。

pub mod dice;
pub mod password;

// 重新导出常用函数，调用方可以直接 `use rt_44_rand::roll_die;`。
pub use dice::{roll_die, roll_n, sum_n};
pub use password::{CHARSET, generate_password};

//! 掷骰子：用 `rand` 的「范围随机数」模拟一个六面骰。

use rand::Rng;

/// 掷一次六面骰，返回 `1..=6` 之间的点数。
///
/// 关键 API 是 `rng.random_range(1..=6)`：
/// - `rand::rng()` 取得一个线程本地的随机数生成器（RNG）。
/// - `random_range` 接受一个区间，这里 `1..=6` 是「闭区间」，两端都能取到。
///
/// 注意 0.9 版用的是 `rng()` 与 `random_range`；旧教程里的
/// `thread_rng()` / `gen_range` 已被弃用。
pub fn roll_die() -> u8 {
    let mut rng = rand::rng();
    rng.random_range(1..=6)
}

/// 连续掷 `n` 次骰子，把每次点数收集成一个 `Vec<u8>`。
pub fn roll_n(n: usize) -> Vec<u8> {
    (0..n).map(|_| roll_die()).collect()
}

/// 掷 `n` 次骰子并返回点数之和，常用于桌游里的「投掷多颗骰子」。
pub fn sum_n(n: usize) -> u32 {
    roll_n(n).iter().map(|&p| u32::from(p)).sum()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn roll_die_in_range() {
        // 随机值无法断言具体数字，只能断言「性质」：点数始终在 1..=6。
        for _ in 0..1000 {
            let p = roll_die();
            assert!((1..=6).contains(&p), "点数越界: {p}");
        }
    }

    #[test]
    fn roll_n_length_and_range() {
        let rolls = roll_n(50);
        assert_eq!(rolls.len(), 50);
        assert!(rolls.iter().all(|&p| (1..=6).contains(&p)));
    }

    #[test]
    fn sum_n_within_bounds() {
        // 掷 3 颗骰子，和必然落在 3..=18 之间。
        for _ in 0..200 {
            let s = sum_n(3);
            assert!((3..=18).contains(&s), "和越界: {s}");
        }
    }
}

//! 随机密码：从一个字符集里反复随机挑字符，拼成指定长度的密码。

use rand::seq::IndexedRandom;

/// 生成密码时可选用的字符集合（大小写字母 + 数字）。
pub const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ\
                             abcdefghijklmnopqrstuvwxyz\
                             0123456789";

/// 生成一个长度为 `len` 的随机密码。
///
/// 核心 API 是切片的 `.choose(&mut rng)`：它来自 `rand::seq::IndexedRandom`
/// 这个 trait，所以必须先 `use` 它才能调用。`choose` 返回 `Option<&T>`
/// （切片可能为空），这里 `CHARSET` 非空，直接 `expect` 即可。
pub fn generate_password(len: usize) -> String {
    let mut rng = rand::rng();
    (0..len)
        .map(|_| {
            let &byte = CHARSET.choose(&mut rng).expect("字符集不应为空");
            byte as char
        })
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn password_has_expected_length() {
        for len in [0, 1, 8, 32] {
            assert_eq!(generate_password(len).chars().count(), len);
        }
    }

    #[test]
    fn password_uses_only_charset() {
        let pw = generate_password(200);
        assert!(
            pw.bytes().all(|b| CHARSET.contains(&b)),
            "出现了字符集之外的字符: {pw}"
        );
    }
}

[package]
name = "rt_44_rand"
version.workspace = true
edition.workspace = true
publish.workspace = true

[dependencies]
rand = "0.9"