Local date range

[PeterAttardo]

This pull request enables Kotlin range and progression semantics with the LocalDate and DatePeriod classes. Its implementation borrows from the patterns used for IntRange.

Example:

val start = LocalDate.parse("2020-01-01")
val end = LocalDate.parse("2020-12-31")

// calls function for each day of the year in 2020
(start..end).forEach {
    processDayOf2020(it)
}

// calls function for each day of the year in 2020, ordered in reverse
(end downTo start).forEach {
   processDayOf2020(it)
}

// calls function for every other day of the year in 2020
(start..end step DatePeriod(days=2)).forEach {
   processDayOf2020(it)
}

[dkhalanskyjb]

We have a similar request, but for Instant: #34
Could you please describe why this is needed? Either in the issue I linked if your use cases are similar to the ones listed there, or in a new issue.

[boswelja]

@dkhalanskyjb I've had a use case for this, though it's more of a convenience having a dedicated LocalDateRange compared to a ClosedRange<LocalDate>. I'm building a calendar library that allows consumers to update a particular range of dates on the screen, the intended use case for this is to allow changing the rendered content in chunks.

A few other use cases off the top of my head:

• Representing a selected date range
• Using plus/minus + forEach in conjunction to iterate over a large range in chunks (granted this could be achieved by having a list of dates and chunking that, but if you've only got a start and end date this could be more efficient)

[dkhalanskyjb]

• Could you also make the range an implementation of Collection? See https://youtrack.jetbrains.com/issue/KT-36932/Let-Progression-classes-implement-Collection-to-reduce-time-when-iterates-over-IntRange-when-cast-to-Iterable
• All API entries (classes, functions, properties) need separate tests, a KDoc, and a usage sample.

[PeterAttardo]

Something I came across that's not exactly an issue in the library, but is a usability question when using the library in IntelliJ that I'm wondering if there's a good answer for.

Because Kotlin automatically imports kotlin.ranges.* into every file, that means that the extension function fun <T : Comparable<T>> T.rangeTo(that: T): ClosedRange<T> is by-default available for all code. LocalDate implements Comparable<LocalDate> and so if you type the following:

(localDate1..localDate2).forEach {
    // some code in here
}

localDate1..localDate2 will not display an Unresolved reference warning due to a failure to import kotlinx.datetime.rangeTo, but will happily use kotlin.ranges.rangeTo and return a ClosedRange<LocalDate> instead. Because ClosedRange<LocalDate> is not LocalDateRange, all of our nice progression methods are unavailable, and we get an Unresolved reference warning on forEach instead.

This is easily solved by importing kotlinx.datetime.rangeTo, but IntelliJ is unable to recognize this as the solution, because from its perspective there is no issue resolving the rangeTo operator, just an issue with calling non-existing methods on ClosedRange<LocalDate>. This means users will have to be aware of this pitfall, and manually type in the import in every file they want to use the range operator with LocalDate.

[dkhalanskyjb]

@PeterAttardo, maybe this issue can be solved if rangeTo is a member method of LocalDate? Good job noticing this problem!

[PeterAttardo]

@dkhalanskyjb I was hoping not to have to touch the LocalDate class, but that does seem like the cleanest solution. I have added the range operators to LocalDate, but because expect classes don't allow default implementations, I have moved the implementation logic into static methods in LocalDateRange. That can be cleaned up in the future if default implementations are ever allowed.

[dkhalanskyjb]

Compilation fails for me, and when I fix it, the getSize test fails.

[dkhalanskyjb]

Other than the small naming issue, I think it's good to go!

[dkhalanskyjb]

Thank you a lot for the hard work! Merged manually in d15ec21 to squash this into one commit.

[lukellmann]

I noticed that LocalDateProgression.random doesn't throw the documented exception.

[dkhalanskyjb]

@lukellmann, thanks, added the fix to the year-month branch (which, too, adds a random function): 8c04d69