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
serde
: Enablesserde::Serialize
andserde::Deserialize
implementations forCron
. 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§
Structs§
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.
- Time
Component
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.