On Period and DateTimeFormatter

[David Alayachew]

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.rappo at 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.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/core-libs-dev/attachments/20250618/21656a4c/attachment-0001.htm>