calends

calends is a library for durations, intervals and other calendar related operations. It is designed to work with chrono.

Durations of time

A RelativeDuration is a unit of time that has some ability to be applied to a date to produce another date.

```rust use calends::RelativeDuration; use chrono::NaiveDate;

// This will allow you to add one month and then go back two days from the added month let rd = RelativeDuration::months(1).with_days(-2);

// It also compatible with NaiveDate asserteq!( NaiveDate::fromymd(2022, 1, 1) + rd, NaiveDate::from_ymd(2022, 1, 30) ); ```

When applying durations to dates, it will apply in order if the largest units first e.g. months will come before weeks. Therefore when you construct durations such as 1 month, -1 day it will then move forward 1 month and then go backwards one day.

Serialization

There are two ways to serialize a RelativeDuration: - The first one serializes it as an object. - The second way is an ISO8601-2:2019 compatible serializer. Because the format is not widely used yet we do not set it as the default (de)serializer.

```rust use calends::RelativeDuration; use calends::rd_iso8601;

[derive(Debug, serde::Deserialize, serde::Serialize)]

struct S { #[serde( deserializewith = "rdiso8601::deserialize", serializewith = "rdiso8601::serialize" )] rd: RelativeDuration, }

let rd = RelativeDuration::default().withdays(1).withmonths(23).with_weeks(-1); let s = S { rd };

let rdstring = serdejson::tostring(&s).unwrap(); asserteq!(rd_string, r#"{"rd":"P23M-1W1D"}"#);

let parsed: S = serdejson::fromstr(&rdstring).unwrap(); asserteq!(rd, parsed.rd) ```

Recurrence & Rules

[Recurrence] allows you to specify a ruleset for how events (dates) repeat in time.

```rust use calends::{Recurrence, Rule}; use chrono::NaiveDate;

let date = NaiveDate::fromymd(2022, 1, 1); let end = NaiveDate::fromymd(2022, 3, 1);

let mut recur = Recurrence::withstart(Rule::monthly(), date).until(end); asserteq!(recur.next(), Some(NaiveDate::fromymd(2022, 1, 1))); asserteq!(recur.next(), Some(NaiveDate::fromymd(2022, 2, 1))); asserteq!(recur.next(), None); ```

Intervals

An interval is a span of time that can be bound or unbound. This means that you can iterate until the beginning/end of the time. However in practice this will be limited by chronos types.

This will likely be used to do things like iterate by week, month, quarter, or year.

```rust use calends::{Interval, IntervalLike, RelativeDuration}; use calends::interval::marker::{End, Start}; use chrono::NaiveDate;

let start = NaiveDate::from_ymd(2022, 1, 1); let duration = RelativeDuration::months(1);

let mut interval = Interval::from_start(start, duration);

asserteq!(interval.start(), start); asserteq!(interval.end(), NaiveDate::from_ymd(2022, 1, 31));

// Intervals are also iterable because they always have a duration! // they are inclusive so they return the current time span first

let next = interval.next().unwrap();

asserteq!(next.start(), NaiveDate::fromymd(2022, 1, 1)); asserteq!(next.end(), NaiveDate::fromymd(2022, 1, 31));

let next = interval.next().unwrap();

asserteq!(next.start(), NaiveDate::fromymd(2022, 2, 1)); asserteq!(next.end(), NaiveDate::fromymd(2022, 2, 28));

```

In combination with RelativeDuration you can do things such as iterate the second to last day of the month.

```rust use calends::{Interval, RelativeDuration}; use chrono::NaiveDate;

let duration = RelativeDuration::months(1).withdays(-2); let start = NaiveDate::fromymd(2022, 1, 1);

let mut interval = Interval::from_start(start, duration); ```

Serialization

There are two ways to serialize a Interval: - The first one serializes it as an object. - The second way is an ISO8601-2:2019 compatible serializer. Because the format is not widely used yet we do not set it as the default (de)serializer.

```rust use chrono::NaiveDate; use calends::{Interval, RelativeDuration}; use calends::interval::marker::Start; use calends::int_iso8601;

[derive(Debug, serde::Deserialize, serde::Serialize)]

struct S { #[serde( deserializewith = "intiso8601::deserialize", serializewith = "intiso8601::serialize" )] i: Interval, }

let rd = RelativeDuration::default().withdays(1).withmonths(23).withweeks(-1); let int = Interval::fromstart(NaiveDate::from_ymd(2022, 1, 1), rd); let s = S { i: int.clone() };

let intstring = serdejson::tostring(&s).unwrap(); asserteq!(int_string, r#"{"i":"2022-01-01/2023-11-24"}"#);

let parsed: S = serdejson::fromstr(&intstring).unwrap(); asserteq!(parsed.i.start(), int.start()) ```

License: MIT