Instant, DateTime: discuss leap seconds per issue 3881 (#4723)

* Instant, DateTime: discuss leap seconds per issue 3881

* fix rakudoc syntax/format errors

* nitpicky change of placeholder variable name

* link all occurrences of C<Instant>

Author: arkiuat

doc/Type/DateTime.rakudoc

@@ -57,12 +57,14 @@ multi method new(Instant:D $i,  :$timezone=0, :&formatter)
 multi method new(Numeric:D $posix,  :$timezone=0, :&formatter)
 multi method new(Str:D $format, :$timezone=0, :&formatter)
 
-Creates a new C<DateTime> object. One option for creating a new DateTime object
+Creates a new C<DateTime> object. One option for creating a new C<DateTime> object
 is from the components (year, month, day, hour, ...) separately. Another is to
 pass a L<C<Date>|/type/Date> object for the date component, and specify the time
 component-wise. Yet another is to obtain the time from an
 L<C<Instant>|/type/Instant>, and only supply the time zone and formatter. Or
-instead of an Instant you can supply a L<C<Numeric>|/type/Numeric> as a UNIX timestamp.
+instead of an L<C<Instant>|/type/Instant> you can supply a L<C<Numeric>|/type/Numeric> as a Unix timestamp
+(but note that this last method provides no way to disambiguate leap seconds,
+unlike using L<C<Instant>|/type/Instant>).
 
 You can also supply a L<C<Str>|/type/Str> formatted in ISO 8601 timestamp
 notation or as a full L<RFC 3339|https://tools.ietf.org/html/rfc3339>
@@ -263,6 +265,11 @@ Returns the instant's time as a fraction of a 24-hour day.
 Notice the C<day-fraction> value is the same as the fractional part of
 the C<modified-julian-date> for the same instant.
 
+Also note that leap seconds may cause some variations from expected values:
+
+    for 30, 31 { say DateTime.new(2016,12,$_,12,0,0).day-fraction }
+    # OUTPUT: «0.5␤0.499994␤»
+
 Available as of the 2021.04 Rakudo compiler release.
 
 =head2 method julian-date
@@ -294,7 +301,9 @@ Returns the L<Modified Julian Date|https://en.wikipedia.org/wiki/Julian_day> (MJ
 
     say DateTime.new('2021-12-24T12:23:00.43Z').modified-julian-date; # OUTPUT: «59572.5159772␤»
 
-Notice the fractional part of the C<modified-julian-date> is same value as the C<day-fraction> for the same instant.
+Notice the fractional part of the C<modified-julian-date> is same value as the
+L<C<day-fraction>|/type/DateTime#method_day-fraction> for the same instant, and
+is similarly affected by leap seconds.
 Likewise, the integral part of the I<MJD> is the same value as the C<daycount> for the same instant since they
 reference the same epoch (November 17, 1858).
 The MJD is obtained by subtracting the constant C<2_400_000.5> from the I<Julian Date> and is used to simplify
@@ -310,14 +319,19 @@ Available as of the 2021.04 Rakudo compiler release.
 
     method posix(Bool:D: $ignore-timezone = False --> Int:D)
 
-Returns the date and time as a POSIX/UNIX timestamp (integral seconds since the POSIX epoch,
+Returns the date and time as a POSIX/Unix timestamp (non-leap seconds since the POSIX epoch,
 1970-01-01T00:00:00Z).
 
 If C<$ignore-timezone> is C<True>, the C<DateTime> object will be treated as if
 the time zone offset is zero.
 
     method posix(Bool:D: $ignore-timezone = False, :$real --> Num:D)
 
+Note that this will collapse both a leap second and the second immediately
+following it into the same timestamp, because POSIX time ignores leap seconds.
+If you need better than this, see L<C<Instant>|/type/Instant> for the relevant
+methods.
+
 As of release 2022.06 of the Rakudo compiler, it is also possible to specify a
 C<:real> named argument.  If specified with a true value, a L<C<Num>|/type/Num> will be
 returned, allowing for sub-second accuracy of the number of seconds since the

doc/Type/Instant.rakudoc

@@ -18,7 +18,41 @@ C<Instant> to a L<C<Duration>|/type/Duration> returns another Instant. Subtracti
 will yield a L<C<Duration>|/type/Duration>. Adding two C<Instant>s is explicitly disallowed. All
 other operations with Instants are undefined.
 
-=head1 Future Leap Seconds
+=head1 Leap Seconds
+
+POSIX time (commonly called "Unix time") makes the incorrect assumption that
+the period of rotation of the Earth is a fixed constant. Since in fact the
+number of seconds that pass between one noon and the next varies from day to
+day, we must occasionally have a 61st second in the 60th minute of some hour;
+this is called a leap second, and happens at the same time all over the world,
+and therefore at different times of day in different timezones.
+
+POSIX deals with this by assigning the same integer label to two different
+consecutive seconds; that is, when a leap second happens, C<DateTime.now.posix>
+does not change for two whole seconds. For example:
+
+    my Instant $i .= from-posix(1483228799);
+    my Duration $s = DateTime.new(1) - DateTime.new(0);
+    sub demo { say [$_, .posix] with DateTime.new($i + $^n * $s) }
+    demo(0); # OUTPUT: «[2016-12-31T23:59:59Z 1483228799]␤»
+    demo(1); # OUTPUT: «[2016-12-31T23:59:60Z 1483228800]␤»
+    demo(2); # OUTPUT: «[2017-01-01T00:00:00Z 1483228800]␤»
+    demo(3); # OUTPUT: «[2017-01-01T00:00:01Z 1483228801]␤»
+
+For L<C<Real>|/type/Real> values, this would count up through the fractions
+of the second, and then instantaneously decrement one second and repeat the
+process a second time. Because of this, each time a leap second is recorded,
+the Unix time falls back one more second behind the actual time. Actual time
+is recorded by atomic clocks which disregard the Earth's rotation: when Unix
+time was first established it was based on UTC, which does track the rotation,
+and had by that time fallen 10 seconds behind atomic-clock time. The numerical
+value of C<Instant> happens to track atomic-clock time, and as of 2025 there
+have been 27 leap seconds recorded. This adds up to a total of 37 seconds,
+which is why, as of 2025, the following holds:
+
+    with now { say .Int - DateTime.new($_).posix } # OUTPUT: «37␤»
+
+=head2 Future Leap Seconds
 
 The methods that involve knowledge of leap seconds always assume
 that there will be no further leaps after the last leap second