txt: ## instant.md
  class Instant
  
  Specific moment in time
  
  ```raku
  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`](/type/DateTime) object set to that `Instant`. The pseudo-constant `now` returns the current time as an `Instant`.
  
  Basic math is defined for `Instant`s (as well as [`Duration`](/type/Duration)s). Adding an `Instant` to a [`Duration`](/type/Duration) returns another Instant. Subtracting two `Instant`s will yield a [`Duration`](/type/Duration). Adding two `Instant`s is explicitly disallowed. All other operations with Instants are undefined.
  
  # [Future Leap Seconds](#class_Instant "go to top of document")[§](#Future_Leap_Seconds "direct link")
  
  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.
  
  ｢text｣ without highlighting
  
  ```
  
  
  ```
  
  $ 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:
  
  ｢text｣ without highlighting
  
  ```
  
  
  ```
  
  $ 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](#class_Instant "go to top of document")[§](#Methods "direct link")
  
  ## [method from-posix](#class_Instant "go to top of document")[§](#method_from-posix "direct link")
  
  ```raku
  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.
  
  ```raku
  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](#class_Instant "go to top of document")[§](#method_to-posix "direct link")
  
  ```raku
  method to-posix()
  ```
  
  Converts the invocant to a POSIX timestamp and returns a two element list containing the POSIX timestamp and a [`Bool`](/type/Bool). It is the inverse of [method from-posix](#method_from-posix), except that the second return value is `True` if \*and only if\* this Instant is in a leap second.
  
  ```raku
  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](#class_Instant "go to top of document")[§](#method_Date "direct link")
  
  ```raku
  method Date(Instant:D: --> Date:D)
  ```
  
  Coerces the invocant to [`Date`](/type/Date).
  
  ```raku
  my $i = "/etc/passwd".IO.modified;
  say $i;             # OUTPUT: «Instant:1451489025.878018␤»
  say $i.Date;        # OUTPUT: «2015-12-30␤»
  ```
  
  ## [method DateTime](#class_Instant "go to top of document")[§](#method_DateTime "direct link")
  
  ```raku
  method DateTime(Instant:D: --> DateTime:D)
  ```
  
  Coerces the invocant to [`DateTime`](/type/DateTime).
  
  ```raku
  say now.DateTime;  # OUTPUT: «2017-05-09T14:02:58.147165Z␤»
  ```
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `Instant`
  
  
  
  raku-type-graph
  
  
  
  Instant
  Instant
  
  
  Cool
  Cool
  
  
  Instant->Cool
  
  
  
  Real
  Real
  
  
  Instant->Real
  
  
  
  Mu
  Mu
  
  
  Any
  Any
  
  
  Any->Mu
  
  
  
  Cool->Any
  
  
  
  Numeric
  Numeric
  
  
  Real->Numeric
  
  [Expand chart above](/assets/typegraphs/Instant.svg)
  