How does `chrono::NaiveDateTime::and_local_timezone` handle ambiguous local times during daylight saving transitions?

chrono::NaiveDateTime::and_local_timezone returns a LocalResult enum that can be None (non-existent time), Single (unambiguous time), or Ambiguous (two possible times during fall-back DST transitions), forcing the caller to explicitly handle the ambiguity rather than silently picking one interpretation. During daylight saving transitions, local times can be invalid (skipped during spring forward) or ambiguous (repeated during fall back), and and_local_timezone models these cases distinctly to prevent silent data corruption.

The LocalResult Enum

use chrono::{NaiveDateTime, TimeZone, LocalResult};
 
fn local_result_basics() {
    // and_local_timezone returns LocalResult, not a direct DateTime
    
    let naive = NaiveDateTime::from_timestamp_opt(1604186400, 0).unwrap(); // Some datetime
    
    // LocalResult has three variants:
    match naive.and_local_timezone(chrono::FixedOffset::east_opt(0).unwrap()) {
        LocalResult::None => {
            // This local time does not exist in the timezone
            // Example: 2:00 AM during spring forward DST transition
        }
        LocalResult::Single(dt) => {
            // Unambiguous: this local time maps to exactly one UTC time
            dt; // DateTime<FixedOffset>
        }
        LocalResult::Ambiguous(earliest, latest) => {
            // Ambiguous: this local time occurs twice
            // Example: 1:00 AM during fall back DST transition
            // Could be first occurrence or second occurrence
        }
    }
}

The LocalResult enum forces explicit handling of edge cases.

Understanding DST Transitions

use chrono::{NaiveDateTime, NaiveDate, NaiveTime, TimeZone, FixedOffset};
 
fn dst_transition_types() {
    // DST transitions create two types of local time problems:
    
    // 1. Spring Forward (Missing Time)
    // Clocks jump from 1:59 AM to 3:00 AM
    // Times 2:00 AM - 2:59 AM do NOT exist
    // Example: US Eastern, second Sunday in March at 2:00 AM
    
    // 2. Fall Back (Ambiguous Time)
    // Clocks go from 1:59 AM back to 1:00 AM
    // Times 1:00 AM - 1:59 AM occur TWICE
    // Example: US Eastern, first Sunday in November at 2:00 AM
    
    // Let's illustrate with a fixed offset timezone
    // (simpler than named timezone for demonstration)
    
    // A timezone with DST: +01:00 standard, +02:00 summer
    // This is simplified; real DST is more complex
}
 
fn missing_time_example() {
    // Create a timezone that transitions
    
    // In US Eastern, on March 12, 2023:
    // 1:59:59 AM EST exists
    // 2:00:00 AM does NOT exist (jumped to 3:00 AM EDT)
    // 2:59:59 AM does NOT exist
    // 3:00:00 AM EDT exists
    
    // Using a fixed offset won't show this - need a real timezone
    use chrono_tz::America::New_York;
    
    let missing_time = NaiveDate::from_ymd_opt(2023, 3, 12).unwrap()
        .and_hms_opt(2, 30, 0).unwrap();
    
    let result = missing_time.and_local_timezone(New_York);
    
    match result {
        LocalResult::None => {
            println!("This time does not exist - it was skipped during DST spring forward");
        }
        LocalResult::Single(_) => {
            println!("This time exists unambiguously");
        }
        LocalResult::Ambiguous(_, _) => {
            println!("This time is ambiguous - it occurs twice");
        }
    }
}
 
fn ambiguous_time_example() {
    use chrono_tz::America::New_York;
    
    // In US Eastern, on November 5, 2023:
    // 1:59:59 AM EDT (first occurrence)
    // 1:00:00 AM EST (second occurrence - clocks went back)
    // 1:59:59 AM EST (second occurrence)
    // 2:00:00 AM EST (single)
    
    let ambiguous_time = NaiveDate::from_ymd_opt(2023, 11, 5).unwrap()
        .and_hms_opt(1, 30, 0).unwrap();
    
    let result = ambiguous_time.and_local_timezone(New_York);
    
    match result {
        LocalResult::Ambiguous(earliest, latest) => {
            // earliest: 1:30 AM EDT (UTC-4) - first occurrence
            // latest: 1:30 AM EST (UTC-5) - second occurrence
            
            println!("Earliest: {} (offset {:?})", 
                earliest, earliest.offset());
            println!("Latest: {} (offset {:?})", 
                latest, latest.offset());
            
            // Both are valid interpretations of "1:30 AM on November 5"
        }
        _ => unreachable!(),
    }
}

DST creates missing times (spring forward) and ambiguous times (fall back).

Single (Unambiguous) Times

use chrono::{NaiveDateTime, TimeZone, LocalResult};
use chrono_tz::America::New_York;
 
fn unambiguous_times() {
    // Most times are unambiguous
    
    let normal_time = NaiveDateTime::parse_from_str(
        "2023-06-15 14:30:00",
        "%Y-%m-%d %H:%M:%S"
    ).unwrap();
    
    let result = normal_time.and_local_timezone(New_York);
    
    match result {
        LocalResult::Single(dt) => {
            println!("Unambiguous: {}", dt);
            println!("Offset: {:?}", dt.offset());
            // Single unique interpretation
        }
        _ => panic!("Normal times should be unambiguous"),
    }
    
    // Times far from DST transitions are always unambiguous
    
    let safe_time = NaiveDateTime::parse_from_str(
        "2023-06-15 12:00:00",
        "%Y-%m-%d %H:%M:%S"
    ).unwrap();
    
    // Summer, midday - definitely unambiguous
    assert!(matches!(
        safe_time.and_local_timezone(New_York),
        LocalResult::Single(_)
    ));
}

Most local times are unambiguous and return LocalResult::Single.

Handling None (Non-Existent Times)

use chrono::{NaiveDateTime, TimeZone, LocalResult};
use chrono_tz::America::New_York;
 
fn handling_nonexistent() {
    // Non-existent time: during spring forward DST transition
    
    // March 12, 2023, 2:30 AM doesn't exist in New York
    // (clocks jumped from 1:59 AM to 3:00 AM)
    
    let nonexistent = NaiveDate::from_ymd_opt(2023, 3, 12).unwrap()
        .and_hms_opt(2, 30, 0).unwrap();
    
    let result = nonexistent.and_local_timezone(New_York);
    
    match result {
        LocalResult::None => {
            // The local time doesn't exist
            // We need to decide how to handle it
            
            // Option 1: Error
            panic!("Invalid local time");
            
            // Option 2: Use the next valid time (forward adjustment)
            // Would be 3:30 AM EDT
            
            // Option 3: Use the previous valid time (backward adjustment)
            // Would be 1:59:59 AM EST, then advance 30 minutes? No...
            // Actually 1:30 AM EST + 1 hour = 2:30 AM which doesn't exist
        }
        _ => {}
    }
}
 
fn workaround_nonexistent() {
    use chrono_tz::America::New_York;
    
    let nonexistent = NaiveDate::from_ymd_opt(2023, 3, 12).unwrap()
        .and_hms_opt(2, 30, 0).unwrap();
    
    // Method 1: Use the earliest possible interpretation
    // (advance to next valid time)
    let earliest = New_York.from_local_datetime(&nonexistent)
        .earliest();  // Returns Option<DateTime>
    
    // For nonexistent times, earliest() returns None
    // But we can use latest() which also returns None
    
    // Method 2: Use single() which returns Option
    let single = New_York.from_local_datetime(&nonexistent)
        .single();  // Returns Option<DateTime>
    
    // For nonexistent times, single() returns None
    
    // Method 3: Use with a fallback
    let dt = New_York.from_local_datetime(&nonexistent)
        .single()
        .or_else(|| {
            // Fallback: advance by 1 hour to skip the gap
            nonexistent.and_utc().checked_add_signed(chrono::Duration::hours(1))
                .and_then(|utc| New_York.from_utc_datetime(&utc.naive_utc()).single())
        });
}

Non-existent times require explicit handling strategies.

Handling Ambiguous Times

use chrono::{NaiveDateTime, TimeZone, LocalResult};
use chrono_tz::America::New_York;
 
fn handling_ambiguous() {
    // Ambiguous time: during fall back DST transition
    
    // November 5, 2023, 1:30 AM occurs twice in New York
    // Once in EDT (UTC-4), once in EST (UTC-5)
    
    let ambiguous = NaiveDate::from_ymd_opt(2023, 11, 5).unwrap()
        .and_hms_opt(1, 30, 0).unwrap();
    
    let result = ambiguous.and_local_timezone(New_York);
    
    match result {
        LocalResult::Ambiguous(earliest, latest) => {
            // Two possible interpretations
            
            // earliest: In EDT (still daylight time)
            // UTC time: 2023-11-05 05:30:00 UTC
            
            // latest: In EST (standard time)
            // UTC time: 2023-11-05 06:30:00 UTC
            
            println!("Ambiguous local time:");
            println!("  First occurrence: {} (offset {:?})", 
                earliest, earliest.offset());
            println!("  Second occurrence: {} (offset {:?})", 
                latest, latest.offset());
            
            // Both are valid but represent different UTC times!
        }
        _ => {}
    }
}
 
fn resolving_ambiguity() {
    use chrono_tz::America::New_York;
    
    let ambiguous = NaiveDate::from_ymd_opt(2023, 11, 5).unwrap()
        .and_hms_opt(1, 30, 0).unwrap();
    
    // Method 1: Use earliest() - first occurrence
    let earliest = New_York.from_local_datetime(&ambiguous)
        .earliest();
    // Returns Some(1:30 AM EDT)
    
    // Method 2: Use latest() - second occurrence  
    let latest = New_York.from_local_datetime(&ambiguous)
        .latest();
    // Returns Some(1:30 AM EST)
    
    // Method 3: Use single() - fails for ambiguous
    let single = New_York.from_local_datetime(&ambiguous)
        .single();
    // Returns None for ambiguous times
    
    // Choosing which to use depends on application:
    
    // For future appointments: use latest (standard time)
    // The later occurrence is the "real" one after the transition
    
    // For past events: need additional context (e.g., was it DST?)
}
 
fn disambiguation_strategies() {
    use chrono_tz::America::New_York;
    
    let ambiguous = NaiveDate::from_ymd_opt(2023, 11, 5).unwrap()
        .and_hms_opt(1, 30, 0).unwrap();
    
    // Strategy 1: Always prefer earliest
    let prefer_earliest = || {
        New_York.from_local_datetime(&ambiguous)
            .earliest()
            .expect("Should have earliest")
    };
    
    // Strategy 2: Always prefer latest
    let prefer_latest = || {
        New_York.from_local_datetime(&ambiguous)
            .latest()
            .expect("Should have latest")
    };
    
    // Strategy 3: Use offset hint (if you know DST status)
    // chrono-tz provides this via the ambiguous method
    
    // Strategy 4: Reject ambiguous times
    let reject_ambiguous = || -> Result<_, &'static str> {
        New_York.from_local_datetime(&ambiguous)
            .single()
            .ok_or("Ambiguous or invalid time")
    };
    
    // Strategy 5: Store in UTC to avoid ambiguity
    let store_as_utc = || {
        // Always convert to UTC before storage
        // When reading, convert back to local for display
        // UTC is never ambiguous
    };
}

Ambiguous times have two valid UTC representations.

The earliest(), latest(), and single() Methods

use chrono::{NaiveDateTime, TimeZone, LocalResult};
use chrono_tz::America::New_York;
 
fn convenience_methods() {
    let ambiguous = NaiveDate::from_ymd_opt(2023, 11, 5).unwrap()
        .and_hms_opt(1, 30, 0).unwrap();
    
    let nonexistent = NaiveDate::from_ymd_opt(2023, 3, 12).unwrap()
        .and_hms_opt(2, 30, 0).unwrap();
    
    let normal = NaiveDate::from_ymd_opt(2023, 6, 15).unwrap()
        .and_hms_opt(12, 0, 0).unwrap();
    
    // .single() - Returns Option<DateTime>
    // - Some(dt) for unambiguous times
    // - None for ambiguous or nonexistent times
    
    assert!(New_York.from_local_datetime(&normal).single().is_some());
    assert!(New_York.from_local_datetime(&ambiguous).single().is_none());
    assert!(New_York.from_local_datetime(&nonexistent).single().is_none());
    
    // .earliest() - Returns Option<DateTime>
    // - Some(dt) for unambiguous or ambiguous (first occurrence)
    // - None for nonexistent times
    
    assert!(New_York.from_local_datetime(&normal).earliest().is_some());
    assert!(New_York.from_local_datetime(&ambiguous).earliest().is_some());
    assert!(New_York.from_local_datetime(&nonexistent).earliest().is_none());
    
    // .latest() - Returns Option<DateTime>
    // - Some(dt) for unambiguous or ambiguous (last occurrence)
    // - None for nonexistent times
    
    assert!(New_York.from_local_datetime(&normal).latest().is_some());
    assert!(New_York.from_local_datetime(&ambiguous).latest().is_some());
    assert!(New_York.from_local_datetime(&nonexistent).latest().is_none());
}

The convenience methods handle different cases appropriately.

FixedOffset vs Named Timezones

use chrono::{NaiveDateTime, FixedOffset, TimeZone, LocalResult};
 
fn fixed_offset_no_dst() {
    // FixedOffset has no DST transitions - always unambiguous
    
    let offset = FixedOffset::east_opt(5 * 3600).unwrap(); // UTC+5
    
    let any_time = NaiveDate::from_ymd_opt(2023, 3, 12).unwrap()
        .and_hms_opt(2, 30, 0).unwrap();
    
    // FixedOffset has no DST - every local time is unambiguous
    let result = any_time.and_local_timezone(offset);
    
    match result {
        LocalResult::Single(dt) => {
            println!("Fixed offset is always unambiguous: {}", dt);
        }
        LocalResult::None | LocalResult::Ambiguous(_, _) => {
            // This won't happen with FixedOffset
            panic!("FixedOffset should never produce None or Ambiguous");
        }
    }
    
    // FixedOffset is simple but doesn't model real-world timezones
    // Real timezones have DST transitions that create ambiguity
}
 
fn named_timezone_has_dst() {
    // Named timezones (chrono-tz) model DST
    
    use chrono_tz::America::New_York;
    
    // Same time as above, but with DST-aware timezone
    let ambiguous_time = NaiveDate::from_ymd_opt(2023, 11, 5).unwrap()
        .and_hms_opt(1, 30, 0).unwrap();
    
    let result = ambiguous_time.and_local_timezone(New_York);
    
    // This WILL be ambiguous!
    assert!(matches!(result, LocalResult::Ambiguous(_, _)));
}

FixedOffset never produces ambiguous or nonexistent times; named timezones do.

Practical Example: User Input Handling

use chrono::{NaiveDateTime, TimeZone, LocalResult};
use chrono_tz::America::New_York;
 
fn parse_user_datetime(input: &str) -> Result<chrono::DateTime<chrono_tz::Tz>, String> {
    // Parse user input as naive datetime
    let naive = NaiveDateTime::parse_from_str(input, "%Y-%m-%d %H:%M:%S")
        .map_err(|e| format!("Invalid datetime format: {}", e))?;
    
    // Convert to timezone-aware datetime
    match naive.and_local_timezone(New_York) {
        LocalResult::Single(dt) => {
            // Unambiguous - good to use
            Ok(dt)
        }
        LocalResult::None => {
            Err("The specified time does not exist (occurs during DST spring forward). \
                 Please choose a time after 3:00 AM.".to_string())
        }
        LocalResult::Ambiguous(earliest, latest) => {
            // Need user input or policy decision
            Err(format!(
                "Ambiguous time during DST transition. \
                 Could be {} (first occurrence) or {} (second occurrence). \
                 Please specify with timezone offset.",
                earliest, latest
            ))
        }
    }
}
 
fn handle_appointment() {
    // User wants to schedule at 2:30 AM on March 12 (doesn't exist)
    match parse_user_datetime("2023-03-12 02:30:00") {
        Ok(dt) => println!("Scheduled: {}", dt),
        Err(e) => {
            println!("Cannot schedule: {}", e);
            // User needs to choose a different time
        }
    }
    
    // User wants to schedule at 1:30 AM on November 5 (ambiguous)
    match parse_user_datetime("2023-11-05 01:30:00") {
        Ok(dt) => println!("Scheduled: {}", dt),
        Err(e) => {
            println!("Cannot schedule: {}", e);
            // Need clarification: EDT or EST?
        }
    }
}

User-facing applications must handle None and Ambiguous cases.

Database Storage Considerations

use chrono::{DateTime, NaiveDateTime, TimeZone, Utc};
use chrono_tz::America::New_York;
 
fn storage_best_practice() {
    // Problem: Local times can be ambiguous or nonexistent
    
    let ambiguous = NaiveDate::from_ymd_opt(2023, 11, 5).unwrap()
        .and_hms_opt(1, 30, 0).unwrap();
    
    // Bad: Storing naive time loses timezone context
    // Cannot reliably convert back
    
    // Better: Store as UTC
    let utc_time: DateTime<Utc> = Utc::now();  // UTC is never ambiguous
    
    // When user provides local time:
    // 1. Convert to UTC immediately (resolving ambiguity if needed)
    // 2. Store UTC time
    // 3. Convert to local time only for display
    
    // Example: Convert local to UTC
    fn local_to_utc(local: NaiveDateTime, tz: chrono_tz::Tz) -> Option<DateTime<Utc>> {
        match local.and_local_timezone(tz) {
            LocalResult::Single(dt) => Some(dt.with_timezone(&Utc)),
            LocalResult::None => {
                // Handle nonexistent time
                // Option 1: Advance to next valid time
                // Option 2: Return error
                None
            }
            LocalResult::Ambiguous(earliest, latest) => {
                // Handle ambiguous time
                // Option 1: Choose earliest
                // Option 2: Choose latest
                // Option 3: Return error
                // Option 4: Ask user
                Some(latest.with_timezone(&Utc))  // Default to latest
            }
        }
    }
}

Store times in UTC to avoid ambiguity issues.

Using chrono_tz for DST-Aware Timezones

use chrono::{NaiveDateTime, TimeZone};
use chrono_tz::{America::New_York, Europe::London, Asia::Tokyo};
 
fn timezone_examples() {
    // Different timezones have different DST rules
    
    // US Eastern: DST March-November
    let us_ambiguous = NaiveDate::from_ymd_opt(2023, 11, 5).unwrap()
        .and_hms_opt(1, 30, 0).unwrap()
        .and_local_timezone(New_York);
    
    // UK: DST March-October
    let uk_ambiguous = NaiveDate::from_ymd_opt(2023, 10, 29).unwrap()
        .and_hms_opt(1, 30, 0).unwrap()
        .and_local_timezone(London);
    
    // Japan: No DST (always unambiguous)
    let jp_time = NaiveDate::from_ymd_opt(2023, 11, 5).unwrap()
        .and_hms_opt(1, 30, 0).unwrap()
        .and_local_timezone(Tokyo);
    
    // Japan has no DST - always Single
    assert!(matches!(jp_time, LocalResult::Single(_)));
    
    // US and UK have DST - can be Ambiguous or None
    assert!(matches!(us_ambiguous, LocalResult::Ambiguous(_, _)));
    assert!(matches!(uk_ambiguous, LocalResult::Ambiguous(_, _)));
}
 
fn checking_dst_status() {
    use chrono_tz::America::New_York;
    
    // You can check if a timezone has DST
    let dt = chrono::Utc::now().with_timezone(&New_York);
    
    // Offset tells you if DST is active
    let offset = dt.offset();
    println!("Current offset: {:?}", offset);
    
    // Named timezone offsets encode DST info
}

Different timezones have different DST rules; some have no DST at all.

Handling Ambiguity in Libraries

use chrono::{NaiveDateTime, TimeZone, DateTime};
use chrono_tz::Tz;
 
// A robust datetime parsing function with DST handling
 
#[derive(Debug)]
enum DstResolution {
    Earliest,
    Latest,
    Reject,
}
 
fn parse_local_datetime(
    naive: NaiveDateTime,
    tz: Tz,
    resolution: DstResolution,
) -> Result<DateTime<Tz>, String> {
    match naive.and_local_timezone(tz) {
        LocalResult::Single(dt) => Ok(dt),
        LocalResult::None => {
            Err(format!(
                "Time {} does not exist in timezone {} (DST spring forward)",
                naive, tz
            ))
        }
        LocalResult::Ambiguous(earliest, latest) => {
            match resolution {
                DstResolution::Earliest => Ok(earliest),
                DstResolution::Latest => Ok(latest),
                DstResolution::Reject => {
                    Err(format!(
                        "Time {} is ambiguous in timezone {} (DST fall back). \
                         Could be {} or {}",
                        naive, tz, earliest, latest
                    ))
                }
            }
        }
    }
}
 
fn example_usage() {
    use chrono_tz::America::New_York;
    
    let ambiguous = NaiveDate::from_ymd_opt(2023, 11, 5).unwrap()
        .and_hms_opt(1, 30, 0).unwrap();
    
    // Use earliest (first occurrence before fall back)
    let earliest = parse_local_datetime(ambiguous, New_York, DstResolution::Earliest);
    
    // Use latest (second occurrence after fall back)
    let latest = parse_local_datetime(ambiguous, New_York, DstResolution::Latest);
    
    // Reject ambiguous
    let rejected = parse_local_datetime(ambiguous, New_York, DstResolution::Reject);
}

A helper function can encapsulate DST resolution policy.

Synthesis

Core behavior:

// and_local_timezone returns LocalResult with three cases:
match naive_dt.and_local_timezone(tz) {
    LocalResult::None => {
        // Local time does not exist (DST spring forward gap)
        // Example: 2:30 AM on DST transition day
    }
    LocalResult::Single(dt) => {
        // Unambiguous: maps to exactly one UTC time
        // Example: Most normal times
    }
    LocalResult::Ambiguous(earliest, latest) => {
        // Ambiguous: occurs twice (DST fall back overlap)
        // Example: 1:30 AM on fall back day
        // earliest: first occurrence (still DST)
        // latest: second occurrence (standard time)
    }
}

Convenience methods:

Method	Unambiguous	Ambiguous	Nonexistent
`.single()`	`Some(dt)`	`None`	`None`
`.earliest()`	`Some(dt)`	`Some(first)`	`None`
`.latest()`	`Some(dt)`	`Some(last)`	`None`

Key points:

LocalResult::None: Times that don't exist because clocks jumped forward (spring DST transition)
LocalResult::Single: Normal times with one unique UTC representation
LocalResult::Ambiguous: Times that occur twice because clocks fell back (fall DST transition)
FixedOffset never produces None or Ambiguous: No DST transitions
Named timezones (chrono-tz) model DST correctly: Produces all three cases
UTC is always unambiguous: Consider storing as UTC and converting for display

Best practices:

// For user input:
// - Handle all three LocalResult cases explicitly
// - Provide clear error messages for None/Ambiguous
 
// For storage:
// - Convert to UTC before storage
// - Resolve ambiguity at input time
// - Store the UTC representation
 
// For display:
// - Convert from UTC to local timezone
// - Never have ambiguity issues (UTC -> local is always well-defined)

Key insight: and_local_timezone forces explicit handling of DST edge cases through the LocalResult type, preventing silent bugs where a naive local time might be interpreted incorrectly. The three-way enum (None, Single, Ambiguous) models the reality of local time in DST-aware timezones: some times don't exist (skipped during spring forward), some exist once (normal times), and some exist twice (repeated during fall back). This design requires developers to think about and handle these cases explicitly, whether by rejecting invalid times, choosing a default resolution strategy, or asking users for clarification. The alternative—silently picking one interpretation—would lead to subtle bugs where events are scheduled at the wrong time or historical records are misinterpreted.

How does chrono::NaiveDateTime::and_local_timezone handle ambiguous local times during daylight saving transitions?