`RelativeDuration::num_days()` misleading output (or name?)

[bobhy]

It seems that num_days(), num_weeks() and num_months() simply fetch the internal implementation fields unchanged.
I was expecting these would return the total length of the duration (truncated to whole days, weeks, months).
I wasn't expecting num_months() to be infallible, since it should need a reference Date to base calculations on in the general case.

Here's a sample program:

#![allow(unused_imports, dead_code)]
extern crate calends;
extern crate chrono;
use calends::RelativeDuration;
use chrono::{DateTime, Datelike, NaiveDate, NaiveDateTime, TimeZone, Timelike, Utc};
use std::fmt::Display;
pub fn main() {

    // simple case, length of month doesn't affect outcome:
    let rd1 = RelativeDuration::from_mwd(0, 3, 12);
    assert_contrapositive(rd1.num_weeks(), 3 + (12 / 7), "from_mwd().num_weeks");
    assert_contrapositive(rd1.num_days(), (3 * 7) + 12, "from_mwd().num_days");

    //  trickier case, length of month *does* come into it.

    let rd2 = RelativeDuration::from_duration_between(
        NaiveDate::from_ymd_opt(2023, 3, 31).unwrap(),
        NaiveDate::from_ymd_opt(2023, 4, 1).unwrap(),
    );

    assert_contrapositive(rd2.num_months(), 1, "from_duration_between().num_months");
    assert_contrapositive(rd2.num_days(), 1, "from_duration_between().num_days");
}

fn assert_contrapositive<T: Display + PartialOrd>(observed: T, expected: T, tag: &str) {
    if observed == expected {
        println!("SUCCESS?! Case {tag}, observed and expected were both: {observed}");
    } else {
        println!("Mismatch. Case {tag}, observed: {observed}, expected: {expected}");
    }
}

Which prints this, when run:

〉cargo run --quiet --example bug_rd
Mismatch. Case from_mwd().num_weeks, observed: 3, expected: 4
Mismatch. Case from_mwd().num_days, observed: 12, expected: 33
SUCCESS?! Case from_duration_between().num_months, observed and expected were both: 1
Mismatch. Case from_duration_between().num_days, observed: -30, expected: 1

FWIW, I think calends should have a helper function that does accept a date and can return total_days, total_weeks, total_months. (Unless there's already a way to get these? Calendar arithmetic is tricky.)

Plus, it would be OK for RelativeImpl to have the simple getters.

[bluemoon]

IIRC this is incredibly tricky, I will have to think about it. Do you have any thoughts on how the API surface area should work here?

[bobhy]

Assuming the RelativeDuration has both days (or weeks) and months, user must provide a particular base date before you can give a total number of days or months. So you might have an API like:

<relativeDuration>.total_days_from(<someDate>) -> i32

and likewise for total_weeks() and total_months(). One thing I'd recommend is these should return ints not floats, and should be truncated rather than rounded.

As for the rest of the API, I would like to see better names for the constructor, getter and setter functions for the individual time units. I didn't find .with_*() for a setter and .num_*() for a getter intuitive. The latter was especially confusing, hence the issue. They could simply be .set_*(), and .get_*(), then .days() as constructor wouldn't have to change. But that's just my opinion.