class Instant is Cool does Real { }

An Instant is a particular moment in time measured in atomic seconds, with fractions. It is not tied to or aware of any epoch.

An Instant can be used to create a DateTime object set to that Instant. The pseudo-constant now returns the current time as an Instant.

Basic math is defined for Instants (as well as Durations). Adding an Instant to a Duration returns another Instant. Subtracting two Instants will yield a Duration. Adding two Instants is explicitly disallowed. All other operations with Instants are undefined.

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, 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 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 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␤»

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 that the implementation knows about, which may not be the last leap second that has actually been scheduled. This means you can get different results, depending on the compiler version you're using. For example, the December 31, 2016 leap second was announced in July and shipped with Rakudo 2016.07, so 2016.06 and earlier releases won't know about it.

$ perl6-2016.06 -e 'say Instant.from-posix: 1485726595'
Instant:1485726631

$ perl6-2016.07 -e 'say Instant.from-posix: 1485726595'
Instant:1485726632

Since a Rakudo compiler always returns 0 for future leap seconds it doesn't know about, you can patch your old code when new leap seconds are announced, so it will give correct results, regardless of what version of the compiler it runs on:

$ perl6-2016.06 -e 'say ($*VM.version before v2016.07 ?? 1 !! 0) + Instant.from-posix: 1485726595'
Instant:1485726632

$ perl6-2016.07 -e 'say ($*VM.version before v2016.07 ?? 1 !! 0) + Instant.from-posix: 1485726595'
Instant:1485726632

These examples require compilers that predate the rename, and so still refer to perl6.

Methods§

method from-posix§

method from-posix($posix, Bool $prefer-leap-second = False)

Converts the POSIX timestamp $posix to an Instant. If $prefer-leap-second is True, the return value will be the first of the two possible seconds in the case of a leap second.

say DateTime.new(Instant.from-posix(915148800, True));  # OUTPUT: «1998-12-31T23:59:60Z␤»
say DateTime.new(Instant.from-posix(915148800));        # OUTPUT: «1999-01-01T00:00:00Z␤»

method to-posix§

method to-posix()

Converts the invocant to a POSIX timestamp and returns a two element list containing the POSIX timestamp and a Bool. It is the inverse of method from-posix, except that the second return value is True if *and only if* this Instant is in a leap second.

say DateTime.new("1999-01-01T00:00:00Z").Instant.to-posix; # OUTPUT: «(915148800 False)␤»
say DateTime.new('1998-12-31T23:59:60Z').Instant.to-posix; # OUTPUT: «(915148800 True)␤»

method Date§

method Date(Instant:D: --> Date:D)

Coerces the invocant to Date.

my $i = "/etc/passwd".IO.modified;
say $i;             # OUTPUT: «Instant:1451489025.878018␤»
say $i.Date;        # OUTPUT: «2015-12-30␤»

method DateTime§

method DateTime(Instant:D: --> DateTime:D)

Coerces the invocant to DateTime.

say now.DateTime;  # OUTPUT: «2017-05-09T14:02:58.147165Z␤»

Typegraph§