Struct Time 

pub struct Time {
    pub hour: u8,
    pub minute: u8,
    pub second: u8,
    pub millisecond: u16,
}

A time of day with millisecond precision

Supports validation, 12-hour conversion, and arithmetic with Duration (with cross-midnight wrapping).

Examples

use rstime::Time;

let t = Time::new(14, 5, 9, 37);
assert!(t.is_valid());
assert_eq!(t.hour, 14);
assert_eq!(t.minute, 5);
assert_eq!(t.second, 9);
assert_eq!(t.millisecond, 37);

Fields

hour: u8

Hour (0-23)

minute: u8

Minute (0-59)

second: u8

Second (0-59)

millisecond: u16

Millisecond (0-999)

Implementations

impl Time

pub fn now() -> Self

Convenience method: current time from the system clock

Examples found in repository

examples/test_clock.rs (line 16)

fn main() {
    println!("=== rstime 时钟测试 ===\n");

    println!("1. 系统时钟 - 当前时间");
    let clock = SystemClock;
    let now = clock.now();
    println!("   DateTime: {}", now);
    println!("   Date:     {}", clock.today());
    println!("   Time:     {}", clock.time_now());
    println!();

    println!("2. 便捷方法（无需实例化 Clock）");
    let today = rstime::Date::today();
    let time_now = rstime::Time::now();
    let datetime_now = rstime::DateTime::now();
    println!("   Date::today()     → {}", today);
    println!("   Time::now()       → {}", time_now);
    println!("   DateTime::now()   → {}", datetime_now);
    println!();

    println!("3. 单调时钟 - 性能计时");
    let timer = MonotonicClock::start();
    let mut _sum: u64 = 0;
    for i in 0..1_000_000 {
        _sum += i;
    }
    let elapsed = timer.elapsed();
    println!("   累加 100 万次: {}ms ({} 纳秒)", elapsed.total_millis(), elapsed.nanos);
    println!();

    println!("4. 单调时钟 - 重置");
    let mut timer = MonotonicClock::start();
    std::thread::sleep(std::time::Duration::from_millis(10));
    println!("   第一次: {}ms", timer.elapsed().total_millis());
    timer.reset();
    println!("   重置后: {}ms", timer.elapsed().total_millis());
    println!();

    println!("5. Duration 常量");
    println!("   ZERO:   {}ms", Duration::ZERO.total_millis());
    println!("   SECOND: {}ms", Duration::SECOND.total_millis());
    println!("   MINUTE: {}ms", Duration::MINUTE.total_millis());
    println!("   HOUR:   {}ms", Duration::HOUR.total_millis());
    println!("   DAY:    {}ms", Duration::DAY.total_millis());
    println!();

    println!("✅ 时钟测试完成！");
}

examples/demo.rs (line 57)

fn main() {
    println!("=== rstime 时间库使用示例 ===\n");

    println!("1. 获取当前时间");
    let now = DateTime::now();
    println!("   现在: {}\n", now);

    println!("2. 格式化输出");
    let dt = DateTime::from_ymd_hms_milli(2026, 5, 10, 14, 5, 9, 37);
    println!("   ISO 8601:  {}", dt.format("{YYYY}-{MM}-{DD}T{HH}:{mm}:{ss}"));
    println!("   中文格式:  {}", dt.format("{YYYY}年{MM}月{DD}日 {HH}:{mm}:{ss}"));
    println!("   12小时制:  {}", dt.format("{hh}:{mm}:{ss} {AMPM}"));
    println!("   星期:      {}", dt.format("{WW}"));
    println!("   毫秒:      {}", dt.format("{SSS}"));
    println!();

    println!("3. 日期计算");
    let d1 = Date::new(2026, 1, 1);
    let d2 = d1 + TimeDelta::new(365 * 86400, 0);
    let diff = d2 - d1;
    println!("   {} + 365 天 = {}", d1, d2);
    println!("   相差 {} 天", diff.total_seconds() as i64 / 86400);
    println!();

    println!("4. 星期计算");
    let dates = [Date::new(2026, 1, 1), Date::new(2026, 5, 10), Date::new(2026, 12, 25)];
    for d in &dates {
        println!("   {} = {}", d, d.weekday());
    }
    println!();

    println!("5. 闰年判断");
    for year in [2024, 2025, 2000, 1900] {
        println!("   {}: {}", year, if Date::new(year, 1, 1).is_leap_year() { "闰年" } else { "平年" });
    }
    println!();

    println!("6. Unix 时间戳");
    let epoch = DateTime::from_unix(0);
    println!("   epoch:     {}", epoch);
    let ts = now.unix_timestamp();
    println!("   当前时间戳: {}", ts);
    let ts_ms = now.unix_timestamp_millis();
    println!("   毫秒时间戳: {}", ts_ms);
    println!();

    println!("7. 时间加法（跨天回绕）");
    let t = Time::from_hms(23, 30, 0);
    println!("   {} + 2h = {}", t, t + Duration::from_secs(7200));
    println!("   {} - 1h = {}", t, t - Duration::HOUR);
    println!();

    println!("8. 时钟功能");
    let today = Date::today();
    let time_now = Time::now();
    println!("   今天: {}", today);
    println!("   此刻: {}", time_now);
    println!();

    println!("9. 单调时钟（性能计时）");
    let timer = MonotonicClock::start();
    let _sum: u64 = (0..10_000_000).sum();
    let elapsed = timer.elapsed();
    println!("   累加 1000 万次耗时: {}ms", elapsed.total_millis());
    println!();

    println!("✅ 所有示例运行完成！");
}

impl Time

pub const MIDNIGHT: Time

Midnight (00:00:00.000)

pub const NOON: Time

Noon (12:00:00.000)

pub const MAX: Time

Maximum time (23:59:59.999)

pub fn new(hour: u8, minute: u8, second: u8, millisecond: u16) -> Self

Create a new time with millisecond precision

Examples found in repository

examples/test_format.rs (line 8)

fn main() {
    println!("=== rstime 格式化测试 ===\n");

    let dt = DateTime::from_ymd_hms_milli(2026, 5, 10, 14, 5, 9, 37);
    let d = Date::new(2026, 5, 10);
    let t = Time::new(14, 5, 9, 37);

    println!("DateTime 格式化:");
    println!("  YYYY-MM-DD HH:mm:ss    → {}", dt.format("{YYYY}-{MM}-{DD} {HH}:{mm}:{ss}"));
    println!("  YYYY/MM/DD             → {}", dt.format("{YYYY}/{MM}/{DD}"));
    println!("  YY-M-D                  → {}", dt.format("{YY}-{M}-{D}"));
    println!("  12h                     → {}", dt.format("{hh}:{mm} {AMPM}"));
    println!("  12h lowercase           → {}", dt.format("{h}:{m} {ampm}"));
    println!("  With millis             → {}", dt.format("{HH}:{mm}:{ss}.{SSS}"));
    println!("  Weekday short           → {}", dt.format("{W}"));
    println!("  Weekday full            → {}", dt.format("{WW}"));
    println!("  Literal text            → {}", dt.format("Today is {YYYY}-{MM}-{DD}!"));
    println!();

    println!("Date 格式化:");
    println!("  YYYY-MM-DD              → {}", d.format("{YYYY}-{MM}-{DD}"));
    println!("  Chinese date            → {}", d.format("{YYYY}年{MM}月{DD}日"));
    println!("  Year only               → {}", d.format("{YYYY}"));
    println!();

    println!("Time 格式化:");
    println!("  HH:mm:ss                → {}", t.format("{HH}:{mm}:{ss}"));
    println!("  12h with AM/PM          → {}", t.format("{hh}:{mm} {AMPM}"));
    println!("  With millis             → {}", t.format("{HH}:{mm}:{ss}.{SSS}"));
    println!();

    println!("预置格式:");
    println!("  ISO8601:      {}", dt.format("{YYYY}-{MM}-{DD}T{HH}:{mm}:{ss}"));
    println!("  RFC2822-ish:  {}", dt.format("{W}, {DD} {MM} {YYYY} {HH}:{mm}:{ss}"));
    println!();

    println!("边界值测试:");
    let midnight = Time::MIDNIGHT;
    let noon = Time::NOON;
    let max = Time::MAX;
    println!("  Midnight  → {}", midnight.format("{HH}:{mm}:{ss} {AMPM}"));
    println!("  Noon      → {}", noon.format("{HH}:{mm}:{ss} {AMPM}"));
    println!("  Max       → {}", max.format("{HH}:{mm}:{ss}.{SSS}"));
    println!();

    println!("✅ 格式化测试完成！");
}

pub fn from_hms(hour: u8, minute: u8, second: u8) -> Self

Create a time from hours, minutes, and seconds (no milliseconds)

Examples found in repository

examples/demo.rs (line 50)

fn main() {
    println!("=== rstime 时间库使用示例 ===\n");

    println!("1. 获取当前时间");
    let now = DateTime::now();
    println!("   现在: {}\n", now);

    println!("2. 格式化输出");
    let dt = DateTime::from_ymd_hms_milli(2026, 5, 10, 14, 5, 9, 37);
    println!("   ISO 8601:  {}", dt.format("{YYYY}-{MM}-{DD}T{HH}:{mm}:{ss}"));
    println!("   中文格式:  {}", dt.format("{YYYY}年{MM}月{DD}日 {HH}:{mm}:{ss}"));
    println!("   12小时制:  {}", dt.format("{hh}:{mm}:{ss} {AMPM}"));
    println!("   星期:      {}", dt.format("{WW}"));
    println!("   毫秒:      {}", dt.format("{SSS}"));
    println!();

    println!("3. 日期计算");
    let d1 = Date::new(2026, 1, 1);
    let d2 = d1 + TimeDelta::new(365 * 86400, 0);
    let diff = d2 - d1;
    println!("   {} + 365 天 = {}", d1, d2);
    println!("   相差 {} 天", diff.total_seconds() as i64 / 86400);
    println!();

    println!("4. 星期计算");
    let dates = [Date::new(2026, 1, 1), Date::new(2026, 5, 10), Date::new(2026, 12, 25)];
    for d in &dates {
        println!("   {} = {}", d, d.weekday());
    }
    println!();

    println!("5. 闰年判断");
    for year in [2024, 2025, 2000, 1900] {
        println!("   {}: {}", year, if Date::new(year, 1, 1).is_leap_year() { "闰年" } else { "平年" });
    }
    println!();

    println!("6. Unix 时间戳");
    let epoch = DateTime::from_unix(0);
    println!("   epoch:     {}", epoch);
    let ts = now.unix_timestamp();
    println!("   当前时间戳: {}", ts);
    let ts_ms = now.unix_timestamp_millis();
    println!("   毫秒时间戳: {}", ts_ms);
    println!();

    println!("7. 时间加法（跨天回绕）");
    let t = Time::from_hms(23, 30, 0);
    println!("   {} + 2h = {}", t, t + Duration::from_secs(7200));
    println!("   {} - 1h = {}", t, t - Duration::HOUR);
    println!();

    println!("8. 时钟功能");
    let today = Date::today();
    let time_now = Time::now();
    println!("   今天: {}", today);
    println!("   此刻: {}", time_now);
    println!();

    println!("9. 单调时钟（性能计时）");
    let timer = MonotonicClock::start();
    let _sum: u64 = (0..10_000_000).sum();
    let elapsed = timer.elapsed();
    println!("   累加 1000 万次耗时: {}ms", elapsed.total_millis());
    println!();

    println!("✅ 所有示例运行完成！");
}

pub fn is_valid(&self) -> bool

Check if the time is valid

use rstime::Time;

assert!(Time::new(14, 5, 9, 0).is_valid());
assert!(!Time::new(24, 0, 0, 0).is_valid());
assert!(!Time::new(0, 60, 0, 0).is_valid());

pub fn total_seconds(&self) -> u32

Total time in seconds (since midnight)

pub fn total_millis(&self) -> u32

Total time in milliseconds (since midnight)

pub fn hour12(&self) -> (u8, bool)

Convert to 12-hour clock representation

Returns (hour, is_pm) where hour is 1-12.

use rstime::Time;

let t = Time::from_hms(14, 0, 0);
assert_eq!(t.hour12(), (2, true));

let midnight = Time::MIDNIGHT;
assert_eq!(midnight.hour12(), (12, false));

pub fn is_pm(&self) -> bool

Returns true if the time is PM (hour >= 12)

Trait Implementations

impl Add<Duration> for Time

fn add(self, delta: Duration) -> Time

Add a duration, wrapping around midnight

use rstime::{Time, Duration};

let t = Time::from_hms(23, 0, 0);
let t2 = t + Duration::HOUR * 2;

type Output = Time

The resulting type after applying the + operator.

impl Clone for Time

fn clone(&self) -> Time

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Time

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Time

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for Time

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Time

fn cmp(&self, other: &Time) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Time

fn eq(&self, other: &Time) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Time

fn partial_cmp(&self, other: &Time) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Sub<Duration> for Time

fn sub(self, delta: Duration) -> Time

Subtract a duration, wrapping around midnight

type Output = Time

The resulting type after applying the - operator.

impl Sub for Time

fn sub(self, rhs: Time) -> Duration

Calculate the difference between two times

type Output = Duration

The resulting type after applying the - operator.

impl TimeFormat for Time

fn format(&self, fmt: &str) -> String

Format the value using the given format string

impl Copy for Time

impl Eq for Time

impl StructuralPartialEq for Time