rstime 0.1.0

# rstime

A lightweight, zero-dependency enhanced time library for Rust, built entirely using the standard library. Fills the gaps left by `std::time` with full date, time, formatting, parsing, and clock capabilities.

## Features

- **Zero Dependencies**: Built entirely using Rust's standard library
- **Date Type**: `Date` (year/month/day) with weekday calculation and leap year detection
- **Time Type**: `Time` (hour/minute/second/millisecond) with 12/24-hour support
- **DateTime Type**: Combined `DateTime` with Unix timestamp conversion
- **Duration Types**: `Duration` (positive) and `TimeDelta` (signed) for calculations
- **Formatting**: Custom format strings like `{YYYY}-{MM}-{DD} {HH}:{mm}:{ss}`
- **Parsing**: Parse date/time from strings with format-based and ISO 8601 support
- **Clock**: System clock for real time, monotonic clock for performance measurement
- **Arithmetic**: Full arithmetic support with operator overloading

## Quick Start

Add `rstime` to your `Cargo.toml`:

```toml
[dependencies]
rstime = { path = "../rstime" }
```

### Current Time

```rust
use rstime::{DateTime, Date, Time};

fn main() {
    let now = DateTime::now();
    println!("{}", now);  // 2026-05-10 14:05:09
    println!("Today: {}", Date::today());
    println!("Time: {}", Time::now());
}
```

### Formatting

```rust
use rstime::{DateTime, TimeFormat};

fn main() {
    let dt = DateTime::from_ymd_hms(2026, 5, 10, 14, 5, 9);

    // ISO 8601
    println!("{}", dt.format("{YYYY}-{MM}-{DD}T{HH}:{mm}:{ss}"));
    // → 2026-05-10T14:05:09

    // Chinese format
    println!("{}", dt.format("{YYYY}年{MM}月{DD}日 {HH}:{mm}:{ss}"));
    // → 2026年05月10日 14:05:09

    // 12-hour format
    println!("{}", dt.format("{hh}:{mm} {AMPM}"));
    // → 02:05 PM
}
```

### Date Arithmetic

```rust
use rstime::{DateTime, Duration, TimeDelta};

fn main() {
    let dt = DateTime::from_ymd_hms(2026, 1, 1, 0, 0, 0);

    let next_day = dt + TimeDelta::new(86400, 0);
    println!("Next day: {}", next_day);  // 2026-01-02 00:00:00

    let minus_hour = dt - Duration::HOUR;
    println!("One hour ago: {}", minus_hour);  // 2025-12-31 23:00:00
}
```

### Unix Timestamps

```rust
use rstime::DateTime;

fn main() {
    let dt = DateTime::from_unix(0);
    println!("{}", dt);  // 1970-01-01 00:00:00

    let now = DateTime::now();
    let ts = now.unix_timestamp();
    let ts_ms = now.unix_timestamp_millis();
    let back = DateTime::from_unix_millis(ts_ms);
}
```

### Parsing

```rust
use rstime::parse_iso8601;

fn main() -> Result<(), String> {
    let dt = parse_iso8601("2026-05-10T14:05:09")?;
    let with_ms = parse_iso8601("2026-05-10T14:05:09.037")?;
    Ok(())
}
```

## Format Tokens

| Token | Meaning | Example |
|-------|---------|---------|
| `{YYYY}` | 4-digit year | `2026` |
| `{YY}` | 2-digit year | `26` |
| `{MM}` | 2-digit month | `05` |
| `{DD}` | 2-digit day | `10` |
| `{HH}` | 2-digit 24-hour | `14` |
| `{hh}` | 2-digit 12-hour | `02` |
| `{mm}` | 2-digit minute | `05` |
| `{ss}` | 2-digit second | `09` |
| `{SSS}` | 3-digit millisecond | `037` |
| `{W}` | Abbreviated weekday | `Sun` |
| `{WW}` | Full weekday | `Sunday` |
| `{AMPM}` | AM/PM uppercase | `PM` |
| `{ampm}` | am/pm lowercase | `pm` |

## Clock

```rust
use rstime::{SystemClock, MonotonicClock};

fn main() {
    // System clock for real time
    let clock = SystemClock;
    let now = clock.now();

    // Monotonic clock for performance measurement
    let timer = MonotonicClock::start();
    // ... do work ...
    let elapsed = timer.elapsed();
    println!("Elapsed: {}ms", elapsed.total_millis());
}
```

## Documentation

Generate documentation:

```bash
cargo doc --open
```

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## 中文文档

中文文档请查看 [rs-docs](https://github.com/Cnkrru/rust-package/tree/main/rs-docs)