Skip to main content

Module calendar

Module calendar 

Source
Expand description

Calendar dates for parameters. Model times are f64 days from day 0; given a start date, a document may write a day as a YYYY-MM-DD date, a YYYY-Www week, or days with units such as 2w. The #[calendar] attribute marks those fields:

use ixa::calendar;
use ixa::calendar::Date;
use serde::{Deserialize, Serialize};

#[calendar]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Policy {
    #[calendar]
    pub start: f64,
    #[calendar]
    pub end: Option<f64>,
    #[calendar(duration)]
    pub delay: f64,
}

#[calendar(weeks = "epi")]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Parameters {
    #[calendar(reference)]
    pub start_date: Option<Date>,
    #[calendar]
    pub policies: Vec<Policy>,
    #[calendar(inclusive)]
    pub max_time: f64,
}

let p: Parameters = serde_json::from_str(r#"{
    "start_date": "2026-05-14",
    "policies": [{"start": "2026-06-01", "end": "2026-W27", "delay": "2w"}],
    "max_time": "2026-08-05"
}"#).unwrap();
assert_eq!(p.policies[0].start, 18.0);
assert_eq!(p.policies[0].end, Some(52.0));
assert_eq!(p.policies[0].delay, 14.0);
assert_eq!(p.max_time, 84.0);

assert!(serde_json::to_string(&p).unwrap().contains(r#""start":18.0"#));
assert!(serde_json::to_string(&p.dated()).unwrap().contains(r#""start":"2026-06-01""#));

#[calendar] generates a twin struct (CalendarPolicy for Policy) holding each marked field’s Calendar::Wire (Day for an f64), and implements Calendar between the two. Field options: #[calendar(reference)] marks the root’s start date (Date or Option<Date>); inclusive is for a day a date or week includes, such as the end of a run; duration is for a length of time, which takes units but no dates and is not moved by Calendar::shift_days; signed lets a duration be negative; week makes dated() write a week where the day starts one. #[calendar(weeks = "iso")] or weeks = "epi" on a struct picks the WeekSystem for it and the structs inside it; a week in a document without one is an error.

Every calendar struct deserializes through its twin and serializes days. The struct with the start date is the root and has dated(); a struct read without one takes numbers and units but no dates or weeks. A nested root falls back to the outer start date. Dates are for human-readable formats; a format that is not (by serde’s is_human_readable) reads and writes the struct as written, days only, so it round trips through any serde format. Every field type must then be Deserialize, including types that implement Calendar by hand.

The twin copies the struct’s derives and serde attributes, so #[calendar] goes above #[derive(..)]. Limits: derive Clone, Debug, PartialEq, Serialize and Deserialize; no generics; no serde try_from, from, into or remote, and no with, deserialize_with, serialize_with or default = ".." on a marked field. A struct with its own wire shape implements Calendar by hand. To validate a document, wrap the root in a type whose Deserialize reads it and checks the result.

In code, Date::start_of and Date::start_of_week turn a date or week string into days from a start date. ContextCalendarExt stores the start date and week system on the context so reports can write the current Date, Week and Weekday, which serialize as YYYY-MM-DD, YYYY-Www and Mon.

Field options on a field that does not hold days are a compile error:

ⓘ
use ixa::calendar;
use serde::{Deserialize, Serialize};

#[calendar]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
struct Window { #[calendar] from: f64 }

#[calendar]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
struct Outer { #[calendar(inclusive)] windows: Vec<Window> }

Structs§

CalendarContext
The enclosing start date and week system of a conversion.
Date
A calendar date, written and read as YYYY-MM-DD.
FieldOptions
The #[calendar(..)] options of the field being converted; the default is a plain point in time.
Week
A numbered week of a year, written and read as YYYY-Www. Which days it covers depends on the WeekSystem.

Enums§

CalendarError
An error reading a date or converting one to days.
Day
A day field as a document writes it. Days with units (2w, 3d, 12h) read as Day::DaysFromStart.
WeekSystem
How weeks are numbered. Both number from the week holding January 4 (the first with four days in the year), so a week near New Year may belong to the year before or after.
Weekday
A day of the week, written as Mon to Sun.

Traits§

Calendar
A type with day fields and a wire form that may hold dates. #[calendar] implements it for a struct.
ContextCalendarExt
The date of day 0 and the week system on a Context, for writing dates and weeks in reports.