Struct Cron

Source

pub struct Cron {
    pub pattern: CronPattern,
}

Fields§

§pattern: CronPattern

Implementations§

Source §

impl Cron

Source

pub fn is_time_matching<Tz: TimeZone>( &self, time: &DateTime<Tz>, ) -> Result<bool, CronError>

Evaluates if a given DateTime matches the cron pattern.

The function checks each cron field (seconds, minutes, hours, day of month, month and year) against the provided DateTime to determine if it aligns with the cron pattern. Each field is checked for a match, and all fields must match for the entire pattern to be considered a match.

§Parameters

time: A reference to the DateTime<Tz> to be checked against the cron pattern.

§Returns

Ok(bool): true if time matches the cron pattern, false otherwise.
Err(CronError): An error if there is a problem checking any of the pattern fields against the provided DateTime.

§Errors

This method may return CronError if an error occurs during the evaluation of the cron pattern fields. Errors can occur due to invalid bit operations or invalid dates.

§Examples

use std::str::FromStr as _;

use croner::Cron;
use chrono::Utc;

// Parse cron expression
let cron: Cron = Cron::from_str("* * * * *").expect("Couldn't parse cron string");

// Compare to time now
let time = Utc::now();
let matches_all = cron.is_time_matching(&time).unwrap();

// Output results
println!("Time is: {}", time);
println!(
    "Pattern \"{}\" does {} time {}",
    cron.pattern.to_string(),
    if matches_all { "match" } else { "not match" },
    time
);

Source

pub fn find_next_occurrence<Tz: TimeZone>( &self, start_time: &DateTime<Tz>, inclusive: bool, ) -> Result<DateTime<Tz>, CronError>

Finds the next occurrence of a scheduled time that matches the cron pattern. starting from a given start_time. If inclusive is true, the search includes the start_time; otherwise, it starts from the next second.

This method performs a search through time, beginning at start_time, to find the next date and time that aligns with the cron pattern defined within the Cron instance. The search respects cron fields (seconds, minutes, hours, day of month, month, day of week) and iterates through time until a match is found or an error occurs.

§Parameters

start_time: A reference to a DateTime<Tz> indicating the start time for the search.
inclusive: A bool that specifies whether the search should include start_time itself.

§Returns

Ok(DateTime<Tz>): The next occurrence that matches the cron pattern.
Err(CronError): An error if the next occurrence cannot be found within a reasonable limit, if any of the date/time manipulations result in an invalid date, or if the cron pattern match fails.

§Errors

CronError::InvalidTime: If the start time provided is invalid or adjustments to the time result in an invalid date/time.
CronError::TimeSearchLimitExceeded: If the search exceeds a reasonable time limit. This prevents infinite loops in case of patterns that cannot be matched.
Other errors as defined by the CronError enum may occur if the pattern match fails at any stage of the search.

§Examples

use chrono::Utc;
use croner::{Cron, parser::{Seconds, CronParser}};

// Parse cron expression
let cron: Cron = CronParser::builder().seconds(Seconds::Required).build().parse("0 18 * * * 5").expect("Success");

// Get next match
let time = Utc::now();
let next = cron.find_next_occurrence(&time, false).unwrap();

println!(
    "Pattern \"{}\" will match next time at {}",
    cron.pattern.to_string(),
    next
);

Source

pub fn find_previous_occurrence<Tz: TimeZone>( &self, start_time: &DateTime<Tz>, inclusive: bool, ) -> Result<DateTime<Tz>, CronError>

Finds the previous occurrence of a scheduled time that matches the cron pattern.

Source

pub fn iter_from<Tz: TimeZone>( &self, start_from: DateTime<Tz>, direction: Direction, ) -> CronIterator<Tz> ⓘ

Creates a CronIterator starting from the specified time.

The search can be performed forwards or backwards in time.

§Arguments

start_from - A DateTime<Tz> that represents the starting point for the iterator.
direction - A Direction to specify the search direction.

§Returns

Returns a CronIterator<Tz> that can be used to iterate over scheduled times.

Source

pub fn iter_after<Tz: TimeZone>( &self, start_after: DateTime<Tz>, ) -> CronIterator<Tz> ⓘ

Creates a CronIterator starting after the specified time, in forward direction.

§Arguments

start_after - A DateTime<Tz> that represents the starting point for the iterator.

§Returns

Returns a CronIterator<Tz> that can be used to iterate over scheduled times.

Source

pub fn iter_before<Tz: TimeZone>( &self, start_before: DateTime<Tz>, ) -> CronIterator<Tz> ⓘ

Creates a CronIterator starting before the specified time, in backwards direction.

§Arguments

start_before - A DateTime<Tz> that represents the starting point for the iterator.

§Returns

Returns a CronIterator<Tz> that can be used to iterate over scheduled times.

Source

pub fn describe(&self) -> String

Returns a human-readable description of the cron pattern.

This method provides a best-effort English description of the cron schedule. Note: The cron instance must be parsed successfully before calling this method.

§Example

use croner::Cron;
use std::str::FromStr as _;

let cron = Cron::from_str("0 12 * * MON-FRI").unwrap();
println!("{}", cron.describe());
// Output: At on minute 0, at hour 12, on Monday,Tuesday,Wednesday,Thursday,Friday.

Source

pub fn describe_lang<L: Language>(&self, lang: L) -> String

Returns a human-readable description using a provided language provider.

§Arguments

lang - An object that implements the Language trait.

Source

pub fn determine_job_type(&self) -> JobType

Determines if the cron pattern represents a Fixed-Time Job or an Interval/Wildcard Job. A Fixed-Time Job has fixed (non-wildcard, non-stepped, single-value) Seconds, Minute, and Hour fields. Otherwise, it’s an Interval/Wildcard Job.

Source