[LEAPSECS] Java JSR-310 Instant class

[Stephen Colebourne]

This is the Javadoc for Instant, the most widely used class. It has
86400 "seconds" per day as most users want and expect.

Please use this thread for any feedback on this Javadoc, with any
recommended wording changes.
Please do not use this thread to discuss the rights and wrongs of
UTC-SLS or leap seconds!

 * An instantaneous point on the time-line.
 * <p>
 * The Time Framework for Java models time as a series of instantaneous events,
 * known as instants, along a single time-line.
 * This class represents one of those instants.
 * <p>
 * An instant is in reality an instantaneous event on an infinite time-line.
 * However, for practicality this API uses a precision of nanoseconds.
 * In addition, this API limits the measurable time-line to the number
of seconds
 * that can be held in a {@code long}.
 * This is greater than the current estimated age of the universe.
 * <p>
 * In order to represent the data a 96 bit number is required. To
achieve this the
 * data is stored as seconds, measured using a {@code long}, and nanoseconds,
 * measured using an {@code int}. The nanosecond part will always be between
 * 0 and 999,999,999 representing the nanosecond part of the second.
 * <p>
 * The seconds are measured from the standard Java epoch of {@code
1970-01-01T00:00:00Z}.
 * Instants on the time-line after the epoch are positive, earlier are negative.
 *
 * <h4>Time-scale</h4>
 * <p>
 * {@code Instant} uses the <a
href="http://www.cl.cam.ac.uk/~mgk25/time/utc-sls/">UTC-SLS</a>
 * time-scale which always has 86400 seconds in a day.
 * Essentially, UTC-SLS is a consistent mechanism of converting an
accurate UTC time
 * (potentially with leap seconds) to a 86400 second day.
 * Its main benefit is that in an accurate implementation, the UTC-SLS
time never experiences
 * any gaps or overlaps.
 * <p>
 * UTC-SLS is defined as spreading any leap second evenly over the
last 1000 seconds of the day.
 * This corresponds to times after 23:43:21 on a day with an added
leap second, or
 * times after 23:43:19 on a day with a removed leap second.
 * <p>
 * The UTC-SLS conversion only matters to users of this class with
high precision requirements.
 * To keep full track of an instant using an accurate time-scale use
the {@link UTCInstant} or
 * {@link TAIInstant} class.
 * For most applications, the behavior where each day has exactly
86400 seconds is the desired one.
 * The UTC-SLS time-scale is also used for all human-scale date-time classes,
 * such as {@code OffsetDateTime} and {@code ZonedDateTime}.
 * <p>
 * The standard Java epoch of 1970 is prior to the introduction of
whole leap seconds into UTC in 1972.
 * As such, the Time Framework for Java needs to define what the 1970
epoch actually means.
 * The chosen definition is that there are no leap seconds or rate
changes in the Java version
 * of UTC prior to 1972, thus it remains 10 seconds offset from TAI.
 * This differs from an accurate UTC implementation, but is relatively
easy to handle if accuracy is required.
 * <p>
 * Operations to add or subtract durations will ignore leap seconds.
 * Use {@code UTCInstant} or {@code TAIInstant} if accurate duration
calculations are required.


Stephen