Arc<Mutex>

Guides

Rust walkthroughs

← Back to all guides

How does chrono::Duration::seconds differ from std::time::Duration::from_secs for time span representation?

chrono::Duration::seconds creates a signed duration that can represent negative time spans, while std::time::Duration::from_secs creates an unsigned duration that cannot be negative. The standard library's Duration is purely non-negative, making it suitable for timeouts and intervals but limiting for time arithmetic. The chrono crate's Duration supports negative values, enabling subtraction of later times from earlier times and representing time differences that may be backwards in time. This fundamental difference affects how the two types handle arithmetic operations, conversions, and use cases.

Creating Durations

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn creating_durations() {
    // Standard library: unsigned duration
    let std_duration = StdDuration::from_secs(60);
    // Cannot create negative durations
    // StdDuration::from_secs(-1);  // Won't compile
    
    // chrono: signed duration
    let chrono_duration = ChronoDuration::seconds(60);
    let negative_duration = ChronoDuration::seconds(-60);
    
    println!("std: {:?}", std_duration);      // 60s
    println!("chrono: {:?}", chrono_duration); // 60s
    println!("negative: {:?}", negative_duration); // -60s
}

The key difference is that chrono::Duration can be negative.

Negative Durations

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn negative_durations() {
    // std::time::Duration cannot be negative
    // This is enforced at the type level:
    // - from_secs takes u64 (unsigned)
    // - from_millis takes u64
    // - No way to represent "negative time"
    
    // chrono::Duration can be negative
    let negative = ChronoDuration::seconds(-30);
    println!("Negative: {:?}", negative);  // -30s
    
    // Useful for time arithmetic
    let earlier = ChronoDuration::seconds(100);
    let later = ChronoDuration::seconds(150);
    let diff = earlier - later;  // -50s
    
    println!("Difference: {:?}", diff);  // -50s
}

Negative durations enable time difference calculations.

Time Arithmetic Differences

use chrono::{DateTime, Utc, Duration as ChronoDuration};
use std::time::Duration as StdDuration;
 
fn time_arithmetic() {
    // With chrono::Duration, subtracting times can give negative result
    let time1: DateTime<Utc> = Utc::now();
    let time2: DateTime<Utc> = time1 + ChronoDuration::seconds(100);
    
    // Subtracting later from earlier gives negative duration
    let diff = time1.signed_duration_since(time2);
    println!("Diff: {:?}", diff);  // -100s
    
    // With std::time::Duration, you must handle ordering
    let instant1 = std::time::Instant::now();
    let instant2 = instant1 + StdDuration::from_secs(100);
    
    // duration_since panics if earlier > later
    // let diff = instant1.duration_since(instant2);  // panic!
    
    // Must use checked_duration_since
    let diff = instant1.checked_duration_since(instant2);
    println!("Checked diff: {:?}", diff);  // None
}

chrono::Duration handles time ordering gracefully; std::time::Duration requires careful handling.

Conversion Between Types

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn conversions() {
    // chrono::Duration to std::time::Duration
    let chrono_dur = ChronoDuration::seconds(60);
    let std_dur: StdDuration = chrono_dur.to_std().unwrap();
    println!("Converted: {:?}", std_dur);
    
    // Negative chrono duration cannot convert to std
    let negative = ChronoDuration::seconds(-60);
    let result = negative.to_std();
    println!("Negative conversion: {:?}", result);  // None
    
    // std::time::Duration to chrono::Duration
    let std_dur = StdDuration::from_secs(60);
    let chrono_dur = ChronoDuration::from_std(std_dur);
    println!("From std: {:?}", chrono_dur);
}

chrono::Duration::to_std() returns None for negative values.

Type Signatures

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn type_signatures() {
    // std::time::Duration::from_secs
    // pub fn from_secs(secs: u64) -> Duration
    // Parameter is u64 (unsigned)
    
    // chrono::Duration::seconds
    // pub fn seconds(seconds: i64) -> Duration
    // Parameter is i64 (signed)
    
    // This difference propagates through the API:
    
    // Std duration constructors:
    let _ = StdDuration::from_secs(60);      // u64
    let _ = StdDuration::from_millis(60000); // u64
    let _ = StdDuration::from_micros(60_000_000); // u64
    
    // Chrono duration constructors:
    let _ = ChronoDuration::seconds(60);      // i64
    let _ = ChronoDuration::milliseconds(60000); // i64
    let _ = ChronoDuration::microseconds(60_000_000); // i64
}

The parameter types (u64 vs i64) reflect the signedness of each duration type.

Subsecond Precision

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn subsecond_precision() {
    // std::time::Duration - nanosecond precision
    let std_nano = StdDuration::from_nanos(123456789);
    println!("std nano: {:?}", std_nano);
    
    // chrono::Duration - also nanosecond precision
    let chrono_nano = ChronoDuration::nanoseconds(123456789);
    println!("chrono nano: {:?}", chrono_nano);
    
    // Both support fractional seconds
    let std_frac = StdDuration::from_secs_f64(1.5);  // 1.5 seconds
    let chrono_frac = ChronoDuration::seconds(1) + ChronoDuration::milliseconds(500);
    
    println!("std frac: {:?}", std_frac);
    println!("chrono frac: {:?}", chrono_frac);
    
    // chrono also supports negative fractional durations
    let chrono_neg_frac = ChronoDuration::milliseconds(-1500);
    println!("neg frac: {:?}", chrono_neg_frac);  // -1.5s
}

Both support nanosecond precision; chrono allows negative subsecond values.

Overflow Handling

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn overflow_handling() {
    // std::time::Duration has no overflow protection in basic constructors
    // from_secs(very_large) could overflow internally
    
    // chrono::Duration can handle larger ranges with i64
    let large = ChronoDuration::seconds(i64::MAX);
    println!("Large: {:?}", large);
    
    // Operations on chrono::Duration can overflow
    let huge = ChronoDuration::MAX;
    // huge + ChronoDuration::seconds(1);  // panic or wrap (implementation-defined)
    
    // std::time::Duration has similar overflow concerns
    let std_huge = StdDuration::from_secs(u64::MAX);
    // std_huge + StdDuration::from_secs(1);  // panic
}

Both types can overflow; handle with checked/saturating operations where needed.

Use with Chrono DateTime

use chrono::{DateTime, Utc, Duration, NaiveDateTime};
 
fn with_datetime() {
    let now: DateTime<Utc> = Utc::now();
    
    // chrono::Duration integrates with DateTime
    let future = now + Duration::seconds(60);
    let past = now - Duration::seconds(60);
    
    println!("Now: {}", now);
    println!("Future: {}", future);
    println!("Past: {}", past);
    
    // Duration differences work naturally
    let diff = future.signed_duration_since(now);
    println!("Diff: {:?}", diff);  // 60s
    
    // Negative differences work too
    let neg_diff = past.signed_duration_since(now);
    println!("Neg diff: {:?}", neg_diff);  // -60s
    
    // std::time::Duration doesn't integrate with chrono DateTime
    // You'd need to convert first
}

chrono::Duration integrates naturally with chrono's date/time types.

Use with std::time::Instant

use std::time::{Duration, Instant};
 
fn with_instant() {
    let start = Instant::now();
    
    // std::time::Duration integrates with Instant
    let future = start + Duration::from_secs(60);
    
    // Cannot subtract to get negative Duration
    // let past = start - Duration::from_secs(60);  // Compile error!
    
    // elapsed() always returns positive Duration
    let elapsed = start.elapsed();
    println!("Elapsed: {:?}", elapsed);
    
    // checked_duration_since for safe subtraction
    let earlier = Instant::now();
    let later = earlier + Duration::from_secs(10);
    
    // Wrong order returns None
    let result = earlier.checked_duration_since(later);
    println!("Wrong order: {:?}", result);  // None
}

std::time::Duration works with std::time::Instant but cannot represent negative differences.

Checked and Saturating Operations

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn checked_operations() {
    // std::time::Duration has checked operations
    let a = StdDuration::from_secs(100);
    let b = StdDuration::from_secs(50);
    
    let checked_sub = a.checked_sub(b);
    println!("Checked sub: {:?}", checked_sub);  // Some(50s)
    
    let checked_add = a.checked_add(StdDuration::MAX);
    println!("Overflow add: {:?}", checked_add);  // None
    
    // chrono::Duration has checked operations too
    let c = ChronoDuration::seconds(100);
    let d = ChronoDuration::seconds(50);
    
    let chrono_checked = c.checked_sub(d);
    println!("Chrono checked: {:?}", chrono_checked);  // Some(50s)
    
    // Negative subtraction works
    let neg_sub = ChronoDuration::seconds(10).checked_sub(ChronoDuration::seconds(50));
    println!("Neg sub: {:?}", neg_sub);  // Some(-40s)
}

Both types provide checked operations; chrono handles negative results.

Comparison Operations

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn comparison() {
    // std::time::Duration: compare unsigned values
    let a = StdDuration::from_secs(10);
    let b = StdDuration::from_secs(20);
    
    println!("a < b: {}", a < b);  // true
    println!("a == b: {}", a == b);  // false
    
    // chrono::Duration: compare signed values
    let c = ChronoDuration::seconds(10);
    let d = ChronoDuration::seconds(-20);
    
    println!("c > d: {}", c > d);  // true (10 > -20)
    println!("c < 0: {}", c < ChronoDuration::zero());  // false
    
    // chrono::Duration::zero() for comparison with zero
    let zero = ChronoDuration::zero();
    let negative = ChronoDuration::seconds(-5);
    
    println!("negative < zero: {}", negative < zero);  // true
}

chrono::Duration compares signed values; comparisons with zero are meaningful.

Arithmetic Operations

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn arithmetic() {
    // std::time::Duration arithmetic
    let a = StdDuration::from_secs(100);
    let b = StdDuration::from_secs(50);
    
    let sum = a + b;
    let diff = a - b;  // Works (100 - 50 = 50)
    println!("std sum: {:?}, diff: {:?}", sum, diff);
    
    // Subtraction that would go negative panics
    // let bad = b - a;  // 50 - 100 would panic in debug, wrap in release
    
    // chrono::Duration arithmetic
    let c = ChronoDuration::seconds(100);
    let d = ChronoDuration::seconds(50);
    
    let sum = c + d;
    let diff = c - d;
    println!("chrono sum: {:?}, diff: {:?}", sum, diff);
    
    // Can go negative!
    let neg = d - c;
    println!("Negative result: {:?}", neg);  // -50s
    
    // Negation
    let negated = -c;
    println!("Negated: {:?}", negated);  // -100s
}

chrono::Duration supports subtraction that yields negative values; std::time::Duration panics or wraps.

Absolute Value and Sign

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn absolute_value() {
    // chrono::Duration has abs() method
    let negative = ChronoDuration::seconds(-100);
    let absolute = negative.abs();
    println!("Absolute: {:?}", absolute);  // 100s
    
    // std::time::Duration is always non-negative
    // No abs() needed (already unsigned)
    
    // chrono::Duration has signum
    let pos = ChronoDuration::seconds(10);
    let neg = ChronoDuration::seconds(-10);
    let zero = ChronoDuration::zero();
    
    println!("pos signum: {}", pos.num_seconds().signum());  // 1
    println!("neg signum: {}", neg.num_seconds().signum());  // -1
    println!("zero signum: {}", zero.num_seconds().signum());  // 0
}

chrono::Duration has abs(); std::time::Duration is inherently non-negative.

Iteration and Loops

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn iteration() {
    // std::time::Duration is natural for timeout loops
    let timeout = StdDuration::from_secs(10);
    let interval = StdDuration::from_millis(100);
    
    let mut elapsed = StdDuration::ZERO;
    while elapsed < timeout {
        // Do work
        std::thread::sleep(interval);
        elapsed += interval;
    }
    
    // chrono::Duration works similarly but can also count down
    let countdown = ChronoDuration::seconds(10);
    let mut remaining = countdown;
    while remaining > ChronoDuration::zero() {
        // Do work
        remaining = remaining - ChronoDuration::milliseconds(100);
    }
}

Both work in loops; chrono allows countdown semantics with negative termination.

Serialization

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn serialization() {
    // std::time::Duration displays as seconds with subsecond precision
    let std = StdDuration::from_secs(90);
    println!("std: {:?}", std);  // 1m30s (Debug format)
    
    // chrono::Duration displays with sign
    let chrono_pos = ChronoDuration::seconds(90);
    let chrono_neg = ChronoDuration::seconds(-90);
    
    println!("chrono_pos: {:?}", chrono_pos);  // PT90S (ISO 8601 format)
    println!("chrono_neg: {:?}", chrono_neg);  // -PT90S
    
    // chrono has human-readable formatting
    println!("Human: {}", chrono_pos);  // 90s
}

Formatting differs; chrono uses ISO 8601-style format with signs.

Practical Use Cases

use chrono::{DateTime, Utc, Duration as ChronoDuration};
use std::time::Duration as StdDuration;
 
fn use_cases() {
    // Use std::time::Duration for:
    // 1. Timeouts (always positive)
    // 2. Sleep durations
    // 3. Intervals (always positive)
    // 4. Performance measurement
    
    fn with_timeout() {
        let timeout = StdDuration::from_secs(30);
        // Use with async timeouts, thread::sleep, etc.
    }
    
    // Use chrono::Duration for:
    // 1. Time differences (can be negative)
    // 2. Calendar calculations
    // 3. Scheduling
    // 4. Duration arithmetic
    
    fn with_dates() {
        let event1: DateTime<Utc> = Utc::now();
        let event2: DateTime<Utc> = event1 + ChronoDuration::hours(2);
        
        // Can subtract in either order
        let diff1 = event2.signed_duration_since(event1);  // +2h
        let diff2 = event1.signed_duration_since(event2);  // -2h
        
        println!("Event2 is {:?} after Event1", diff1);
        println!("Event1 is {:?} before Event2", diff2);
    }
}

Choose based on whether negative durations are meaningful in your context.

Interoperability

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn interoperability() {
    // Converting between types when needed
    
    // chrono -> std (for APIs requiring std::time::Duration)
    let chrono = ChronoDuration::seconds(60);
    if let Some(std) = chrono.to_std() {
        println!("Converted to std: {:?}", std);
    }
    
    // std -> chrono (for chrono date arithmetic)
    let std = StdDuration::from_secs(60);
    let chrono = ChronoDuration::from_std(std);
    println!("Converted to chrono: {:?}", chrono);
    
    // Function accepting both requires conversion
    fn takes_std(d: StdDuration) {
        println!("Got: {:?}", d);
    }
    
    fn takes_chrono(d: ChronoDuration) {
        println!("Got: {:?}", d);
    }
    
    // To pass chrono to std function:
    let c = ChronoDuration::seconds(30);
    if let Some(s) = c.to_std() {
        takes_std(s);
    }
    
    // To pass std to chrono function:
    let s = StdDuration::from_secs(30);
    takes_chrono(ChronoDuration::from_std(s));
}

Convert between types when APIs require specific duration types.

Comparison Summary

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn comparison_table() {
    // | Feature | std::time::Duration | chrono::Duration |
    // |---------|---------------------|------------------|
    // | Sign | Unsigned (non-negative) | Signed (can be negative) |
    // | from_secs param | u64 | i64 |
    // | Negation | Not possible | Supported (-) |
    // | Time differences | Must be ordered | Any order |
    // | abs() | Not needed | Available |
    // | zero() | ZERO constant | zero() method |
    // | DateTime integration | None | Native |
    // | Instant integration | Native | Convert first |
    // | Timeout use | Ideal | Overkill |
    // | Calendar use | Convert first | Ideal |
}

Synthesis

Quick reference:

use chrono::Duration as ChronoDuration;
use std::time::Duration as StdDuration;
 
fn quick_reference() {
    // std::time::Duration::from_secs(u64)
    // - Creates non-negative duration
    // - Use for timeouts, sleep, intervals
    // - Works with std::time::Instant
    // - Cannot represent "time before"
    
    let timeout = StdDuration::from_secs(30);
    
    // chrono::Duration::seconds(i64)
    // - Creates signed duration (can be negative)
    // - Use for time arithmetic, differences
    // - Works with chrono DateTime
    // - Can represent "past" or "before"
    
    let diff = ChronoDuration::seconds(-30);
    
    // Convert between:
    let chrono_to_std = ChronoDuration::seconds(60).to_std();
    let std_to_chrono = ChronoDuration::from_std(StdDuration::from_secs(60));
    
    // Key mental model:
    // std::time::Duration = "amount of time" (always positive)
    // chrono::Duration = "time difference" (can be positive or negative)
}

Key insight: The fundamental distinction between these duration types is semantic: std::time::Duration represents an amount of time, always non-negative, making it ideal for timeouts, sleeps, and intervals. chrono::Duration represents a difference between two times, which can naturally be positive or negative depending on ordering. This reflects real-world time arithmetic where "meeting A is before meeting B" produces a different sign than "meeting B is before meeting A." Use std::time::Duration when you're measuring or waiting—situations where time is inherently positive. Use chrono::Duration when you're calculating differences between timestamps or performing calendar arithmetic where the sign matters. The to_std() and from_std() conversion methods bridge the two worlds when APIs require a specific type, but the conversion from chrono to std can fail (returning None) for negative durations.