Add a "DateDelta" datatype for differences in number of days

[esheppa]

change Days to take a u32 and addition of DaysDelta to NaiveDate, changes to Iterator Implementations

This has been separated out from #824

[esheppa]

This could potentially target 0.4.x but that would preclude some of the API changes like the new impl Sub return type

[esheppa]

Actually, upon re-reading this, I think the only thing I'd have to change is to leave Days::new taking a u64, then this would be ok in 0.4.x

[djc]

Sorry, I've paged out my context on why we needed/wanted this as an addition.

(If we want to do it, doing it on 0.4.x first seems like a great idea. Would also be nice to rewrite the commit message to have a shorter first line introduction.)

[esheppa]

Fair call - the main idea here is to have a proper return type for things like my_date.days_since(my_other_date) - where we want to use the existing Days type, but the difference can either be forwards or backwards.

[djc]

Been thinking about this more. What if instead of all the *Delta types we only offer checked_sub() operations that just yield None if negative? I feel like the proliferation of Delta types makes the API unwieldy and they actually have really limited utility since the sub of something negative is not something that actually makes all that much sense in this domain.

[esheppa]

This sounds reasonable to me. From the implementation, the only time *Delta is useful is when you have two datetimes/times and you want to get the difference in duration between them along with the ordering in one operation, but this is likely a rare use case.

What if we had the following functions:
checked_sub / checked_difference / checked_delta - this returns Option<core::time::Duration>
absolute_delta / abs_diff - this returns the absolute value in core::time::Duration

And then we would also not implement the ops::Sub<NaiveDate> for NaiveDate etc for NaiveDateTime as well. This is great as it means there would now be the full functionality of https://github.com/chronotope/chrono/pull/860/files available in 0.4.x!

[djc]

Yeah, sounds good! I think I would go with checked_sub() and abs_diff().

[esheppa]

Had another thought of just using Result for this - what do you think? (with a similar pattern in #860)

[djc]

What's the point of changing from u64 to u32?

[esheppa]

This was originally combined with the work in d086ca9 and in the implementations of signed_duration_since which is infallible, a u32 is much more convenient to work with than a u64, due to the From<u32> for i64 impl. In hindsight u64 was a mistake and u32 makes more sense for days, given that u32 allows for far more years than NaiveDate has in total range anyway. u16 would be too narrow, and so u32 is the most reasonable fit.

[jtmoon79]

Please add attribute #[must_use] to new and modified functions.

[jtmoon79]

For backwards compatibility checks, could you add some tests cases (or statements within a test case) to compare Days::new and Days::from_u32 result in the same values?

I know new is the "old way", but wouldn't hurt to make sure it's still working.