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:

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

Current Time

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

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

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

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

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

Clock

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:

cargo doc --open

License

MIT License

Contributing

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

中文文档

中文文档请查看 rs-docs