What exactly is the difference between Interval.length(), Interval.count(), and DateTime.diff()?

[arcataroger]

I'm having some trouble understanding the nuanced differences between these three similar-looking methods. I ran some experiments in a Codesandbox, but it's still not super clear: https://codesandbox.io/s/luxon-date-range-test-3uog3b?file=/src/App.tsx

Assuming a range of 1970-01-01T00:00:00Z (0 ms) to 1973-03-03T09:46:40Z (100000000000 ms)

DateTime.diff()

"Return the difference between two DateTimes as a Duration."

OK, that seems straightforward enough. But then:

• diff.as('days') = 1157.4074074074074 (makes sense)
• diff.days and diff.get('days') = 0 (huh? what is this supposed to do?)

Interval.length()

"Returns the length of the Interval in the specified unit."

• interval.length() = 1157.4074074074074 (same as diff.as('days'))

Interval.count()

"Returns the count of minutes, hours, days, months, or years included in the Interval, even in part. Unlike Interval#length this counts sections of the calendar, not periods of time, e.g. specifying 'day' asks 'what dates are included in this interval?', not 'how many days long is this interval?'"

• interval.count() = 1158 (Is this just interval.length() rounded up?)

I don't understand this explanation at all. What does "What dates are included in this interval" mean, compared to "how many days long is this interval"? Is that "is included" a binary true/false count of days in that (so it'll give you an int)? Is that the same as "will round up to the nearest integer of the specified unit", or is there some other nuance I'm not getting?

In summary

Would it be correct say this:

• For a precise measurement, use either diff.as() or Interval.length(). These are the same?
• To round up, use Interval.count(). This is the same as Math.ceil() of the above?

Or am I missing something...?

[icambron]

Durations

Durations are a pile of units. Think of it as like { days: 1, hours: 48, minutes: 3, seconds: 4 }. The various methods like shiftTo can move data between the units. Anyway, that duration would return 1 for days, since the day component is 1. as("days") converts it to days and would return 3.something. If you don't specify the units in the diff() call, you get the diff in milliseconds (i.e. the duration is like {milliseconds: someHugeNumber}, so the days component is 0. See here for more.

Interval.length(unit) vs Duration.as(unit)

These are not always the same. See here

Interval.count

No, count("days") checks how many calendar days are included in the interval. So if the interval starts at 23:59 Monday and ends at 00:01 on Wednesday, it is just over a day in length but the count is 3 because the interval touches 3 different days.

[arcataroger]

Thank you for the clear and detailed explanations, @icambron! They were very helpful.

Would it be possible, please, to include some of these potential misunderstandings (possible footguns?) in the API method documentation too? The links you provided were awesome, but it would be helpful to see them in the API docs too.

For example, providing examples of the differences between .shiftTo(), .get(), and .as() (in the examples section of each) and/or explicitly linking to the "duration math" page you provided. I didn't realize the API docs weren't the same thing as the very helpful overviews you provided.

If helpful, I would be happy to provide drafts of such changes and PR them? Are the API docs just autogenerated from the JSdocs (example for Duration.as())?

Thanks so much again for this excellent explanation (and the library!)