v3.0.0

Croner 3.0 Release Notes

Version 3.0 is a significant release, introducing powerful new features, major API enhancements for improved safety and flexibility, and important bug fixes.

Breaking changes

• Support for optional years: The default configuration now allow for optional years, when combined with seconds in a 7-field pattern. Example: 0 30 23 * * FRI 2025-2026 (At 23:30, on Friday, in year 2025 and 2026). This is breaking because 7-part patterns would throw an error in previous versions, but is successfully parsed with the default configuration from 3.0.0. It's possible to emulate the previous behavior by disallowing years through configuration.

Major New Features

• Reverse Lookup: You can now search for previous occurrences of a cron pattern. The new find_previous_occurrence() method and iter_before() iterator allow for iterating backwards in time from a given point.
• Flexible Parser Configuration with Builder Pattern: The CronParser has been enhanced with a builder pattern (CronParser::builder()) for a more type-safe and explicit configuration. This allows you to precisely control:
  • How the seconds field is handled (Optional, Required, Disallowed).
  • Whether the year field is supported (Optional, Required, Disallowed).
  • The logical combination of Day-of-Month and Day-of-Week fields (dom_and_dow).
  • Support for forcing alternative (Quartz-style) weekdays.
• Logical AND for Day-of-Month and Day-of-Week with + modifier: Introduced the + prefix in the day-of-week field (e.g., 0 0 1 * +MON) to explicitly enforce a logical AND relationship between the day-of-month and day-of-week conditions, overriding the default OR behavior.
• EXPERIMENTAL Human-Readable Descriptions: Croner can now generate human-readable, English descriptions for any cron pattern using the new .describe() method. This feature is also extensible with internationalization support, demonstrated with an initial Swedish translation.

Enhancements

• Common Trait Implementation: Cron and CronPattern now implement common traits including Eq, PartialEq, Ord, PartialOrd, and Hash. This allows Cron instances to be reliably compared, sorted, and used in hash-based collections like HashMap.
• Robust Whitespace Parsing: The parser is now more robust and correctly handles leading, trailing, and mixed whitespace separators in cron patterns.
• Improved DST Handling: Fixed an issue where fixed-time jobs scheduled within a Daylight Saving Time (DST) spring forward gap would incorrectly skip to the next day. These jobs now execute immediately at the first valid time following the gap on the same calendar day, aligning with the OCPS and Vixie-cron behavior.
• Improved Specification Conformance: This release improves conformance with the draft Open Cron Pattern Specification (OCPS). This includes better handling of 5, 6, and 7-field patterns and special characters like L, #, and W. Validation logic has been refined to ensure that the ? wildcard is only permitted in the day-of-month and day-of-week fields, improving pattern integrity.

Bug Fixes

• Constrained Closest Weekday (W): The W modifier is now correctly constrained within the given month. The search for the closest weekday will no longer incorrectly cross into a previous or subsequent month.

Migrating to the New Parser Configuration

From this version on, the initialization of Cron instances has been updated to use a flexible builder pattern, which is more idiomatic to Rust, and provides greater control and type safety.

Previous Method (Before v3.0)

Previously, Cron was typically initialized directly from a string, which used a default parser configuration:

    // Parse cron expression
    let cron_all = Cron::new("18 * * * 5")
      // <options>
      .parse()
      .expect("Couldn't parse cron string");

New Recommended Method (v3.0 and later)

For v3.0 and later, there are two primary ways to construct a Cron object, depending on your needs.

1. Directly, using default settings: For simple cases that do not require special configuration, the Cron::from_str() method is the most convenient option.

   use std::str::FromStr as _;
   use croner::Cron;
   
   let cron = Cron::from_str("*/10 * * * *").unwrap();

2. With a configured parser: For custom behavior, the new builder pattern is the recommended approach.

   use croner::parser::{CronParser, Seconds};
   use croner::Cron;
   
   let parser = CronParser::builder()
       .seconds(Seconds::Disallowed) // Example: Only allow 5-part patterns
       .dom_and_dow(true)           // Example: require both day-of-month and day-of-week to match (Quartz Mode)
       .build();
   
   let cron = parser.parse("0 0 1 * MON").expect("Invalid cron pattern");

New Contributors

• A special thanks to @CardboardTurkey for their first contributions in this release!

Full Changelog: v2.2.0...v3.0.0

v2.2.0

What's Changed

• Add optional support for serde by @jakewmeyer in #15
• Fix panic on DST transition #16

New Contributors

• @jakewmeyer made their first contribution in #15

Full Changelog: v2.1.0...v2.2.0

v2.1.0

What's Changed

• impl Display for Cron and as_str to get the original pattern by @veeshi in #7

Full Changelog: v2.0.8...v2.1.0

v2.0.8

Changes

• Fixes #13, error when using '7' as Sunday in "Nth occurrence of weekday"

Full Changelog: v2.0.7...v2.0.8

v2.0.7

Changes

• Fixes #12, panic when passing 0 as weekday when using .with_alernative_weekdays()

Full Changelog: v2.0.6...v2.0.7

v2.0.6

What's Changed

• Make cron iterator public by @veeshi in #8
• Fix alias combined with with_seconds_required (issue #9) by @Hexagon in #10

New Contributors

• @veeshi made their first contribution in #8

Full Changelog: v2.0.5...v2.0.6

v2.0.5

Changes

• feat: added debug derive impl to Cron struct by @willmalcs in #5
• chore: Dependency update. Version bump. by @Hexagon in #6

New Contributors

• @willmalcs made their first contribution in #5

Full Changelog: v2.0.4...v2.0.5

v2.0.4

Changes

This release contains a minor update, exposing the errors module to the public interface.

Full Changelog: v2.0.3...v2.0.4

v2.0.3

Changes

Maintenance release focusing mainly on documentation updates and additional test cases.

Full Changelog: v2.0.2...v2.0.3

v2.0.2

Changes

• Added support for Quartz-style last occurrence of weekday '5L'
• Added tests ensuring that both 5#L and 5L works, and are only allowed in the day-of-week part
• Code cleanup
• Documentation improvements

Full Changelog: v2.0.1...v2.0.2