Crate croner

Source
Expand description

§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

§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)
// │ │ │ │ │ │
// * * * * * *
FieldRequiredAllowed valuesAllowed special charactersRemarks
SecondsOptional0-59* , - / ?
MinutesYes0-59* , - / ?
HoursYes0-23* , - / ?
Day of MonthYes1-31* , - / ? L W
MonthYes1-12 or JAN-DEC* , - / ?
Day of WeekYes0-7 or SUN-MON* , - / ? # L0 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