Analyze the number of trailing zeros for fractions of seconds

[dkhalanskyjb]

Currently, in toString() for Instant, LocalDateTime, and LocalTime, we follow Java's approach and add trailing zeros up to the next multiple of three:

01:02:03
01:02:03.100
01:02:03.120
01:02:03.123
01:02:03.123400
01:02:03.123450
01:02:03.123456
01:02:03.123456700
01:02:03.123456780
01:02:03.123456789

This behavior can be misleading.

Imagine someone wants to parse the output of toString() from some other language where the paired parse() that we provide is not available. When sampling the output of toString() on effectively random values of nanosecond-of-second (for example, using Clock.System.now()), the user will see strings like 01:02:03.643441689, 01:02:04.432163481, 01:02:10.164127210: in essence, the strings of the same length. There is only a 0.1% chance to obtain a string that will be shorter; in other words, on average, it will take 1000 attempts to observe a second-fraction component that's not 9 digits, so a parser that assumes that the length is always 9 digits has a real chance of reaching production.

[dkhalanskyjb]

After an internal discussion, here are the conclusions.

localTime.toString() and localTime.format(LocalTime.Formats.ISO) serve slightly different purposes, even if the formats are very similar.

Both of them output and parse valid ISO 8601 strings, but for toString, the primary use case is doing println and looking in the debugger: it's mostly an API for human-readable output. We can afford a few niceties there, like omitting seconds if they are zero or adding extra zeros for readability, even if it means it's more difficult to write a parser for it.

Formats.ISO is for communication in ISO format between machines. We should prioritize predictability there, maybe at the cost of readability of the output. So, for predefined formats, we shouldn't add extra padding; for toString, why not?