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.

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