Time Management in Rust

Managing time is a fundamental aspect of many applications, from measuring performance to scheduling events and timestamping data. In Rust, the standard library provides basic functionalities for time handling through the `std::time` module. For more advanced use cases, external crates offer comprehensive solutions.

`std::time::Instant`
`Instant` represents a point in time measured by a monotonic clock. This means it's suitable for measuring elapsed time between two points, as it's guaranteed to move forward and is not affected by system clock changes (e.g., if a user manually changes the system time or if NTP synchronizes it). It's ideal for benchmarking, performance measurements, and situations where you need to track a duration accurately.

- Characteristics: Monotonic, non-decreasing, not tied to wall-clock time.
- Use Cases: Benchmarking code execution, implementing timeouts, measuring operation durations.

`std::time::SystemTime`
`SystemTime` represents the system's wall-clock time, typically Coordinated Universal Time (UTC). It's useful for obtaining the current date and time, creating timestamps, or interacting with external systems that rely on calendar dates. Unlike `Instant`, `SystemTime` can go backward if the system clock is adjusted (e.g., by NTP synchronization or manual changes).

- Characteristics: Wall-clock time, can be affected by system clock changes, tied to a specific date and time (e.g., UNIX epoch).
- Use Cases: Generating timestamps for logs, file modification times, displaying current date/time to users.

`std::time::Duration`
`Duration` represents a span of time, such as "5 seconds" or "300 milliseconds". It's used in conjunction with both `Instant` and `SystemTime` to represent differences between time points. `Duration` can be created from various units (seconds, milliseconds, nanoseconds) and supports arithmetic operations like addition, subtraction, multiplication, and division.

- Characteristics: Represents a time interval, independent of any specific time point.
- Use Cases: Defining timeouts, specifying delays, calculating time differences.

External Crates
While `std::time` provides fundamental building blocks, it lacks features like time zones, date parsing from strings, and complex calendar manipulations. For such advanced needs, the Rust ecosystem offers powerful external crates:

- `chrono`: A popular and feature-rich library for date and time handling, including time zones, parsing, formatting, and calendar calculations.
- `time`: Another robust date and time library that focuses on correctness and offers a modern API for comprehensive time management.

use std::time::{Instant, SystemTime, Duration};
use std::thread; // Used for simulating work with thread::sleep
use std::error::Error; // Used for convenient error handling in main

fn main() -> Result<(), Box<dyn Error>> {
    println!("--- std::time::Instant Example ---");
    // Instant: For measuring elapsed time. It's monotonic and not affected by system clock changes.
    let start_instant = Instant::now();
    println!("Starting a simulated task...");
    
    // Simulate some work that takes 2 seconds
    thread::sleep(Duration::from_secs(2)); 
    
    let end_instant = Instant::now();
    let elapsed_instant = end_instant.duration_since(start_instant);
    println!("Task finished. Elapsed time: {:?}", elapsed_instant);
    println!("Elapsed seconds (float): {}", elapsed_instant.as_secs_f64());

    println!("\n--- std::time::SystemTime Example ---");
    // SystemTime: For wall-clock time, useful for timestamps. Can go backwards.
    let now_system = SystemTime::now();
    println!("Current system time: {:?}", now_system);

    // Get time since UNIX_EPOCH (January 1, 1970, 00:00:00 UTC)
    // This can fail if the system time is set before the epoch, hence the `?` operator.
    let since_epoch = now_system.duration_since(SystemTime::UNIX_EPOCH)?;
    println!("Seconds since UNIX EPOCH: {}", since_epoch.as_secs());

    // You can also create a SystemTime by adding a duration to the epoch
    // Example: March 15, 2023 12:00:00 PM UTC corresponds to 1678886400 seconds since epoch
    let custom_time_epoch = SystemTime::UNIX_EPOCH + Duration::from_secs(1678886400);
    println!("Custom SystemTime (March 15, 2023, 12:00 UTC): {:?}", custom_time_epoch);

    println!("\n--- std::time::Duration Example ---");
    // Duration: Represents a span of time.
    let one_second = Duration::new(1, 0); // 1 second, 0 nanoseconds
    let ten_millis = Duration::from_millis(10);
    let one_micro = Duration::from_micros(1);
    let fifty_nanos = Duration::from_nanos(50);

    println!("One second: {:?}", one_second);
    println!("Ten milliseconds: {:?}", ten_millis);
    println!("One microsecond: {:?}", one_micro);
    println!("Fifty nanoseconds: {:?}", fifty_nanos);

    // Duration arithmetic
    let total_duration = one_second + ten_millis;
    println!("One second + ten milliseconds: {:?}", total_duration);

    let half_second = one_second / 2;
    println!("Half a second: {:?}", half_second);

    let tripled_duration = ten_millis * 3;
    println!("Ten milliseconds * 3: {:?}", tripled_duration);

    Ok(())
}