Cron

https://github.com/zslayton/cron
Admin
A cron expression parser that works with stable Rust v1.28.0, allowing parsing and scheduling based...
Tokens:38,508
Snippets:275
Trust Score:8.4
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### is_all usage example

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Example using is_all to check if a unit matches all ordinals. The schedule is '* * * 1,15 * * *' and the example asserts that days_of_month is not all, but months is all.

```rust
use cron::{Schedule, TimeUnitSpec};
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("* * * 1,15 * * *").unwrap();
    assert_eq!(false, schedule.days_of_month().is_all());
    assert_eq!(true, schedule.months().is_all());
}

```

--------------------------------

### serde usage example with Cargo.toml

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Example of using serde with Schedule, including Cargo.toml feature and a Job struct.

```rust
// Cargo.toml
// cron = { version = "0.17", features = ["serde"] }

use cron::Schedule;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Job {
    name: String,
    schedule: Schedule,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let job: Job = serde_json::from_str(r#"{"name":"nightly","schedule":"@daily"}"#)?;
    let json = serde_json::to_string(&job)?;
    println!("{json}");
    Ok(())
}
```

--------------------------------

### count usage example

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Example using count to get the number of days of month in a schedule. The schedule is '* * * 1,15 * * *' and the example asserts that the count is 2.

```rust
use cron::{Schedule, TimeUnitSpec};
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("* * * 1,15 * * *").unwrap();
    assert_eq!(2, schedule.days_of_month().count());
}

```

--------------------------------

### Schedule::after usage example

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Example using Schedule::after with a business-hours cron expression to find the next 9am on a weekday after a given start time.

```rust
use cron::Schedule;
use chrono::offset::TimeZone;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("0 0 9 * * Mon-Fri *").unwrap();
    let start = Utc.with_ymd_and_hms(2023, 1, 2, 12, 0, 0).unwrap(); // Mon 12:00 UTC
    let next = schedule.after(&start).next().unwrap();
    println!("next business-day 9am: {}", next.to_rfc3339());
}
```

--------------------------------

### Schedule::after_owned usage example

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Example using Schedule::after_owned with a monthly cron expression to get the next month start after the current time.

```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("0 0 0 1 * * *").unwrap();
    let iter = schedule.after_owned(Utc::now());
    println!("next month starts: {:?}", iter.next());
}
```

--------------------------------

### Example: forward and backward iteration with Schedule::after

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule-iterators.md

Shows using next() for forward iteration and next_back() for backward iteration from the same anchor. The example prints the previous and next fire times.

```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("0 30 9 * * * *").unwrap();
    let now = Utc::now();

    // Forward from now
    let mut iter = schedule.after(&now);
    let next_1 = iter.next().unwrap();
    let next_2 = iter.next().unwrap();

    // Backward from now
    let mut rev = schedule.after(&now);
    let prev = rev.next_back().unwrap();
    println!("previous: {prev}, next: {next_1}, next2: {next_2}");
}
```

--------------------------------

### iter usage example

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Example using iter to iterate over months in a schedule. The schedule is '* * * 5-8 * *' and the example asserts that the iterator yields 5, 6, 7, 8, then None.

```rust
use cron::{Schedule, TimeUnitSpec};
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("* * * 5-8 * *").unwrap();
    let mut summer = schedule.months().iter();
    assert_eq!(Some(5), summer.next());
    assert_eq!(Some(6), summer.next());
    assert_eq!(Some(7), summer.next());
    assert_eq!(Some(8), summer.next());
    assert_eq!(None, summer.next());
}

```

--------------------------------

### Using From<Schedule> for String

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Example of converting a Schedule to a String using the From implementation.

```rust
use cron::Schedule;
use std::str::FromStr;

let schedule = Schedule::from_str("* 1,2,3 * * * *").unwrap();
let text: String = schedule.into();
assert_eq!(text, "* 1,2,3 * * * *");
```

--------------------------------

### range usage example

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Example using range to iterate over days of month within a bounded range. The schedule is '* * * 1,15 * * *' and the example asserts that the iterator yields 15 then None.

```rust
use cron::{Schedule, TimeUnitSpec};
use std::ops::Bound::{Included, Excluded};
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("* * * 1,15 * * *").unwrap();
    let mut paydays = schedule.days_of_month().range((Included(10, Included(20)));
    assert_eq!(Some(15), paydays.next());
    assert_eq!(None, paydays.next());
}

```

--------------------------------

### Using source

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Example showing that source() returns the exact expression string, including whitespace.

```rust
use cron::Schedule;
use std::str::FromStr;

fn main() {
    let s = Schedule::from_str("  0 0  * * * * *  ").unwrap();
    assert_eq!(s.source(), "  0 0  * * * * *  ");
}
```

--------------------------------

### Schedule::upcoming usage example

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Example using Schedule::upcoming with a cron expression '0 0,30 * * * * *' to print the next four matching times in UTC.

```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("0 0,30 * * * * *").unwrap();
    for datetime in schedule.upcoming(Utc).take(4) {
        println!("{}", datetime.to_rfc3339());
    }
}
```

--------------------------------

### Schedule::includes usage example

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Example using Schedule::includes with a daily 9:30 cron expression to test a specific datetime, printing 'matches: true'.

```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("0 30 9 * * * *").unwrap();
    let today_0930 = Utc.with_ymd_and_hms(2024, 5, 1, 9, 30, 0).unwrap();
    println!("matches: {}", schedule.includes(today_0930)); // true
}
```

--------------------------------

### Basic usage example for OwnedScheduleIterator

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule-iterators.md

Creates a schedule from a cron expression and an OwnedScheduleIterator, then prints the next midnight. The iterator is created with Utc::now() as the starting datetime.

```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("0 0 0 * * * *").unwrap();
    let iter = OwnedScheduleIterator::new(schedule, Utc::now());
    println!("next midnight: {:?}", iter.next());
}
```

--------------------------------

### Example: using rev() with Schedule::upcoming

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule-iterators.md

Shows using DoubleEndedIterator's rev() to get the five most recent hourly fire times from an upcoming iterator.

```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("@hourly").unwrap();
    // The five most recent hourly fire times
    for dt in schedule.upcoming(Utc).rev().take(5) {
        println!("{}", dt.to_rfc3339());
    }
}
```

--------------------------------

### Using time-unit accessors

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Example showing how to use the years() accessor to count, check inclusion, and iterate over a range of years.

```rust
use cron::{Schedule, TimeUnitSpec};
use std::ops::Bound::{Included, Excluded};
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("* * * * * * 2015-2044").unwrap();
    println!("years in range: {}", schedule.years().count()); // 30
    println!("2015 included: {}", schedule.years().includes(2015)); // true
    for y in schedule.years().range((Included(2020), Excluded(2023))) {
        println!("{y}");
    }
}
```

--------------------------------

### Simulate fire-time calendar with includes, range, and count

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Rust example using cron::Schedule and TimeUnitSpec to parse a cron expression and query minute counts, day-of-week inclusion, and hour ranges. Demonstrates the minutes().count(), days_of_week().includes(7), and hours().range(..=11) methods.

```rust
use cron::{Schedule, TimeUnitSpec};
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("0 15,45 6-18 * * Mon-Fri *").unwrap();

    // How many distinct minutes fire per hour?
    println!("minutes/hour: {}", schedule.minutes().count()); // 2

    // Is Sunday (7) ever a fire day?
    println!("sundays scheduled: {}", schedule.days_of_week().includes(7)); // false

    // Hours in the morning (0-11):
    for h in schedule.hours().range(..=11) {
        println!("morning fire hour: {h}");
    }
}
```

--------------------------------

### Schedule::after

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Like `upcoming`, but starts from an explicitly supplied starting datetime. The first item yielded is the first schedule match strictly after `after` (candidates `<= after` are skipped).

```APIDOC
## Schedule::after

### Description
Like `upcoming`, but starts from an explicitly supplied starting datetime. The first item yielded is the first schedule match strictly after `after` (candidates `<= after` are skipped).

### Method
`pub fn after<Z>(&self, after: &DateTime<Z>) -> ScheduleIterator<'_, Z> where Z: TimeZone`

### Parameters
- `after` (&chrono::DateTime<Z>) - Required - Starting datetime; first result is strictly greater than this value

### Returns
`ScheduleIterator<'_, Z>`.

### Example
```rust
use cron::Schedule;
use chrono::offset::TimeZone;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("0 0 9 * * Mon-Fri *").unwrap();
    let start = Utc.with_ymd_and_hms(2023, 1, 2, 12, 0, 0).unwrap(); // Mon 12:00 UTC
    let next = schedule.after(&start).next().unwrap();
    println!("next business-day 9am: {}", next.to_rfc3339());
}
```
```

--------------------------------

### Error handling example for OwnedScheduleIterator

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule-iterators.md

Shows explicit error handling when parsing a cron expression. The new constructor never fails; invalid expressions fail at the FromStr step. The example iterates over the first three matches and prints them in RFC3339 format.

```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = match Schedule::from_str("not a cron expression") {
        Ok(s) => s,
        Err(e) => {
            eprintln!("could not build schedule: {e}");
            return;
        }
    };
    let mut iter = OwnedScheduleIterator::new(schedule, Utc::now());
    for dt in iter.by_ref().take(3) {
        println!("> {}", dt.to_rfc3339());
    }
}
```

--------------------------------

### Schedule::upcoming_owned usage example

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Example using Schedule::upcoming_owned with '@daily' to create a 'static iterator that can be moved or stored without lifetime constraints.

```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("@daily").unwrap();
    // 'static iterator: can be moved or stored without lifetime constraints
    let iter = schedule.upcoming_owned(Utc);
    for datetime in iter.take(3) {
        println!("{}", datetime.to_rfc3339());
    }
}
```

--------------------------------

### Query state machines: NextAfterQuery and PrevFromQuery

Source: https://github.com/zslayton/cron/blob/master/_autodocs/types.md

Internal query state machines for the `cron` crate. `NextAfterQuery` seeds forward scan lower bounds at the starting datetime; `PrevFromQuery` subtracts one second when `timestamp_subsec_nanos() == 0` to include exact-boundary matches in backward iteration. Used by `Schedule::next_after`.

```rust
pub struct NextAfterQuery<Z: TimeZone> { initial_datetime, first_month, first_day_of_month, first_hour, first_minute, first_second }
pub struct PrevFromQuery<Z: TimeZone>  { initial_datetime, first_month, first_day_of_month, first_hour, first_minute, first_second }
```

--------------------------------

### OwnedScheduleIterator::new

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule-iterators.md

Creates a new OwnedScheduleIterator seeded at a starting datetime. The first next() returns the first match strictly after the starting datetime, and the first next_back() returns the first match strictly before it.

```APIDOC
## OwnedScheduleIterator::new

### Description
Creates a new OwnedScheduleIterator seeded at a starting datetime. The first next() returns the first match strictly after the starting datetime, and the first next_back() returns the first match strictly before it.

### Method
new

### Signature
pub fn new(schedule: Schedule, starting_datetime: DateTime<Z>) -> Self

### Parameters
- **schedule** (Schedule) - Required - Owned schedule to iterate
- **starting_datetime** (DateTime<Z>) - Required - Anchor; first next() returns the first match strictly after it; first next_back() the first match strictly before it

### Returns
Self — an OwnedScheduleIterator<Z> seeded at starting_datetime.

### Example
```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("0 0 0 * * * *").unwrap();
    let iter = OwnedScheduleIterator::new(schedule, Utc::now());
    println!("next midnight: {:?}", iter.next());
}
```
```

--------------------------------

### Using timeunitspec_eq

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Example demonstrating that timeunitspec_eq compares parsed fields, allowing structurally equivalent expressions to compare equal even when PartialEq does not.

```rust
use cron::Schedule;
use std::str::FromStr;

fn main() {
    let a = Schedule::from_str("@weekly").unwrap();
    let b = Schedule::from_str("0 0 0 * * 1 *").unwrap();
    assert_ne!(a, b);   // PartialEq compares source strings
    assert!(a.timeunitspec_eq(&b)); // fields are equal
}
```

--------------------------------

### Schedule::after signature

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Method signature for Schedule::after, which returns an iterator starting from a supplied datetime, skipping candidates <= after.

```rust
pub fn after<Z>(&self, after: &DateTime<Z>) -> ScheduleIterator<'_, Z>
where
    Z: TimeZone,
```

--------------------------------

### OwnedScheduleIterator::new constructor signature

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule-iterators.md

Signature for the new constructor. It takes an owned Schedule and a starting DateTime<Z>, and returns an OwnedScheduleIterator<Z> seeded at that datetime.

```rust
pub fn new(schedule: Schedule, starting_datetime: DateTime<Z>) -> Self
```

--------------------------------

### Enable serde feature in Cargo.toml

Source: https://github.com/zslayton/cron/blob/master/_autodocs/configuration.md

Shows how to enable the `serde` feature when adding the `cron` crate as a dependency. Use `cargo add cron --features serde` as an alternative.

```toml
[dependencies]
cron = { version = "0.17", features = ["serde"] }
```

--------------------------------

### serde Serialize and Deserialize implementations

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Shows the serde implementations for Schedule, serializing as a string and deserializing by re-parsing.

```rust
#[cfg(feature = "serde")]
impl Serialize for Schedule  // src/schedule.rs:695
// delegates to serializer.serialize_str(self.source())

#[cfg(feature = "serde")]
impl<'de> Deserialize<'de> for Schedule  // src/schedule.rs:705
// deserializer.deserialize_string(ScheduleVisitor)
```

--------------------------------

### PartialEq implementation

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Shows the PartialEq implementation that compares source strings, making equality source-string equality.

```rust
impl PartialEq for Schedule {  // src/schedule.rs:507
    fn eq(&self, other: &Schedule) -> bool { self.source == other.source }
}
```

--------------------------------

### std::fmt::Display implementation

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Shows the Display implementation that writes self.source, making Display output equal the original expression text.

```rust
impl Display for Schedule  // src/schedule.rs:501
```

--------------------------------

### Schedule::try_from (for Cow<'_, str>)

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Attempts to convert a `Cow<'_, str>` into a `Schedule`. Returns a `Result` with an `Error` on failure.

```APIDOC
## Schedule::try_from (for Cow<'_, str>)

### Description
Attempts to convert a `Cow<'_, str>` into a `Schedule`. Returns a `Result` with an `Error` on failure.

### Method
`try_from`

### Signature
```rust
impl TryFrom<Cow<'_, str>> for Schedule {
    type Error = Error;
}
```

### Parameters
- `expression` (`Cow<'_, str>`) - Required - A cron expression: 6 fields (`seconds minutes hours day-of-month month day-of-week`) or 7 fields (optional trailing `year`), or a shorthand (`@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`).

### Returns
`Result<Schedule, Error>` — `Ok` with the parsed schedule, or `Err(Error)` wrapping a `ErrorKind::Expression(String)` description of the parse failure.

### Errors
- `cron::error::Error` (`ErrorKind::Expression(..)`) - Any grammar violation, out-of-range ordinal, invalid name, invalid step, missing/extra fields, or trailing garbage.
```

--------------------------------

### From<Schedule> for String implementation

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Shows the trait implementation that converts a Schedule back into its source expression string.

```rust
impl From<Schedule> for String  // src/schedule.rs:19
```

--------------------------------

### FromStr and TryFrom implementations for Schedule

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

These trait implementations allow constructing a `Schedule` from a string, `String`, or `Cow<'_, str>`. All return `cron::error::Error` on failure.

```rust
impl FromStr for Schedule {
    type Err = Error;

    fn from_str(expression: &str) -> Result<Self, Self::Err>;
}

impl TryFrom<&str> for Schedule {
    type Error = Error;
}

impl TryFrom<String> for Schedule {
    type Error = Error;
}

impl TryFrom<Cow<'_, str>> for Schedule {
    type Error = Error;
}
```

--------------------------------

### Schedule::upcoming signature

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Method signature for Schedule::upcoming, which returns an iterator of matching DateTimes starting after the current time in the given timezone.

```rust
pub fn upcoming<Z>(&self, timezone: Z) -> ScheduleIterator<'_, Z>
where
    Z: TimeZone,
```

--------------------------------

### std::fmt::Display for Schedule

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Writes the schedule's source string; Display output equals the original expression text.

```APIDOC
## std::fmt::Display for Schedule

### Description
Writes `self.source`; `Display` output equals the original expression text.

### Method
`impl Display for Schedule`

### Parameters
- `self` (Schedule) - The schedule to format.

### Returns
- `fmt::Result` - The result of the formatting operation.

### Example
```rust
use cron::Schedule;
use std::str::FromStr;

let schedule = Schedule::from_str("* 1,2,3 * * * *").unwrap();
println!("{}", schedule); // prints "* 1,2,3 * * * *"
```
```

--------------------------------

### From<Schedule> for String

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Converts a Schedule back into its source expression string, identical to the source() method.

```APIDOC
## From<Schedule> for String

### Description
Converts the schedule back into its source expression string (same value as `source()`).

### Method
`impl From<Schedule> for String`

### Parameters
- `schedule` (Schedule) - The schedule to convert.

### Returns
- `String` - The original cron expression string.

### Example
```rust
use cron::Schedule;
use std::str::FromStr;

let schedule = Schedule::from_str("* 1,2,3 * * * *").unwrap();
let text: String = schedule.into();
assert_eq!(text, "* 1,2,3 * * * *");
```
```

--------------------------------

### Schedule::upcoming

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Returns an iterator that yields each DateTime matching the schedule, starting from the current time. The first yielded item is strictly after 'now' in the provided timezone's wall clock.

```APIDOC
## Schedule::upcoming

### Description
Provides an iterator which will return each `DateTime` that matches the schedule, starting from the current time (the first yielded item is strictly after "now", in the provided timezone's wall clock).

### Method
`pub fn upcoming<Z>(&self, timezone: Z) -> ScheduleIterator<'_, Z> where Z: TimeZone`

### Parameters
- `timezone` (Z: chrono::offset::TimeZone) - Required - Timezone in which fire times are computed and returned (`chrono::Utc`, `chrono::Local`, `chrono_tz::Tz`, …)

### Returns
`ScheduleIterator<'_, Z>` — a borrowing iterator yielding `chrono::DateTime<Z>`.

### Example
```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("0 0,30 * * * * *").unwrap();
    for datetime in schedule.upcoming(Utc).take(4) {
        println!("{}", datetime.to_rfc3339());
    }
}
```
```

--------------------------------

### Schedule::try_from (for String)

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Attempts to convert a `String` into a `Schedule`. Returns a `Result` with an `Error` on failure.

```APIDOC
## Schedule::try_from (for String)

### Description
Attempts to convert a `String` into a `Schedule`. Returns a `Result` with an `Error` on failure.

### Method
`try_from`

### Signature
```rust
impl TryFrom<String> for Schedule {
    type Error = Error;
}
```

### Parameters
- `expression` (`String`) - Required - A cron expression: 6 fields (`seconds minutes hours day-of-month month day-of-week`) or 7 fields (optional trailing `year`), or a shorthand (`@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`).

### Returns
`Result<Schedule, Error>` — `Ok` with the parsed schedule, or `Err(Error)` wrapping a `ErrorKind::Expression(String)` description of the parse failure.

### Errors
- `cron::error::Error` (`ErrorKind::Expression(..)`) - Any grammar violation, out-of-range ordinal, invalid name, invalid step, missing/extra fields, or trailing garbage.
```

--------------------------------

### Schedule::source signature

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Method signature for returning the original expression string.

```rust
pub fn source(&self) -> &str
```

--------------------------------

### PartialEq / Eq for Schedule

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Schedule equality is source-string equality. Use timeunitspec_eq for semantic equality.

```APIDOC
## PartialEq / Eq for Schedule

### Description
`Schedule` equality is **source-string equality**. Use `timeunitspec_eq` for semantic (parsed-field) equality. `Clone` and `Debug` are derived.

### Method
`impl PartialEq for Schedule`

### Parameters
- `self` (Schedule) - The first schedule.
- `other` (Schedule) - The second schedule.

### Returns
- `bool` - `true` if the source strings are equal, `false` otherwise.

### Example
```rust
use cron::Schedule;
use std::str::FromStr;

let s1 = Schedule::from_str("* * * * * *").unwrap();
let s2 = Schedule::from_str("* * * * * *").unwrap();
assert_eq!(s1, s2);
```
```

--------------------------------

### Schedule::minutes()

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Returns the minutes component of the schedule. The inclusive range is 0..=59 and no names are supported.

```APIDOC
## minutes()

### Description
Returns the minutes component of the schedule. The inclusive range is 0..=59 and no names are supported.

### Method
Accessor on `Schedule`

### Endpoint
`Schedule::minutes()`

### Parameters
None

### Response
Returns a `TimeUnitSpec` for minutes.

### Example
```rust
let schedule = Schedule::from_str("0 15,45 6-18 * * Mon-Fri *").unwrap();
let minutes = schedule.minutes();
println!("minutes/hour: {}", minutes.count()); // 2
```
```

--------------------------------

### Parsing a 7-field cron expression with Schedule::from_str

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Demonstrates parsing a 7-field cron expression with list, named range, and named day values. The `source()` method preserves the original expression text.

```rust
use cron::Schedule;
use std::str::FromStr;

fn main() -> Result<(), cron::error::Error> {
    // 7-field form with list, named range, and named day values
    let schedule = Schedule::from_str("0 30 9,12,15 1,15 May-Aug Mon,Wed,Fri 2018/2")?;
    println!("{}", schedule.source()); // preserves the original text
    Ok(())
}
```

--------------------------------

### Compare error Display output for cron parse errors

Source: https://github.com/zslayton/cron/blob/master/_autodocs/errors.md

Shows how to programmatically discriminate errors by comparing the Display output, since there are no error codes and the kind field is private. Asserts that the error message for a zero step is "range step cannot be zero".

```rust
use cron::Schedule;
use std::str::FromStr;

fn main() {
    match Schedule::from_str("*/0 * * * * * *") {
        Err(e) => {
            assert_eq!(e.to_string(), "range step cannot be zero");
        }
        Ok(_) => unreachable!(),
    }
}
```

--------------------------------

### Parsing a cron expression with Schedule::try_from

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Demonstrates using `TryFrom` to parse a simple cron expression. On failure, the error is printed with the message 'failed to parse: ...'.

```rust
use cron::Schedule;
use std::convert::TryFrom;

fn main() {
    match Schedule::try_from("* * * * *") {
        Ok(_) => println!("parsed"),
        Err(e) => println!("failed to parse: {e}"), // "failed to parse: ..." 
    }
}
```

--------------------------------

### Matching on error message string

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/error.md

Shows how to compare the `Display` output of an error to a known message string, since the `kind` field is private and `ErrorKind` does not implement `PartialEq`.

```rust
use cron::Schedule;
use std::str::FromStr;

fn main() {
    match Schedule::from_str("*/0 * * * * * *") {
        Err(e) => assert_eq!(e.to_string(), "range step cannot be zero"),
        Ok(_) => unreachable!(),
    }
}
```

--------------------------------

### Time-unit structs for seconds, minutes, hours, etc.

Source: https://github.com/zslayton/cron/blob/master/_autodocs/types.md

Seven time-unit structs that follow the same shape with Option<OrdinalSet> storage where None means all. They implement PartialEq, TimeUnitField, and have a lazy ALL static. They are internal, declared pub in private modules.

```rust
#[derive(Clone, Debug, Eq)]
pub struct Seconds { ordinals: Option<OrdinalSet> }      // 0..=59,   no names
pub struct Minutes { ordinals: Option<OrdinalSet> }      // 0..=59,   no names
pub struct Hours   { ordinals: Option<OrdinalSet> }      // 0..=23,   no names
pub struct DaysOfMonth { ordinals: Option<OrdinalSet> }  // 1..=31,   no names, accepts '?'
pub struct Months  { ordinals: Option<OrdinalSet> }      // 1..=12,   Jan..December (case-insensitive, PHF map src/time_unit/months.rs:6)
pub struct DaysOfWeek { ordinals: Option<OrdinalSet> }   // 1..=7 (Sun=1), Sun..Saturday, '?'; PHF map src/time_unit/days_of_week.rs:6
pub struct Years   { ordinals: Option<OrdinalSet> }      // 1970..=2100, no names
```

--------------------------------

### Schedule::days_of_week()

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Returns the days of week component of the schedule. The inclusive range is 1..=7 (Sunday=1, Saturday=7) and supports case-insensitive names Sun/Sunday through Sat/Saturday, with Tue/Tues and Thu/Thurs abbreviations.

```APIDOC
## days_of_week()

### Description
Returns the days of week component of the schedule. The inclusive range is 1..=7 (Sunday=1, Saturday=7) and supports case-insensitive names Sun/Sunday through Sat/Saturday, with Tue/Tues and Thu/Thurs abbreviations.

### Method
Accessor on `Schedule`

### Endpoint
`Schedule::days_of_week()`

### Parameters
None

### Response
Returns a `TimeUnitSpec` for days of week.

### Example
```rust
let schedule = Schedule::from_str("0 15,45 6-18 * * Mon-Fri *").unwrap();
println!("sundays scheduled: {}", schedule.days_of_week().includes(7)); // false
```
```

--------------------------------

### Schedule::months()

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Returns the months component of the schedule. The inclusive range is 1..=12 and supports case-insensitive names Jan/January through Dec/December.

```APIDOC
## months()

### Description
Returns the months component of the schedule. The inclusive range is 1..=12 and supports case-insensitive names Jan/January through Dec/December.

### Method
Accessor on `Schedule`

### Endpoint
`Schedule::months()`

### Parameters
None

### Response
Returns a `TimeUnitSpec` for months.

### Example
```rust
let schedule = Schedule::from_str("0 15,45 6-18 * * Mon-Fri *").unwrap();
let months = schedule.months();
```
```

--------------------------------

### Schedule::days_of_month()

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Returns the days of month component of the schedule. The inclusive range is 1..=31 and no names are supported.

```APIDOC
## days_of_month()

### Description
Returns the days of month component of the schedule. The inclusive range is 1..=31 and no names are supported.

### Method
Accessor on `Schedule`

### Endpoint
`Schedule::days_of_month()`

### Parameters
None

### Response
Returns a `TimeUnitSpec` for days of month.

### Example
```rust
let schedule = Schedule::from_str("0 15,45 6-18 * * Mon-Fri *").unwrap();
let days_of_month = schedule.days_of_month();
```
```

--------------------------------

### Schedule::seconds()

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Returns the seconds component of the schedule. The inclusive range is 0..=59 and no names are supported.

```APIDOC
## seconds()

### Description
Returns the seconds component of the schedule. The inclusive range is 0..=59 and no names are supported.

### Method
Accessor on `Schedule`

### Endpoint
`Schedule::seconds()`

### Parameters
None

### Response
Returns a `TimeUnitSpec` for seconds.

### Example
```rust
let schedule = Schedule::from_str("0 15,45 6-18 * * Mon-Fri *").unwrap();
let seconds = schedule.seconds();
```
```

--------------------------------

### Schedule::timeunitspec_eq

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Compares two schedules for equality based on their parsed time-unit fields, ignoring the original source strings.

```APIDOC
## Schedule::timeunitspec_eq

### Description
Equality of the *parsed fields* (not the source strings), allowing structurally equivalent expressions (e.g. `@weekly` vs `0 0 0 * * 1 *`) to compare equal.

### Method
`pub fn timeunitspec_eq(&self, other: &Schedule) -> bool`

### Parameters
- `other` (`&Schedule`) - Required - Schedule to compare field-by-field

### Returns
`bool` — `true` when the seven parsed time-unit fields of both schedules are equal.

### Example
```rust
use cron::Schedule;
use std::str::FromStr;

fn main() {
    let a = Schedule::from_str("@weekly").unwrap();
    let b = Schedule::from_str("0 0 0 * * 1 *").unwrap();
    assert_ne!(a, b);   // PartialEq compares source strings
    assert!(a.timeunitspec_eq(&b)); // fields are equal
}
```
```

--------------------------------

### Schedule::try_from (for &str)

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Attempts to convert a string slice into a `Schedule`. Returns a `Result` with an `Error` on failure.

```APIDOC
## Schedule::try_from (for &str)

### Description
Attempts to convert a string slice into a `Schedule`. Returns a `Result` with an `Error` on failure.

### Method
`try_from`

### Signature
```rust
impl TryFrom<&str> for Schedule {
    type Error = Error;
}
```

### Parameters
- `expression` (`&str`) - Required - A cron expression: 6 fields (`seconds minutes hours day-of-month month day-of-week`) or 7 fields (optional trailing `year`), or a shorthand (`@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`).

### Returns
`Result<Schedule, Error>` — `Ok` with the parsed schedule, or `Err(Error)` wrapping a `ErrorKind::Expression(String)` description of the parse failure.

### Errors
- `cron::error::Error` (`ErrorKind::Expression(..)`) - Any grammar violation, out-of-range ordinal, invalid name, invalid step, missing/extra fields, or trailing garbage.

### Example
```rust
use cron::Schedule;
use std::convert::TryFrom;

fn main() {
    match Schedule::try_from("* * * * *") {
        Ok(_) => println!("parsed"),
        Err(e) => println!("failed to parse: {e}"), // "failed to parse: ..." 
    }
}
```
```

--------------------------------

### Schedule::includes signature

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Method signature for Schedule::includes, which checks if a given DateTime matches the schedule.

```rust
pub fn includes<Z>(&self, date_time: DateTime<Z>) -> bool
where
    Z: TimeZone,
```

--------------------------------

### Schedule::source

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Returns the original expression string that the schedule was parsed from, verbatim.

```APIDOC
## Schedule::source

### Description
Returns the original expression string, verbatim (including whitespace as written).

### Method
`pub fn source(&self) -> &str`

### Parameters
None.

### Returns
`&str` — the exact expression this schedule was parsed from.

### Example
```rust
use cron::Schedule;
use std::str::FromStr;

fn main() {
    let s = Schedule::from_str("  0 0  * * * * *  ").unwrap();
    assert_eq!(s.source(), "  0 0  * * * * *  ");
}
```
```

--------------------------------

### serde Serialize for Schedule

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Serializes the schedule as a string containing the original cron expression.

```APIDOC
## serde Serialize for Schedule

### Description
Serializes the schedule as a string containing the original cron expression. This implementation is available with the `serde` feature.

### Method
`impl Serialize for Schedule`

### Parameters
- `self` (Schedule) - The schedule to serialize.
- `serializer` (S) - The serializer to use.

### Returns
- `Result<S::Ok, S::Error>` - The serialization result.

### Example
```rust
// Cargo.toml
// cron = { version = "0.17", features = ["serde"] }

use cron::Schedule;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Job {
    name: String,
    schedule: Schedule,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let job: Job = serde_json::from_str(r#"{"name":"nightly","schedule":"@daily"}"#)?;
    let json = serde_json::to_string(&job)?;
    println!("{json}");
    Ok(())
}
```
```

--------------------------------

### serde Deserialize for Schedule

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Deserializes a string into a Schedule by re-parsing it via Schedule::try_from, mapping parse failures to the deserializer's error type.

```APIDOC
## serde Deserialize for Schedule

### Description
Deserializes a string into a Schedule by re-parsing it via `Schedule::try_from` and maps parse failures to the deserializer's error type (`de::Error::custom`). Implemented using `deserialize_string`, so deserializers must be able to provide an owned `String` (or a `&str` that is cloned); this works with `postcard`, `serde_json`, and `serde_test`.

### Method
`impl<'de> Deserialize<'de> for Schedule`

### Parameters
- `deserializer` (D) - The deserializer to use.

### Returns
- `Result<Schedule, D::Error>` - The deserialized schedule or an error.

### Example
```rust
// Cargo.toml
// cron = { version = "0.17", features = ["serde"] }

use cron::Schedule;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Job {
    name: String,
    schedule: Schedule,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let job: Job = serde_json::from_str(r#"{"name":"nightly","schedule":"@daily"}"#)?;
    let json = serde_json::to_string(&job)?;
    println!("{json}");
    Ok(())
}
```
```

--------------------------------

### is_all method signature

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Signature for the is_all method, which returns true if this unit matches the entire set of supported ordinals.

```rust
fn is_all(&self) -> bool;

```

--------------------------------

### Parse cron expression and print upcoming fire times

Source: https://github.com/zslayton/cron/blob/master/README.md

Parses a cron expression with the cron crate and prints the next 10 fire times using Schedule::from_str and schedule.upcoming(Utc). The expression includes seconds, minutes, hours, day of month, month, day of week, and year fields. The output shows the expected UTC datetimes for the given expression.

```rust
use cron::Schedule;
use chrono::Utc;
use std::str::FromStr;

fn main() {
  //               sec  min   hour   day of month   month   day of week   year
  let expression = "0   30   9,12,15     1,15       May-Aug  Mon,Wed,Fri  2018/2";
  let schedule = Schedule::from_str(expression).unwrap();
  println!("Upcoming fire times:");
  for datetime in schedule.upcoming(Utc).take(10) {
    println!("-> {}", datetime);
  }
}

/*
Upcoming fire times:
-> 2018-06-01 09:30:00 UTC
-> 2018-06-01 12:30:00 UTC
-> 2018-06-01 15:30:00 UTC
-> 2018-06-15 09:30:00 UTC
-> 2018-06-15 12:30:00 UTC
-> 2018-06-15 15:30:00 UTC
-> 2018-08-01 09:30:00 UTC
-> 2018-08-01 12:30:00 UTC
-> 2018-08-01 15:30:00 UTC
-> 2018-08-15 09:30:00 UTC
*/
```

--------------------------------

### DoubleEndedIterator implementation for ScheduleIterator

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule-iterators.md

The DoubleEndedIterator implementation for ScheduleIterator. next_back() returns the first match strictly before the previous position, skipping candidates >= before.

```rust
impl<Z> DoubleEndedIterator for ScheduleIterator<'_, Z>
where
    Z: TimeZone,
{
    fn next_back(&mut self) -> Option<Self::Item>;
}
```

--------------------------------

### Schedule::years()

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Returns the years component of the schedule. The inclusive range is 1970..=2100 and no names are supported.

```APIDOC
## years()

### Description
Returns the years component of the schedule. The inclusive range is 1970..=2100 and no names are supported.

### Method
Accessor on `Schedule`

### Endpoint
`Schedule::years()`

### Parameters
None

### Response
Returns a `TimeUnitSpec` for years.

### Example
```rust
let schedule = Schedule::from_str("0 15,45 6-18 * * Mon-Fri *").unwrap();
let years = schedule.years();
```
```

--------------------------------

### Schedule::timeunitspec_eq signature

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Method signature for comparing two schedules by their parsed time-unit fields.

```rust
pub fn timeunitspec_eq(&self, other: &Schedule) -> bool
```

--------------------------------

### Time-unit accessors

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/schedule.md

Seven accessor methods that return a reference to a TimeUnitSpec for each time unit (years, months, days of month, days of week, hours, minutes, seconds).

```APIDOC
## Time-unit accessors

### Description
Returns a `&impl TimeUnitSpec` describing which ordinals of the respective time unit the schedule includes.

### Methods
- `pub fn years(&self) -> &impl TimeUnitSpec`
- `pub fn months(&self) -> &impl TimeUnitSpec`
- `pub fn days_of_month(&self) -> &impl TimeUnitSpec`
- `pub fn days_of_week(&self) -> &impl TimeUnitSpec`
- `pub fn hours(&self) -> &impl TimeUnitSpec`
- `pub fn minutes(&self) -> &impl TimeUnitSpec`
- `pub fn seconds(&self) -> &impl TimeUnitSpec`

### Parameters
None (all take `&self` only).

### Returns
`&impl TimeUnitSpec` — see the `TimeUnitSpec` trait for `includes`, `iter`, `range`, `count`, `is_all`.

### Example
```rust
use cron::{Schedule, TimeUnitSpec};
use std::ops::Bound::{Included, Excluded};
use std::str::FromStr;

fn main() {
    let schedule = Schedule::from_str("* * * * * * 2015-2044").unwrap();
    println!("years in range: {}", schedule.years().count()); // 30
    println!("2015 included: {}", schedule.years().includes(2015)); // true
    for y in schedule.years().range((Included(2020), Excluded(2023))) {
        println!("{y}");
    }
}
```
```

--------------------------------

### Schedule::hours()

Source: https://github.com/zslayton/cron/blob/master/_autodocs/api-reference/time-unit-spec.md

Returns the hours component of the schedule. The inclusive range is 0..=23 and no names are supported.

```APIDOC
## hours()

### Description
Returns the hours component of the schedule. The inclusive range is 0..=23 and no names are supported.

### Method
Accessor on `Schedule`

### Endpoint
`Schedule::hours()`

### Parameters
None

### Response
Returns a `TimeUnitSpec` for hours.

### Example
```rust
let schedule = Schedule::from_str("0 15,45 6-18 * * Mon-Fri *").unwrap();
for h in schedule.hours().range(..=11) {
    println!("morning fire hour: {h}");
}
```
```
Tokens:
Raw