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§
- Calendar
Context - The enclosing start date and week system of a conversion.
- Date
- A calendar date, written and read as
YYYY-MM-DD. - Field
Options - 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 theWeekSystem.
Enums§
- Calendar
Error - 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 asDay::DaysFromStart. - Week
System - 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
MontoSun.
Traits§
- Calendar
- A type with day fields and a wire form that may hold dates.
#[calendar]implements it for a struct. - Context
Calendar Ext - The date of day 0 and the week system on a
Context, for writing dates and weeks in reports.