[LEAPSECS] Java JSR-310 UTCInstant class

[Stephen Colebourne]

This is the Javadoc of the UTCInstant class:
This implements leap seconds.

Please use this thread to discuss flaws in the documentation.

 * An instantaneous point on the time-line measured in the UTC time-scale,
 * handling leap seconds.
 * <p>
 * Most of the Time Framework for Java works on the assumption that
the time-line is
 * simple, there are no leap-seconds and there are always 24 * 60 * 60
seconds in a day.
 * However, the Earth's rotation is not straightforward, and a solar
day does not match
 * this definition.
 * <p>
 * This class is an alternative representation based on the UTC time-scale which
 * includes leap-seconds. Leap-seconds are additional seconds that are
inserted into the
 * year-month-day-hour-minute-second time-line in order to keep UTC in
line with the solar day.
 * When a leap second occurs, an accurate clock will show the time
{@code 23:59:60} just before midnight.
 * <p>
 * Leap-seconds are announced in advance, typically at least six months.
 * The {@link UTCRules} class models which dates have leap-seconds.
 * Alternative implementations of the rules may be supplied.
 * <p>
 * The default rules implementation fixes the start point of UTC as 1972.
 * This date was chosen as UTC was more complex before 1972.
 * <p>
 * The duration between two points on the UTC time-scale is calculated
solely using this class.
 * Do not use the {@code between} method on {@code Duration} as that
will lose information.
 * Instead use {@link #durationUntil(UTCInstant)} on this class.
 * <p>
 * It is intended that most applications will use the {@code Instant} class
 * which uses the UTC-SLS mapping from UTC to guarantee 86400 seconds per day.
 * Specialist applications with access to an accurate time-source may
find this class useful.
 *
 * <h4>Time-scale</h4>
 * <p>
 * The length of the solar day is the standard way that humans measure time.
 * As the Earth's rotation changes, the length of the day varies.
 * In general, a solar day is slightly longer than 86400 seconds.
 * The actual length is not predictable and can only be determined by
measurement.
 * The UT1 time-scale captures these measurements.
 * <p>
 * The UTC time-scale is a standard approach to bundle up all the
additional fractions
 * of a second from UT1 into whole seconds, known as <i>leap-seconds</i>.
 * A leap-second may be added or removed depending on the Earth's
rotational changes.
 * If it is removed, then the relevant date will have no time of
{@code 23:59:59}.
 * If it is added, then the relevant date will have an extra second of
{@code 23:59:60}.
 * <p>
 * The modern UTC time-scale was introduced in 1972, introducing the
concept of whole leap-seconds.
 * Between 1958 and 1972, the definition of UTC was complex, with
minor sub-second leaps and
 * alterations to the length of seconds. The default rules only
implement UTC from 1972.
 * Prior to that date, the default rules fix the UTC-TAI offset at 10 seconds.
 * While not historically accurate, it is a simple, easy definition,
suitable for this library.
 * <p>
 * The standard Java epoch of {@code 1970-01-01} 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 follows the UTC definition given above, such
that {@code 1970-01-01} is 10 seconds
 * offset from TAI.


Stephen