How does it not model an interval? Here is the official documentation.
*Obtains a Period consisting of the number of years, months, and days between two dates.* https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/time/Period.html#between(java.time.LocalDate,java.time.LocalDate) And here is the dictionary definition. *a space of time between events or states* https://www.merriam-webster.com/dictionary/interval On Wed, Jun 18, 2025, 7:30 AM Pavel Rappo <pavel.ra...@gmail.com> wrote: > Hello, I have two questions on java.time API. > > The first one is about documentation for java.time.Period. When I get > back to the API after a long period (no pun intended) of not using it, > it takes me a while to recall that Period does __NOT__ model an > interval between two specific points in time, such as vacation dates. > And the signature of the Period.between(LocalDate, LocalDate) method > makes it even harder. > > I'm not sure what it is. Is it because I'm a non-native English > speaker or it's some idiosyncrasy? Anyway, if it's not just me, then > my question is: would it make sense to provide a few short and punchy > notes to the reader to quickly rectify this misconception that might > be forming in their head while they are reading the documentation? > Sometimes it's helpful to say what something isn't in addition to > saying what something is. > > > The second question is about DateTimeFormatter. I recently had to > parse a date that resembles output of asctime: Sat Jul 16 02:03:55 > +0000 1994. It's fine and dandy until you parse a date in September. > That time format expects "Sep", while the formatter expects "Sept". > > Now, I'm aware that it's a known issue [^1]. Still, I wonder if we can > do anything better than suggest using a specific locale, which is not > bulletproof, or going to the DateTimeFormatterBuilder route. > > Thanks, > -Pavel > > [^1]: See https://bugs.openjdk.org/browse/JDK-8256837 and its numerous > duplicates. >
