Crate croner

Croner

Croner is a fully-featured, lightweight, and efficient Rust library designed for parsing and evaluating cron patterns.

Features

• Parses a wide range of cron expressions, including extended formats.
• Generates human-readable descriptions of cron patterns.
• Evaluates cron patterns to calculate upcoming and previous execution times.
• Supports time zone-aware scheduling.
• Offers granularity up to seconds for precise task scheduling.
• Compatible with the chrono library for dealing with date and time in Rust.

Crate Features

• serde: Enables serde::Serialize and serde::Deserialize implementations for Cron. This feature is disabled by default.

Example

The following example demonstrates how to use Croner to parse a cron expression and find the next and previous occurrences.

use std::str::FromStr as _;

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

// Parse a cron expression to find occurrences at 00:00 on Friday
let cron = Cron::from_str("0 0 * * FRI").expect("Successful parsing");
let now = Utc::now();

// Get the next occurrence from the current time
let next = cron.find_next_occurrence(&now, false).unwrap();

// Get the previous occurrence from the current time
let previous = cron.find_previous_occurrence(&now, false).unwrap();

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

println!(
    "Pattern \"{}\" matched previously at {}",
    cron.pattern.to_string(),
    previous
);

In this example, Cron::from_str("0 0 * * FRI") creates a new Cron instance for the pattern that represents every Friday at midnight. The find_next_occurrence method calculates the next time this pattern will be true from the current moment.

The false argument in find_next_occurrence specifies that the current time is not included in the calculation, ensuring that only future occurrences are considered.

Describing a Pattern

Croner can also generate a human-readable, English description of a cron pattern. This is highly useful for displaying schedule information in a UI or for debugging complex patterns.

The .describe() method returns a String detailing what the schedule means.

Getting Started

To start using Croner, add it to your project’s Cargo.toml and follow the examples to integrate cron pattern parsing and scheduling into your application.

Pattern

The expressions used by Croner are very similar to those of Vixie Cron, but with a few additions as outlined below:

// ┌──────────────── (optional) second (0 - 59)
// │ ┌────────────── minute (0 - 59)
// │ │ ┌──────────── hour (0 - 23)
// │ │ │ ┌────────── day of month (1 - 31)
// │ │ │ │ ┌──────── month (1 - 12, JAN-DEC)
// │ │ │ │ │ ┌────── day of week (0 - 6, SUN-Mon)
// │ │ │ │ │ │       (0 to 6 are Sunday to Saturday; 7 is Sunday, the same as 0)
// │ │ │ │ │ │
// * * * * * *

Field	Required	Allowed values	Allowed special characters	Remarks
Seconds	Optional	0-59	* , - / ?
Minutes	Yes	0-59	* , - / ?
Hours	Yes	0-23	* , - / ?
Day of Month	Yes	1-31	* , - / ? L W
Month	Yes	1-12 or JAN-DEC	* , - / ?
Day of Week	Yes	0-7 or SUN-MON	* , - / ? # L	0 to 6 are Sunday to Saturday, 7 is Sunday, the same as 0. ‘#’ is used to specify the nth weekday

For more information, refer to the full README.

Modules

describe

errors

parser

Parser for Cron patterns.

Structs

Cron

CronIterator

Enums

Direction

JobType

Categorizes a cron pattern as either a Fixed-Time Job or an Interval/Wildcard Job. This is used to apply specific Daylight Saving Time (DST) transition rules.

TimeComponent

Constants

YEAR_LOWER_LIMIT

Sets the lower year limit to 1 AD/CE. This is a pragmatic choice to avoid the complexities of year 0 (1 BCE) and pre-CE dates, which involve different calendar systems and are outside the scope of a modern scheduling library.

YEAR_UPPER_LIMIT

Safeguard to prevent infinite loops when searching for future occurrences of a cron pattern that may never match. It ensures that the search function will eventually terminate and return an error instead of running indefinitely.

Functions

from_naive