Arc<Mutex>

Guides

Rust walkthroughs

ā† Back to all guides

How does chrono::Duration differ from std::time::Duration and when would you use each?

std::time::Duration is the standard library's duration type focused on positive time spans for system timing operations, while chrono::Duration is a more feature-rich duration type from the chrono crate that supports negative durations, larger time ranges, and richer arithmetic operations. std::time::Duration integrates with async runtimes and system APIs, whereas chrono::Duration integrates with chrono's date/time types for calendar calculations. The choice depends on whether you need simple timing or date/time arithmetic.

Basic Creation and Representation

use std::time::Duration as StdDuration;
use chrono::Duration as ChronoDuration;
 
fn creation_comparison() {
    // std::time::Duration - only positive durations
    let std_dur = StdDuration::new(5, 500_000_000);  // 5.5 seconds
    let std_dur2 = StdDuration::from_secs(10);
    let std_dur3 = StdDuration::from_millis(1500);
    let std_dur4 = StdDuration::from_secs_f64(2.5);
    
    // chrono::Duration - supports negative durations
    let chrono_dur = ChronoDuration::seconds(5);
    let chrono_dur2 = ChronoDuration::milliseconds(1500);
    let chrono_dur3 = ChronoDuration::nanoseconds(500_000_000);
    let chrono_dur4 = ChronoDuration::seconds(-5);  // Negative!
    
    println!("std: {:?}", std_dur);        // 5.5s
    println!("chrono: {:?}", chrono_dur);  // PT5S (ISO 8601 format)
}

std::time::Duration represents only non-negative time spans; chrono::Duration can be negative.

Negative Duration Support

use std::time::Duration as StdDuration;
use chrono::Duration as ChronoDuration;
 
fn negative_durations() {
    // std::time::Duration cannot represent negative values
    // This would panic:
    // let negative = StdDuration::new(-1, 0);  // panic!
    
    // chrono::Duration handles negative durations naturally
    let negative = ChronoDuration::seconds(-5);
    println!("Negative: {:?}", negative);  // -PT5S
    
    let also_negative = -ChronoDuration::hours(2);
    println!("Also negative: {:?}", also_negative);  // -PT2H
    
    // Arithmetic that produces negatives
    let a = ChronoDuration::seconds(3);
    let b = ChronoDuration::seconds(10);
    let diff = a - b;  // -7 seconds
    println!("Difference: {:?}", diff);  // -PT7S
}

Negative durations enable representing time differences without special handling.

Integration with Async and System APIs

use std::time::Duration as StdDuration;
use chrono::Duration as ChronoDuration;
 
// std::time::Duration works directly with async
async fn async_timing() {
    // Direct use with tokio::sleep
    tokio::time::sleep(StdDuration::from_secs(5)).await;
    
    // Direct use with tokio::interval
    let mut interval = tokio::time::interval(StdDuration::from_millis(100));
    
    // Direct use with std::thread::sleep
    std::thread::sleep(StdDuration::from_millis(50));
}
 
// chrono::Duration requires conversion
async fn async_with_chrono() {
    let chrono_dur = ChronoDuration::seconds(5);
    
    // Must convert to std::time::Duration
    let std_dur = chrono_dur.to_std().unwrap();
    tokio::time::sleep(std_dur).await;
    
    // Or use try_into (chrono Duration -> std Duration)
    let std_dur2: StdDuration = chrono_dur.try_into().unwrap();
    tokio::time::sleep(std_dur2).await;
}

std::time::Duration is the native type for async and system timing APIs.

Integration with Date/Time Types

use chrono::{DateTime, Duration, Utc, NaiveDateTime, NaiveDate, NaiveTime};
 
fn datetime_integration() {
    // chrono::Duration works with chrono date/time types
    let now = Utc::now();
    let future = now + Duration::hours(24);
    let past = now - Duration::hours(24);
    
    println!("Now: {}", now);
    println!("Future: {}", future);
    println!("Past: {}", past);
    
    // Difference between DateTimes produces chrono::Duration
    let diff = future - now;
    println!("Difference: {:?}", diff);  // PT24H
    
    // Can be negative
    let neg_diff = past - now;
    println!("Negative diff: {:?}", neg_diff);  // -PT24H
    
    // Works with NaiveDateTime too
    let naive = NaiveDate::from_ymd_opt(2024, 1, 1).unwrap()
        .and_hms_opt(0, 0, 0).unwrap();
    let later = naive + Duration::days(30);
}
 
// std::time::Duration doesn't integrate with date types
fn std_no_datetime_integration() {
    // No way to add std::time::Duration to a DateTime
    // Must convert through chrono::Duration first
}

chrono::Duration is essential for calendar-aware time calculations.

Time Range and Precision

use std::time::Duration as StdDuration;
use chrono::Duration as ChronoDuration;
 
fn time_ranges() {
    // std::time::Duration limits
    // - Minimum: Duration::ZERO (0 seconds, 0 nanoseconds)
    // - Maximum: u64::MAX seconds + 999,999,999 nanoseconds
    // - Sufficient for most practical timing
    
    let std_max = StdDuration::MAX;
    println!("std max: {:?}", std_max);  // ~584 million years
    
    // chrono::Duration limits
    // - Can represent negative values
    // - Microsecond precision internally
    // - Much larger range due to different internal representation
    
    let chrono_large = ChronoDuration::days(365 * 1000);  // 1000 years
    println!("Chrono large: {:?}", chrono_large);
    
    // chrono supports years and months (approximate)
    let years = ChronoDuration::days(365 * 5);  // ~5 years
    let months = ChronoDuration::days(30 * 6);  // ~6 months
}

Both handle practical ranges; chrono offers more intuitive large time spans.

Arithmetic Operations

use std::time::Duration as StdDuration;
use chrono::Duration as ChronoDuration;
 
fn arithmetic_comparison() {
    // std::time::Duration arithmetic
    let a = StdDuration::from_secs(10);
    let b = StdDuration::from_secs(3);
    
    let sum = a + b;              // 13 seconds
    let diff = a - b;             // 7 seconds (cannot go negative!)
    // let negative = b - a;      // panic! in debug, wraps in release
    let mul = a * 2;              // 20 seconds
    let div = a / 2;              // 5 seconds
    
    // chrono::Duration arithmetic
    let c = ChronoDuration::seconds(10);
    let d = ChronoDuration::seconds(3);
    
    let sum2 = c + d;             // 13 seconds
    let diff2 = c - d;            // 7 seconds
    let negative = d - c;         // -7 seconds (no panic!)
    let mul2 = c * 2;             // 20 seconds
    let div2 = c / 2;             // 5 seconds
    let rem = c % 3;              // 1 second
    
    // chrono also supports division by Duration
    let ratio = c / d;            // ~3.33 (f64)
    println!("Ratio: {}", ratio);
}

chrono::Duration supports negative results and duration-by-duration division.

Checked vs Wrapping Operations

use std::time::Duration as StdDuration;
use chrono::Duration as ChronoDuration;
 
fn checked_operations() {
    // std::time::Duration checked operations
    let a = StdDuration::from_secs(10);
    let b = StdDuration::from_secs(15);
    
    // checked_sub returns None instead of panic/wrap
    if let Some(result) = a.checked_sub(b) {
        println!("Result: {:?}", result);
    } else {
        println!("Would underflow!");  // This prints
    }
    
    // saturating operations clamp to valid range
    let saturated = a.saturating_sub(b);  // Duration::ZERO
    println!("Saturated: {:?}", saturated);
    
    // chrono::Duration doesn't need checked_sub
    // Subtraction naturally produces negative durations
    let c = ChronoDuration::seconds(10);
    let d = ChronoDuration::seconds(15);
    let result = c - d;  // -5 seconds, no problem
    println!("Chrono result: {:?}", result);
}

std::time::Duration needs checked operations to avoid underflow; chrono::Duration handles negatives directly.

Parsing and Formatting

use std::time::Duration as StdDuration;
use chrono::Duration as ChronoDuration;
 
fn parsing_formatting() {
    // std::time::Duration formatting
    let std_dur = StdDuration::new(5, 500_000_000);
    println!("Debug: {:?}", std_dur);      // 5.5s
    // No Display implementation
    // No standard parsing
    
    // chrono::Duration formatting
    let chrono_dur = ChronoDuration::seconds(5);
    println!("Debug: {:?}", chrono_dur);   // PT5S (ISO 8601)
    // chrono::Duration has Display
    println!("Display: {}", chrono_dur);   // PT5S
    
    // Parsing from ISO 8601
    let parsed: ChronoDuration = "PT5M30S".parse().unwrap();
    println!("Parsed: {:?}", parsed);      // PT5M30S
    
    let parsed2: ChronoDuration = "-PT1H".parse().unwrap();
    println!("Negative parsed: {:?}", parsed2);  // -PT1H
}

chrono::Duration supports ISO 8601 parsing and display; std::time::Duration only has Debug.

Conversion Between Types

use std::time::Duration as StdDuration;
use chrono::Duration as ChronoDuration;
 
fn conversions() {
    // chrono::Duration -> std::time::Duration
    let chrono_dur = ChronoDuration::seconds(5);
    let std_dur: StdDuration = chrono_dur.to_std().unwrap();
    println!("Converted: {:?}", std_dur);
    
    // Cannot convert negative chrono to std
    let negative_chrono = ChronoDuration::seconds(-5);
    let result = negative_chrono.to_std();
    println!("Negative conversion: {:?}", result);  // Err
    
    // std::time::Duration -> chrono::Duration
    let std_dur2 = StdDuration::from_millis(1500);
    let chrono_dur2 = ChronoDuration::from_std(std_dur2).unwrap();
    println!("Chrono from std: {:?}", chrono_dur2);
    
    // Using From/TryFrom traits
    let chrono_dur3 = ChronoDuration::from(std_dur2);
    let std_dur3: StdDuration = chrono_dur.try_into().unwrap();
}

Conversion is straightforward for positive durations; negative ones fail when converting to std::time::Duration.

Comparison Operations

use std::time::Duration as StdDuration;
use chrono::Duration as ChronoDuration;
 
fn comparison() {
    // Both support standard comparisons
    let std_a = StdDuration::from_secs(5);
    let std_b = StdDuration::from_secs(10);
    
    assert!(std_a < std_b);
    assert!(std_a <= std_b);
    assert!(std_b > std_a);
    
    let chrono_a = ChronoDuration::seconds(5);
    let chrono_b = ChronoDuration::seconds(10);
    let chrono_c = ChronoDuration::seconds(-5);
    
    assert!(chrono_a < chrono_b);
    assert!(chrono_c < chrono_a);  // Negative is less than positive
    
    // chrono::Duration implements PartialOrd with std::time::Duration
    let std_dur = StdDuration::from_secs(5);
    let chrono_dur = ChronoDuration::seconds(5);
    // assert!(chrono_dur == std_dur);  // Not directly comparable
}

Both types support comparison; chrono::Duration handles negative ordering correctly.

Real-World Use Cases

use std::time::Duration as StdDuration;
use chrono::{Duration as ChronoDuration, Utc, DateTime};
 
// Use std::time::Duration for async timing
async fn fetch_with_timeout() -> Result<String, String> {
    let client = reqwest::Client::new();
    
    // Async APIs use std::time::Duration
    let response = tokio::time::timeout(
        StdDuration::from_secs(10),
        client.get("https://example.com").send()
    ).await
        .map_err(|_| "Timeout")?;
    
    Ok(response.text().await?)
}
 
// Use chrono::Duration for date calculations
fn calculate_deadline(base: DateTime<Utc>, workdays: i64) -> DateTime<Utc> {
    let mut deadline = base;
    let mut days_added = 0i64;
    
    while days_added < workdays {
        deadline = deadline + ChronoDuration::days(1);
        // Skip weekends (simplified)
        if deadline.weekday().number_from_monday() <= 5 {
            days_added += 1;
        }
    }
    
    deadline
}
 
// Use std::time::Duration for rate limiting
struct RateLimiter {
    interval: StdDuration,
    last_call: std::time::Instant,
}
 
impl RateLimiter {
    fn new(interval: StdDuration) -> Self {
        Self {
            interval,
            last_call: std::time::Instant::now() - interval,
        }
    }
    
    async fn wait(&mut self) {
        let elapsed = self.last_call.elapsed();
        if elapsed < self.interval {
            tokio::time::sleep(self.interval - elapsed).await;
        }
        self.last_call = std::time::Instant::now();
    }
}
 
// Use chrono::Duration for scheduling
fn schedule_reminders(event_time: DateTime<Utc>) -> Vec<DateTime<Utc>> {
    vec![
        event_time - ChronoDuration::weeks(1),
        event_time - ChronoDuration::days(1),
        event_time - ChronoDuration::hours(1),
        event_time - ChronoDuration::minutes(15),
    ]
}

Each type excels in different domains: system timing vs calendar calculations.

Feature Comparison

// Feature comparison table
// 
// Feature                    | std::time::Duration | chrono::Duration
// ---------------------------|---------------------|------------------
// Negative values            | No                  | Yes
// Integration with async     | Direct              | Requires conversion
// Integration with DateTime  | No                  | Direct
// ISO 8601 parsing           | No                  | Yes
// Display trait              | No (Debug only)     | Yes
// Duration division          | Only by scalar      | By scalar and Duration
// Checked arithmetic         | Yes                 | Not needed
// Part of std library        | Yes                 | No (external crate)
// Zero-cost abstraction      | Yes                 | Similar

Practical Decision Guide

// Use std::time::Duration when:
// - Working with async/await (tokio, async-std)
// - Using std::thread::sleep
// - Setting timeouts for I/O operations
// - Working with std::time::Instant
// - Building rate limiters or throttling
// - Don't need negative durations
 
// Use chrono::Duration when:
// - Calculating dates and times
// - Working with DateTime, NaiveDateTime
// - Need to represent negative time spans
// - Parsing ISO 8601 duration strings
// - Doing calendar arithmetic (days, weeks, months)
// - Computing differences between timestamps

Mixed Usage Pattern

use std::time::Duration as StdDuration;
use chrono::{DateTime, Duration as ChronoDuration, Utc};
 
struct EventScheduler {
    // Store schedule with chrono types
    next_event: DateTime<Utc>,
    reminder_offset: ChronoDuration,
    
    // Use std for async timing
    check_interval: StdDuration,
}
 
impl EventScheduler {
    fn new(event_time: DateTime<Utc>) -> Self {
        Self {
            next_event: event_time,
            reminder_offset: ChronoDuration::minutes(15),
            check_interval: StdDuration::from_secs(60),
        }
    }
    
    async fn run(&mut self) {
        loop {
            let now = Utc::now();
            let time_until_event = self.next_event - now;
            
            // Convert chrono duration to std for async sleep
            if time_until_event <= ChronoDuration::zero() {
                println!("Event time!");
                break;
            }
            
            // Check if it's time for reminder
            if time_until_event <= self.reminder_offset {
                println!("Reminder: Event in {} minutes!", 
                    time_until_event.num_minutes());
            }
            
            // Sleep using std duration
            tokio::time::sleep(self.check_interval).await;
        }
    }
}

Real applications often use both types, converting between them as needed.

Synthesis

The two Duration types serve complementary purposes:

Use std::time::Duration when:

  • Working with async runtimes (tokio, async-std)
  • System timing operations (thread::sleep, Instant)
  • Setting timeouts for I/O and network operations
  • Building rate limiters, throttling, polling intervals
  • You want zero external dependencies

Use chrono::Duration when:

  • Performing date/time arithmetic
  • Working with DateTime, NaiveDateTime, NaiveDate
  • You need negative durations (time differences)
  • Parsing or formatting ISO 8601 durations
  • Calendar-aware calculations (days, weeks, months)

Key insight: std::time::Duration is the native type for the Rust runtime and async ecosystem, while chrono::Duration is the native type for calendar and date/time arithmetic. Convert between them using to_std() and from_std() when bridging these domains. The inability of std::time::Duration to represent negative values is intentionalā€”it models elapsed time, not time differences, while chrono::Duration models the mathematical concept of a time span that can be positive or negative.