librarys 0.1.1

# API 使用指南


详细的API使用指南和示例代码。

## 特性配置


在使用本库之前，需要在 `Cargo.toml` 中配置所需的特性：

```toml
[dependencies]
librarys = { version = "0.1.1", features = ["default"] }

# 或者选择特定功能

librarys = { version = "0.1.1", features = ["datetime", "crypto", "data"] }

# 或者使用全部功能

librarys = { version = "0.1.1", features = ["full"] }
```

### 可用特性


- `default`: 核心功能 (字符串、日期时间、验证)
- `crypto`: 基础加密功能 (哈希算法)
- `crypto-full`: 完整加密功能 (哈希 + AES/DES/RSA)
- `data`: 数据处理 (JSON/XML)
- `random`: 随机生成功能
- `io`: 文件操作功能
- `network`: 网络功能
- `full`: 所有功能

## 测试指南


### 正确的测试方式


⚠️ **重要**: 不要直接运行 `cargo test`，这会导致特性不匹配错误。

```bash
# 正确的测试方式

cargo test --lib --features default
cargo test --doc --features default

# 测试特定特性

cargo test --lib --features "default,crypto"
cargo test --lib --features "default,data"

# 测试全部功能

cargo test --lib --features full
cargo test --doc --features full
```

## 模块使用指南


### 1. 核心模块 (core)


#### 字符串工具 (string_utils)


```rust
use librarys::core::string_utils;

// 字符串判断
assert_eq!(string_utils::is_empty(""), true);
assert_eq!(string_utils::is_not_empty("hello"), true);
assert_eq!(string_utils::is_chinese_char('你'), true);

// 类型转换
assert_eq!(string_utils::to_int("123"), 123);
assert_eq!(string_utils::to_double("3.14"), 3.14);
assert_eq!(string_utils::to_boolean("true"), true);

// 大小写转换
assert_eq!(string_utils::to_uppercase_first("hello"), "Hello");
assert_eq!(string_utils::to_lowercase_first("WORLD"), "wORLD");

// 命名风格转换
assert_eq!(string_utils::camel_case_to_underscore("userName"), "user_name");
assert_eq!(string_utils::underscore_to_camel_case("user_name"), "userName");
```

#### 数据验证 (validation)


```rust
use librarys::core::validation;

// 基本验证
assert!(validation::is_email("test@example.com"));
assert!(validation::is_phone("13812345678"));
assert!(validation::is_url("https://www.example.com"));

// 数字验证
assert!(validation::is_integer("123"));
assert!(validation::is_float("3.14"));
assert!(validation::is_positive_integer("42"));

// 中文验证
assert!(validation::is_chinese("你好世界"));
assert!(validation::is_real_name("张三"));

// 敏感信息掩码
assert_eq!(validation::mask_phone("13812345678"), "138****5678");
assert_eq!(validation::mask_id_card("123456789012345678"), "1234**********5678");
```

### 2. 日期时间模块 (datetime)


```rust
use librarys::datetime::{date_utils, time_utils, format};
use chrono::Local;

// 时间获取
let timestamp = date_utils::current_timestamp();
let hour = time_utils::current_hour();
let minute = time_utils::current_minute();

// 日期判断
assert!(date_utils::is_leap_year(2024));
assert_eq!(date_utils::days_of_month(2024, 2), 29);

// 生肖星座
assert_eq!(date_utils::get_chinese_zodiac(2024), "龙");
assert_eq!(date_utils::get_zodiac(3, 15), "双鱼座");

// 日期格式化
let now = Local::now();
let formatted = format::format_datetime(&now, "%Y-%m-%d %H:%M:%S");
```

### 3. 文件操作模块 (io)


```rust
use librarys::io::file_utils;
use std::path::Path;

// 文件操作
let content = file_utils::read_file_to_string(Path::new("test.txt"))?;
file_utils::write_string_to_file(Path::new("output.txt"), "Hello", false)?;

// 文件信息
let exists = file_utils::file_exists(Path::new("test.txt"));
let size = file_utils::get_file_size(Path::new("test.txt"))?;
let formatted_size = file_utils::format_file_size(1024); // "1.0 KB"

// Base64编码
let base64_str = file_utils::string_to_base64("hello world");
let decoded = file_utils::base64_to_string(&base64_str)?;

// 文件名处理
let filename = file_utils::get_filename("/path/to/file.txt"); // "file.txt"
let extension = file_utils::get_file_extension("file.txt"); // Some("txt")
```

### 4. 加密模块 (crypto)


```rust
use librarys::crypto::{hash, symmetric};

// 哈希算法
let md5 = hash::md5_hash("hello world");
let sha1 = hash::sha1_hash("hello world");
let sha256 = hash::sha256_hash("hello world");

// HMAC签名
let signature = hash::hmac_sha256("data", "secret_key")?;

// AES加密（简化版）
let key = b"1234567890123456"; // 16字节密钥
let plaintext = "hello world";
let encrypted = symmetric::aes_encrypt(plaintext, key)?;
let decrypted = symmetric::aes_decrypt(&encrypted, key)?;
```

### 5. 数据处理模块 (data)


```rust
use librarys::data::json_utils;
use serde_json::json;

// JSON处理
let json_str = r#"{"name":"张三","age":30}"#;
let pretty = json_utils::prettify_json(json_str)?;
let minified = json_utils::minify_json(json_str)?;

// JSON值操作
let json_obj = json!({"name": "张三", "age": 30});
let name = json_utils::get_string(&json_obj, "name"); // Some("张三")
let age = json_utils::get_i64(&json_obj, "age"); // Some(30)

// JSON验证
assert!(json_utils::is_valid_json(json_str));
```

### 6. 随机数模块 (random)


```rust
use librarys::random::{generators, uuid};

// 随机字符串
let random_nums = generators::random_numbers(8);
let random_letters = generators::random_letters(10);
let random_hex = generators::random_hex_string(16);

// 随机数字
let random_int = generators::random_int(100); // 0-100
let random_range = generators::random_int_range(10, 50); // 10-50
let random_bool = generators::random_bool();

// UUID生成
let uuid_simple = uuid::generate_uuid(); // 简单格式
let uuid_standard = uuid::generate_uuid_standard(); // 标准格式

// 特殊随机
let chinese_char = generators::random_chinese_char();
let password = generators::random_password(12);
```

### 7. 网络模块 (network)


```rust
use librarys::network::url_utils;

// URL处理
let url = url_utils::parse_url("https://www.example.com/path?query=value")?;
let domain = url_utils::get_domain("https://www.example.com/path")?; // "www.example.com"

// URL编码解码
let encoded = url_utils::url_encode("hello world"); // "hello%20world"
let decoded = url_utils::url_decode("hello%20world")?; // "hello world"
```

### 8. 系统模块 (system)


```rust
use librarys::system::{device_info, process_utils};

// 设备信息
let cpu_count = device_info::get_cpu_count();
let arch = device_info::get_arch(); // "x86_64"
let os = device_info::get_os(); // "windows"

// 进程操作
let output = process_utils::execute_command("echo", &["hello"])?;
let child = process_utils::start_background_process("notepad", &[])?;
```

## 错误处理


所有可能失败的函数都返回`Result<T, E>`类型：

```rust
use librarys::Result;

fn example() -> Result<()> {
    let content = file_utils::read_file_to_string("nonexistent.txt")?;
    println!("{}", content);
    Ok(())
}

// 或者使用模式匹配
match file_utils::read_file_to_string("test.txt") {
    Ok(content) => println!("文件内容: {}", content),
    Err(e) => eprintln!("读取文件失败: {}", e),
}
```

## 向后兼容性


为了保持向后兼容，库还提供了扁平化的模块导入：

```rust
// 新的模块化方式
use librarys::core::string_utils;
use librarys::datetime::date_utils;

// 向后兼容的方式
use librarys::{string_utils, date_utils};

// 两种方式都可以使用
```

## 性能提示


1. **字符串操作**: 对于大量字符串操作，考虑使用`String::with_capacity()`预分配容量
2. **文件操作**: 对于大文件，使用流式读取而不是一次性读取全部内容
3. **正则表达式**: 频繁使用的正则表达式会被自动缓存
4. **随机数**: 内部使用线程安全的随机数生成器，性能优异

## 线程安全


所有公共API都是线程安全的，可以在多线程环境中安全使用：

```rust
use std::thread;
use librarys::random::generators;

let handles: Vec<_> = (0..4)
    .map(|_| {
        thread::spawn(|| {
            for _ in 0..1000 {
                let _random = generators::random_letters(10);
            }
        })
    })
    .collect();

for handle in handles {
    handle.join().unwrap();
}
```