Earlier quoted context omitted.
> Once you know that “Java says X is the first day of the week,” The basic assumption when designing anything is that you can never rely on assuming that other humans "will" know.
A funny part is that java has java.util.Calendar that has setFirstDayOfWeek(int), the default depends on the locale used to create the Calendar. It's considered a bad design overall, esp with SUNDAY const being 1. For most of the world that (sun=1) made absolutely no sense at all and assumed one of those weird things like jokes about IQ and room temperature.
That is exactly the kind of hidden assumption that I’m trying to fight against! If the date and the locale were both passed in as parameters, preferably just plain data, this would be a transparent function. Instead, you have to find and read through the documentation to see what kind of mischief is going on. And you have to do that every time you encounter a Java.until.Calendar.
Edit to clarify: if “locale” is some class, you have to learn that class DSL to examine it, and depend on a runtime debugger that does the same. If “locale” is just a hash map, you can examine the values without a lot of faff.