cron

The Schedule iterator correctly handles ambiguous or non-existent times caused by Daylight Saving Time transitions. When using after(&dt) or nth_back(n), the library ensures that it does not panic when encountering times that fall within a DST gap or overlap.

For example, in a timezone like America/Chicago, an hourly schedule will correctly yield both instances of an hour that repeats during a fallback transition (e.g., 1 AM CDT followed by 1 AM CST).

use chrono_tz::Tz;
use cron::Schedule;

let schedule_tz: Tz = "America/Chicago".parse().unwrap();
let dt = schedule_tz.with_ymd_and_hms(2022, 11, 5, 23, 30, 0).unwrap();
let schedule = Schedule::from_str("0 0 * * * * *").unwrap();

// Iterating forward through a DST transition
let times = schedule
    .after(&dt)
    .map(|x| x.to_string())
    .take(5)
    .collect::<Vec<_>>();

// Expected behavior includes the repeated hour during fallback
// ["2022-11-06 00:00:00 CDT", "2022-11-06 01:00:00 CDT", "2022-11-06 01:00:00 CST", ...]

The Schedule struct allows you to find upcoming or previous occurrences of a cron expression. You can iterate through these occurrences using ScheduleIterator (which borrows the schedule) or OwnedScheduleIterator (which takes ownership of the schedule).

Key Methods

• upcoming<Z>(&self, timezone: Z) -> ScheduleIterator<'_, Z>: Returns an iterator starting with the next occurrence relative to the current time in the specified timezone.
• after<Z>(&self, after: &DateTime<Z>) -> ScheduleIterator<'_, Z>: Returns an iterator starting with the first occurrence strictly after the provided after timestamp.
• after_owned<Z>(&self, after: DateTime<Z>) -> OwnedScheduleIterator<Z>: Similar to after, but returns an iterator that owns the Schedule instance.
• upcoming_owned<Z>(&self, timezone: Z) -> OwnedScheduleIterator<Z>: Similar to upcoming, but returns an iterator that owns the Schedule instance.

Both iterator types implement Iterator and DoubleEndedIterator, allowing you to use .next() to go forward in time or .next_back() to go backward in time.

use chrono::{Utc, TimeZone};
use std::str::FromStr;

let expression = "0 0,30 0,6,12,18 1,15 Jan-March Thurs";
let schedule = Schedule::from_str(expression).unwrap();

// Get upcoming occurrences in UTC
let mut upcoming = schedule.upcoming(Utc);
while let Some(occurrence) = upcoming.next() {
    println!("Next occurrence: {}", occurrence);
}

// Iterate backwards from a specific point
let starting_point = Utc.with_ymd_and_hms(2023, 1, 1, 0, 0, 0).unwrap();
let mut backward = schedule.after(&starting_point).rev();
while let Some(prev) = backward.next() {
    println!("Previous occurrence: {}", prev);
}

Use NextAfterQuery::from(&DateTime<Z>) to create a query object used for finding the next scheduled occurrence after a specific point in time. The query tracks the initial datetime and manages lower bounds for time units (month, day, hour, minute, second) to ensure the search progresses forward correctly.

Key methods for navigating the search space include:

• year_lower_bound(): Returns the year of the initial datetime.
• month_lower_bound(): Returns the current month or the minimum possible month.
• day_of_month_lower_bound(): Returns the current day or the minimum possible day.
• hour_lower_bound(), minute_lower_bound(), second_lower_bound(): Return the current unit value or the minimum possible value.
• reset_month(), reset_day_of_month(), etc.: Resets the search bounds for a specific unit and its sub-units (e.g., resetting the month also resets the day, hour, minute, and second).

use chrono::TimeZone;
use cron::NextAfterQuery;

// Assuming 'dt' is a valid DateTime<Z>
let query = NextAfterQuery::from(&dt);
let year = query.year_lower_bound();
let month = query.month_lower_bound();

Use PrevFromQuery::from(&DateTime<Z>) to create a query object used for finding the previous scheduled occurrence relative to a specific point in time. If the provided datetime has sub-second precision, the query starts from that exact time; otherwise, it starts from one second prior.

Key methods for navigating the search space include:

• year_upper_bound(): Returns the year of the initial datetime.
• month_upper_bound(): Returns the current month or the maximum possible month.
• day_of_month_upper_bound(): Returns the current day or the maximum possible day.
• hour_upper_bound(), minute_upper_bound(), second_upper_bound(): Return the current unit value or the maximum possible value.
• reset_month(), reset_day_of_month(), etc.: Resets the search bounds for a specific unit and its sub-units (e.g., resetting the month also resets the day, hour, minute, and second).

use chrono::TimeZone;
use cron::PrevFromQuery;

// Assuming 'dt' is a valid DateTime<Z>
let query = PrevFromQuery::from(&dt);
let year = query.year_upper_bound();
let month = query.month_upper_bound();