Struct RecurrenceRule 

pub struct RecurrenceRule {
    pub kind: RuleKind,
    pub interval: Option<u32>,
    pub anchor: Option<String>,
    pub timezone: Option<Timezone>,
    pub expression: Option<String>,
    pub unit: Option<IntervalUnit>,
    pub extensions: BTreeMap<String, Value>,
}

A supported schedule definition (data-model.md §2).

Field literals are public so a surface can build a rule directly; the with_* builders exist for the common “start from a kind and add fields” case. Nothing here is executable: expression is text a CronParser interprets, and extensions is inert metadata.

Unknown metadata (T005)

A key this build does not interpret lands in RecurrenceRule::extensions and is written back on the next serialization. A newer tix that adds a cadence field writes it into the same record, and this build preserves it rather than silently dropping it on the next edit.

Why PartialEq and not Eq

extensions holds serde_yaml::Value, which carries floats and therefore has no Eq. Whole-struct equality is the priority; the missing Eq is the documented consequence.

Fields

kind: RuleKind

The supported family this rule names.

interval: Option<u32>

The cadence, where the family uses one.

anchor: Option<String>

The stable schedule origin, as a canonical YYYY-MM-DD date.

Required for every family: an origin is what makes a schedule deterministic, and inventing one from the inject context would be exactly the silent guess C-009 escalates.

timezone: Option<Timezone>

The explicit timezone policy, or None for a timezone-independent calendar rule.

expression: Option<String>

The cron-like expression; only meaningful for RuleKind::CronLike.

unit: Option<IntervalUnit>

The RuleKind::Interval unit.

extensions: BTreeMap<String, Value>

Metadata this build does not interpret, preserved verbatim.

Implementations

impl RecurrenceRule

pub fn new(kind: RuleKind) -> Self

A bare rule of kind, with no cadence fields and no extensions.

pub fn with_interval(self, interval: u32) -> Self

Set the cadence.

pub fn with_anchor(self, anchor: impl Into<String>) -> Self

Set the anchor, as a YYYY-MM-DD string.

pub fn with_timezone(self, timezone: Timezone) -> Self

Set the timezone policy.

pub fn with_expression(self, expression: impl Into<String>) -> Self

Set the cron-like expression.

pub fn with_unit(self, unit: IntervalUnit) -> Self

Set the interval unit.

impl RecurrenceRule

pub fn validate(&self) -> Result<(), RuleError>

Validate the rule before it is persisted (T002, C-004).

Collects every finding rather than failing on the first, so a user fixes one rule once instead of discovering one problem per attempt. A refusal writes nothing, so an invalid rule can never reach a series file.

pub fn diagnostics(&self) -> Vec<RuleDiagnostic>

Every diagnostic, in deterministic field order.

pub fn anchor_date(&self) -> Result<Date, RuleError>

The anchor as a calendar date, if the rule has a valid one.

pub fn anchor_key(&self) -> Result<DateKey, RuleError>

The canonical anchor date key.

pub fn summary(&self) -> String

A one-line human summary of the rule, for a warning’s rule_summary.

Best-effort on an invalid rule: the summary is display text, and refusing to render it would hide the very rule a user is trying to fix.

impl RecurrenceRule

pub fn next_occurrence( &self, context: &RuleContext, ) -> Result<DateKey, RuleError>

The first occurrence strictly after context.today (T003).

The schedule is anchor, anchor + step, anchor + 2·step, …; the result is the first of those dates after the injected date key. An anchor in the future is therefore the answer, and an occurrence exactly on the injected date is not the answer — “next” means next.

Month-end and leap-day arithmetic, defined not guessed

A monthly step keeps the anchor’s day-of-month and re-anchors on the target month’s last day when that day does not exist. An anchor of 2026-01-31 therefore recurs on 2026-02-28, and a 2024-02-29 anchor recurs on 2025-02-28; the rules are here, in one place, rather than left to whichever arithmetic a caller happened to write. A stored anchor that is not a real date at all (2025-02-29) never reaches this function: validation refuses it first.

Ambiguity is refused

The rule is validated, then the injected context: a named zone on either side, an unparseable offset, or a rule/context offset disagreement is a diagnostic rather than a silent normalization. A computed occurrence outside the supported calendar range is a diagnostic too.

Trait Implementations

impl Clone for RecurrenceRule

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RecurrenceRule

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RecurrenceRule

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for RecurrenceRule

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for RecurrenceRule

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for RecurrenceRule