Implement LocalDate.fromEpochDays

[dkhalanskyjb]

Naming is up to discussion. See #210. For now, I'm for the name fromEpochDays because days-of-anything are most commonly numbered from 1. *EpochDays, as opposed to *EpochDay, helps highlight us using the number of days and not their 1-based ordinal.

[dkhalanskyjb]

NB: the fromEpochDay test failed because the Windows agent suddenly was very slow and triggered a 5-second timeout built into the JS runner. I think the best course of action here would be to just disable the timeout, as the test itself runs instantly for me for all targets.

[ilya-g]

That can happen on TC, because agents there are usually computationally weaker than dev laptops or workstations.
In this case I suggest to reduce the test complexity, since computing all these ~2mln datapoints, especially incurring allocations, can be indeed a tough call for JS.

[dkhalanskyjb]

I think we do want to test this thoroughly on a large range of values, because of the complexity of the code. A lot of things can go wrong there. In particular, it uses the notion of 400-year cycles in its implementation, and march-based years. I wouldn't dare to change anything there without being sure that every math operation there was exercised via brute force.

[dkhalanskyjb]

I fixed the test—despite the comment in its beginning, it was invoking plus instead of next and previous—and it seems for now that the problem is mitigated. Restarting the test a few times on the CI, I couldn't observe a failure. next and previous are a bit more efficient than plus, maybe that's the thing.

[ilya-g]

This file contains common math functions, not specific to any date calculations. I suggest to find another file for these new ones, or introduce a new one, e.g. dateMath.kt/calendarMath.kt/IsoChronology.kt

[dkhalanskyjb]

It does define some constants like internal const val HOURS_PER_DAY = 24 or NANOS_PER_DAY already, so it's not just pure math here. I don't think it's worth it yet to split the file, because

• it's relatively short,
• when writing code, I like to look over the available constants, and seeing all of them in one place helps, whereas we would need to move, say, HOURS_PER_DAY into the date-specific-math file, keeping NANOS_PER_ONE in the pure math one.

[ilya-g]

Now, when we've got two new functions, it's a good chance to group these constants together with them in a separate file.
NANOS_PER_ONE can also be seen as a time-related constant, not general math.

[dkhalanskyjb]

Peculiarly, trying to implement this refactoring slows down the code on JS considerably. The test for fromEpochDays now fails, and checking on my machine, before the refactoring, it takes 1.2 ± 0.2 seconds, while after the refactoring, it takes 1.6 ± 0.3 seconds. I propose that we revert this change.

[ilya-g]

Can't confirm such effect, on the opposite the test runs faster for me on the latest commit than on the previous.
I compared generated JS code and didn't find anything suspicious in the difference.

[ilya-g]

As the last resort, the timeout could be increased if it's essential to test all these values.

[dkhalanskyjb]

Yeah, let's do that.

[ilya-g]

The highest recorded test duration value was 8.6s, so probably 10-15 s should be fine

[dkhalanskyjb]

Sure, I just don't see the point in this timeout at all. Don't understand what it brings to the table. So, I increased it to the point where it will most certainly not bother us. Do you have some ideas about why this limit could be useful? If so, maybe it makes sense to add it to the other targets as well?