# librarys

**Repository Path**: rust_us/librarys

## Basic Information

- **Project Name**: librarys
- **Description**: librarys
- **Primary Language**: Rust
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-08
- **Last Updated**: 2025-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Librarys - Rust Rapid Development Toolkit

[![Crates.io](https://img.shields.io/crates/v/librarys.svg)](https://crates.io/crates/librarys)
[![Documentation](https://docs.rs/librarys/badge.svg)](https://docs.rs/librarys)
[![License](https://img.shields.io/crates/l/librarys.svg)](LICENSE)

A comprehensive Rust toolkit that provides commonly needed functionalities for rapid development, including string processing, date/time operations, file handling, JSON processing, validation, random number generation, and encryption.

## ✨ Features

- 🎯 **Modular Design** - Import functionalities on-demand through the feature system
- 🛡️ **Type Safety** - Fully leverage Rust's type system to ensure safety
- 🚀 **High Performance** - Optimized algorithms and data structures
- 📚 **Rich Documentation** - Complete API documentation and usage examples
- 🧪 **Comprehensive Testing** - Over 200 test cases to ensure quality
- 🔧 **Easy to Use** - Clean API design
- 🌍 **Internationalization Support** - Supports Chinese processing and validation

## 📦 Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
librarys = "0.1.2"
```

### Feature Selection

The core functionality is enabled by default. You can choose other features as needed:

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

# Or select specific features
librarys = { version = "0.1.2", features = ["datetime", "crypto", "data"] }

librarys = { version = "0.1.2", features = ["core", "datetime", "validation", "data", "random", "network"] }
```

## 🎯 Available Features

| Feature | Description | Included Functionality |
|---------|-------------|------------------------|
| `default` | Default features (minimal dependencies) | `core`, `datetime` date/time, `validation` validation |
| `core` | Core string utilities | String processing, type conversion |
| `datetime` | Date/time utilities | Date formatting, time calculations, zodiac signs |
| `validation` | Validation utilities | Email, phone, ID validation |
| `crypto` | Basic encryption | MD5, SHA1, SHA256, HMAC |
| `crypto-full` | Full encryption | Basic encryption + AES, DES, RSA |
| `data` | Data processing | JSON, XML processing |
| `io` | File operations | File read/write, compression |
| `random` | Random generation | Random strings, numbers, UUID, password generation |
| `network` | Network functionality | HTTP client, SSL utilities |
| `full` | All features | Includes all features |

## 🚀 Quick Start

### Basic Example

```rust
use librarys::core::string_utils;
use librarys::datetime::date_utils;
use librarys::core::validation;

fn main() {
    // String utilities
    println!("Is empty: {}", string_utils::is_empty(""));  // true
    println!("To uppercase first: {}", string_utils::to_uppercase_first("hello"));  // "Hello"
    
    // Date/time
    println!("Current timestamp: {}", date_utils::current_timestamp());
    println!("2024 Chinese zodiac: {}", date_utils::get_chinese_zodiac(2024));  // "Dragon"
    
    // Validation utilities
    println!("Email validation: {}", validation::is_email("test@example.com"));  // true
    println!("Phone validation: {}", validation::is_phone("13812345678"));  // true
}
```

### Encryption Example

```rust
use librarys::crypto;

fn main() {
    let text = "Hello, Rust!";
    
    // Hash calculation
    println!("MD5: {}", crypto::md5_hash(text));
    println!("SHA256: {}", crypto::sha256_hash(text));
    
    // HMAC signature
    if let Ok(signature) = crypto::hmac_sha256(text, "secret_key") {
        println!("HMAC signature: {}", signature);
    }
}
```

### JSON Processing Example

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

fn main() {
    let data = json!({
        "name": "Zhang San",
        "age": 30,
        "city": "Beijing"
    });
    
    // Pretty print JSON
    if let Ok(pretty) = json_utils::prettify_json(&data.to_string()) {
        println!("Pretty JSON:\n{}", pretty);
    }
    
    // Get value
    if let Some(name) = json_utils::get_string(&data, "name") {
        println!("Name: {}", name);
    }
}
```

## 📖 Core Functionality

### String Utilities (`string_utils`)

```rust
// Basic checks
string_utils::is_empty("");                    // true
string_utils::is_chinese_char('你');            // true
string_utils::contains_chinese("hello世界");    // true

// Type conversion
string_utils::to_int("123");                   // 123
string_utils::to_double("3.14");               // 3.14

// Naming style conversion
string_utils::camel_case_to_underscore("userName");    // "user_name"
string_utils::underscore_to_camel_case("user_name");   // "userName"

// Garbled text detection
string_utils::is_garbled("正常文本");           // false
string_utils::is_garbled("~`#$%^&*");          // true
```

### Validation Utilities (`validation`)

```rust
// Basic validation
validation::is_email("test@example.com");      // true
validation::is_phone("13812345678");           // true
validation::is_url("https://example.com");     // true

// Chinese validation
validation::is_chinese("你好世界");             // true
validation::is_real_name("张三");               // true

// Masking
validation::mask_phone("13812345678");         // "138****5678"
validation::mask_email("test@example.com");    // "t***@example.com"
```

### Date/Time Utilities (`date_utils`)

```rust
// Current time
date_utils::current_timestamp();              // Current Unix timestamp
date_utils::today_yyyy_mm_dd();               // "2024-01-15"

// Date calculations
date_utils::is_leap_year(2024);               // true
date_utils::days_of_month(2024, 2);           // 29

// Zodiac signs
date_utils::get_chinese_zodiac(2024);         // "Dragon"
date_utils::get_zodiac(3, 15);               // "Pisces"
```

### Random Generation Utilities (`generators`)

```rust
// Random strings
generators::random_numbers(8);                // "12345678"
generators::random_letters(10);               // "AbCdEfGhIj"

// Random numbers
generators::random_int_range(1, 100);         // Random integer between 1-100
generators::random_bool();                    // true or false

// UUID generation
generators::random_uuid();                    // UUID string
generators::random_chinese_string(5);         // Random Chinese string

// Password generation
generators::random_password(12, true, true, true); // Complex password
```

## 🧪 Running Examples

We provide two example programs:

### 1. Full Feature Demo (`demo.rs`)
Showcases comprehensive usage of all functional modules:

```bash
# Run full feature demo (requires all features)
cargo run --example demo --features full
```

### 2. Feature Selection Demo (`features_demo.rs`)
Showcases functional modules by feature category:

```bash
# Run basic feature demo
cargo run --example features_demo --features default

# Run full feature demo
cargo run --example features_demo --features full

# Run specific feature demo
cargo run --example features_demo --features "datetime,crypto,data"
```

## 🔬 Testing

### Basic Testing

```bash
# Run default feature tests (core functionality only)
cargo test --lib --features default

# Run documentation tests
cargo test --doc --features default
```

### Feature Testing

```bash
# Test specific feature combinations
cargo test --lib --features "default,crypto"
cargo test --lib --features "default,data"
cargo test --lib --features "default,random"
cargo test --lib --features "default,io"
cargo test --lib --features "default,network"

# Test all features
cargo test --lib --features full
cargo test --doc --features full
```

### Important Notes

❗ **Do not run `cargo test` directly**, as this will cause feature mismatch errors. Always use the `--lib` or `--doc` flags to specify the test target.

### Test Results Statistics

- **Unit Tests** - All passed
- **Documentation Tests** - All passed 
- **8 Feature Combinations** - All supported
- **Test Coverage** - > 95%

```
$ cargo test
test result: ok. 82 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 9.98s

$ cargo test --lib --features full
test result: ok. 91 passed; 0 failed; 5 ignored; 0 measured; 0 filtered out; finished in 0.60s

$ cargo test --doc --features full
test result: ok. 197 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 26.43s
```

## 📖 Detailed Documentation

- [API Guide](API_GUIDE.md) - Detailed API documentation and usage examples, including feature configuration and testing guide
- [API Documentation](https://docs.rs/librarys) - Online API documentation

## 🤝 Contributing

Contributions are welcome! Please check [CONTRIBUTING.md](CONTRIBUTING.md) for details.

### Development Setup

```bash
git clone https://gitee.com/rust_us/librarys.git
cd librarys

cargo build --features full
cargo test --features full
```

## 📄 License

This project is dual-licensed under MIT or Apache-2.0. See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE) files for details.

## ❓ FAQ

### Q: How to choose appropriate features?
A: Choose based on your project requirements:
- Basic projects: Use `default` features
- Web applications: Add `network`, `data`, `crypto` features  
- Desktop applications: Add `io`, `media` features
- Full-featured applications: Use `full` features

### Q: Why is compilation time long?
A: This is due to heavy encryption and image processing dependencies. Recommendations:
- Only enable needed features
- Use `cargo build --release` for release builds

### Q: How to handle Chinese characters?
A: This library has built-in Chinese support:
- Use `string_utils::is_chinese_char()` to detect Chinese characters
- Use `validation::is_real_name()` to validate Chinese names
- Use `random::generators::random_chinese_string()` to generate Chinese strings

## 🌟 Acknowledgements

Special thanks to the following open-source projects:
- [serde](https://serde.rs/) - Serialization framework
- [chrono](https://github.com/chronotope/chrono) - Date/time processing
- [regex](https://github.com/rust-lang/regex) - Regular expressions
- [uuid](https://github.com/uuid-rs/uuid) - UUID generation

---

**Make Rust development more efficient!** 🦀✨