public DateTimeFormatterBuilder appendInstant (int fractionalDigits)

Appends an instant using ISO-8601 to the formatter with control over the number of fractional digits.

Instants have a fixed output format, although this method provides some control over the fractional digits. They are converted to a date-time with a zone-offset of UTC and printed using the standard ISO-8601 format. The localized decimal style is not used.

The fractionalDigits parameter allows the output of the fractional second to be controlled. Specifying zero will cause no fractional digits to be output. From 1 to 9 will output an increasing number of digits, using zero right-padding if necessary. The special value -1 is used to output as many digits as necessary to avoid any trailing zeroes.

When parsing in strict mode, the number of parsed digits must match the fractional digits. When parsing in lenient mode, any number of fractional digits from zero to nine are accepted.

The instant is obtained using INSTANT_SECONDS and optionally NANO_OF_SECOND. The value of INSTANT_SECONDS may be outside the maximum range of LocalDateTime.

The resolver style has no effect on instant parsing. The end-of-day time of '24:00' is handled as midnight at the start of the following day. The leap-second time of '23:59:60' is handled to some degree, see DateTimeFormatter.parsedLeapSecond() for full details.

An alternative to this method is to format/parse the instant as a single epoch-seconds value. That is achieved using appendValue(INSTANT_SECONDS).

Parameters:
fractionalDigits    the number of fractional second digits to format with, from 0 to 9, or -1 to use as many digits as necessary

Returns:  this, for chaining, not null

Exceptions:
IllegalArgumentException    if the number of fractional digits is invalid