txt: ## datetime.md
  class DateTime
  
  Calendar date with time
  
  ```raku
  class DateTime does Dateish {}
  ```
  
  For handling points in civil time, a `DateTime` object stores year, month, day, hour, minute (all [`Int`](/type/Int)), second (potentially fractional) and a time zone.
  
  It provides methods for calculating with date (for the Gregorian calendar) and time.
  
  `DateTime` methods are immutable; if you are tempted to modify one, create a modified copy instead.
  
  Time zones are handled as [`Int`](/type/Int)s in **seconds** offset from UTC, not by time zone name.
  
  ```raku
  my $dt = DateTime.new(
      year    => 2015,
      month   => 11,
      day     => 21,
      hour    => 16,
      minute  => 1,
  );
  
  say $dt;                            # OUTPUT: «2015-11-21T16:01:00Z␤»
  say $dt.later(days => 20);          # OUTPUT: «2015-12-11T16:01:00Z␤»
  say $dt.truncated-to('hour');       # OUTPUT: «2015-11-21T16:00:00Z␤»
  say $dt.in-timezone(-8 * 3600);     # OUTPUT: «2015-11-21T08:01:00-0800␤»
  
  my $now = DateTime.now(formatter => { sprintf "%02d:%02d", .hour, .minute });
  say $now;                           # 12:45 (or something like that)
  
  ```
  
  Since version 6.d, using synthetic codepoints such as 7̈ will result in an error.
  
  # [Methods](#class_DateTime "go to top of document")[§](#Methods "direct link")
  
  ## [method new](#class_DateTime "go to top of document")[§](#method_new "direct link")
  
  ```raku
  multi method new(Int :$year!, Int :$month = 1, Int :$day = 1,
                   Int :$hour = 0, Int :$minute = 0, :$second = 0,
                   Int :$timezone = 0, :&formatter)
  multi method new(Date :$date!,
                   Int :$hour = 0, Int :$minute = 0, :$second = 0,
                   Int :$timezone = 0, :&formatter)
  multi method new(Int() $year, Int() $month, Int() $day,
                   Int() $hour, Int $minute, $second,
                   Int() :$timezone = 0, :&formatter)
  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 `DateTime` object. One option for creating a new DateTime object is from the components (year, month, day, hour, ...) separately. Another is to pass a [`Date`](/type/Date) object for the date component, and specify the time component-wise. Yet another is to obtain the time from an [`Instant`](/type/Instant), and only supply the time zone and formatter. Or instead of an Instant you can supply a [`Numeric`](/type/Numeric) as a UNIX timestamp.
  
  You can also supply a [`Str`](/type/Str) formatted in ISO 8601 timestamp notation or as a full [RFC 3339](https://tools.ietf.org/html/rfc3339) date and time. Strings should be formatted as `yyyy-mm-ddThh:mm:ssZ` or `yyyy-mm-ddThh:mm:ss+0100`. We are somewhat less restrictive than the ISO 8601 standard, as we allow Unicode digits and mixing of condensed and extended time formats.
  
  An invalid input string throws an exception of type [`X::Temporal::InvalidFormat`](/type/X/Temporal/InvalidFormat). If you supply a string that includes a time zone and supply the `timezone` named argument, an exception of type [`X::DateTime::TimezoneClash`](/type/X/DateTime/TimezoneClash) is thrown.
  
  ```raku
  my $datetime = DateTime.new(year => 2015,
                              month => 1,
                              day => 1,
                              hour => 1,
                              minute => 1,
                              second => 1,
                              timezone => 1);
  $datetime = DateTime.new(date => Date.new('2015-12-24'),
                           hour => 1,
                           minute => 1,
                           second => 1,
                           timezone => 1);
  $datetime = DateTime.new(2015, 1, 1, # First January of 2015
                           1, 1, 1);   # Hour, minute, second with default time zone
  $datetime = DateTime.new(now);                       # Instant.
  # from a Unix timestamp
  say $datetime = DateTime.new(1470853583.3);          # OUTPUT: «2016-08-10T18:26:23.300000Z␤»
  $datetime = DateTime.new("2015-01-01T03:17:30+0500") # Formatted string
  ```
  
  Since Rakudo release 2022.03, the `day` parameter can be a [`Callable`](/type/Callable), with `*` returning the last day in the month, and `*-n` returning the last but `n`.
  
  Since Rakudo release 2022.07, it is also possible to just specify a "YYYY-MM-DD" string to indicate midnight on the given date.
  
  ```raku
  say DateTime.new("2023-03-04");  # OUTPUT: «2023-03-04T00:00:00Z␤»
  ```
  
  ## [method now](#class_DateTime "go to top of document")[§](#method_now "direct link")
  
  ```raku
  method now(:$timezone = $*TZ, :&formatter --> DateTime:D)
  ```
  
  Creates a new `DateTime` object from the current system time. A custom [formatter](/routine/formatter) and [timezone](/routine/timezone) can be provided. The `:$timezone` is the offset **in seconds** from [GMT](https://en.wikipedia.org/wiki/Greenwich_Mean_Time) and defaults to the value of [`$*TZ` variable](/language/variables#index-entry-%24*TZ).
  
  ```raku
  say DateTime.now; # OUTPUT: «2018-01-08T13:05:32.703292-06:00␤»
  ```
  
  Note that one may use the methods shown below chained to the `.now` to easily express current values, e.g.,
  
  ```raku
  say DateTime.now.year; # OUTPUT: «2018␤»
  ```
  
  ## [method clone](#class_DateTime "go to top of document")[§](#method_clone "direct link")
  
  ```raku
  method clone(DateTime:D: :$year, :$month, :$day, :$hour, :$minute, :$second, :$timezone, :&formatter)
  ```
  
  Creates a new `DateTime` object based on the invocant, but with the given arguments overriding the values from the invocant.
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00Z').clone(hour => 0);
  # OUTPUT: «2015-12-24T00:23:00Z␤»
  ```
  
  Note that this can lead to invalid dates in some circumstances:
  
  ```raku
  say DateTime.new("2012-02-29T12:34:56Z").clone(year => 2015);
  CATCH { default { put .^name, ': ', .Str } };
  # OUTPUT: «X::OutOfRange: Day out of range. Is: 29, should be in 1..28␤»
  ```
  
  ## [method hh-mm-ss](#class_DateTime "go to top of document")[§](#method_hh-mm-ss "direct link")
  
  ```raku
  method hh-mm-ss(DateTime:D: --> Str:D)
  ```
  
  Returns the time represented by the object as a string in 24-hour HH:MM:SS format:
  
  ```raku
  say DateTime.new("2052-02-29T22:34:56Z").hh-mm-ss;
  # OUTPUT: «22:34:56␤»
  ```
  
  ## [method hour](#class_DateTime "go to top of document")[§](#method_hour "direct link")
  
  ```raku
  method hour(DateTime:D: --> Int:D)
  ```
  
  Returns the hour component.
  
  ```raku
  say DateTime.new('2012-02-29T12:34:56Z').hour;      # OUTPUT: «12␤»
  ```
  
  ## [method minute](#class_DateTime "go to top of document")[§](#method_minute "direct link")
  
  ```raku
  method minute(DateTime:D: --> Int:D)
  ```
  
  Returns the minute component.
  
  ```raku
  say DateTime.new('2012-02-29T12:34:56Z').minute;     # OUTPUT: «34␤»
  ```
  
  ## [method second](#class_DateTime "go to top of document")[§](#method_second "direct link")
  
  ```raku
  method second(DateTime:D:)
  ```
  
  Returns the second component, including potentially fractional seconds.
  
  ```raku
  say DateTime.new('2012-02-29T12:34:56Z').second;     # OUTPUT: «56␤»
  say DateTime.new('2012-02-29T12:34:56.789Z').second; # OUTPUT: «56.789␤»
  say DateTime.new('2012-02-29T12:34:56,789Z').second; # comma also ok
  ```
  
  ## [method whole-second](#class_DateTime "go to top of document")[§](#method_whole-second "direct link")
  
  ```raku
  method whole-second(DateTime:D:)
  ```
  
  Returns the second component, rounded down to an [`Int`](/type/Int).
  
  ```raku
  say DateTime.new('2012-02-29T12:34:56.789Z').whole-second;      # OUTPUT: «56␤»
  ```
  
  ## [method timezone](#class_DateTime "go to top of document")[§](#method_timezone "direct link")
  
  ```raku
  method timezone(DateTime:D: --> Int:D)
  ```
  
  Returns the time zone **in seconds** as an offset from UTC.
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00+0200').timezone;          # OUTPUT: «7200␤»
  ```
  
  ## [method offset](#class_DateTime "go to top of document")[§](#method_offset "direct link")
  
  ```raku
  method offset(DateTime:D: --> Int:D)
  ```
  
  Returns the time zone **in seconds** as an offset from UTC. This is an alias for [method timezone](#method_timezone).
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00+0200').offset;            # OUTPUT: «7200␤»
  ```
  
  ## [method offset-in-minutes](#class_DateTime "go to top of document")[§](#method_offset-in-minutes "direct link")
  
  ```raku
  method offset-in-minutes(DateTime:D: --> Real:D)
  ```
  
  Returns the time zone in minutes as an offset from UTC.
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00+0200').offset-in-minutes; # OUTPUT: «120␤»
  ```
  
  ## [method offset-in-hours](#class_DateTime "go to top of document")[§](#method_offset-in-hours "direct link")
  
  ```raku
  method offset-in-hours(DateTime:D: --> Real:D)
  ```
  
  Returns the time zone in hours as an offset from UTC.
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00+0200').offset-in-hours;   # OUTPUT: «2␤»
  
  ```
  
  ## [method Str](#class_DateTime "go to top of document")[§](#method_Str "direct link")
  
  ```raku
  method Str(DateTime:D: --> Str:D)
  ```
  
  Returns a string representation of the invocant, as done by [the formatter](/type/Dateish#method_formatter). If no formatter was specified, an ISO 8601 timestamp will be returned.
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00+0200').Str;
  # OUTPUT: «2015-12-24T12:23:00+02:00␤»
  
  ```
  
  ## [method Instant](#class_DateTime "go to top of document")[§](#method_Instant "direct link")
  
  ```raku
  method Instant(DateTime:D: --> Instant:D)
  ```
  
  Returns an [`Instant`](/type/Instant) object based on the invocant.
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00+0200').Instant; # OUTPUT: «Instant:1450952616␤»
  ```
  
  ## [method Real](#class_DateTime "go to top of document")[§](#method_Real "direct link")
  
  ```raku
  multi method Real(DateTime:D: --> Instant:D)
  ```
  
  Converts the invocant to [`Instant`](/type/Instant). The same value can be obtained with the [`Instant`](/type/Instant) method.
  
  Available as of release 2023.02 of the Rakudo compiler.
  
  ## [method Numeric](#class_DateTime "go to top of document")[§](#method_Numeric "direct link")
  
  ```raku
  multi method Numeric(DateTime:D: --> Instant:D)
  ```
  
  Available as of the 2021.09 release of the Rakudo compiler.
  
  Converts the invocant to [`Instant`](/type/Instant). The same value can be obtained with the [`Instant`](/type/Instant) method. This allows `DateTime` objects to be used directly in arithmetic operations.
  
  ## [method day-fraction](#class_DateTime "go to top of document")[§](#method_day-fraction "direct link")
  
  ```raku
  method day-fraction(DateTime:D: --> Real:D)
  ```
  
  Returns the instant's time as a fraction of a 24-hour day.
  
  ```raku
  say DateTime.new('2021-12-24T12:23:00.43Z').day-fraction; # OUTPUT: «0.5159772␤»
  ```
  
  Notice the `day-fraction` value is the same as the fractional part of the `modified-julian-date` for the same instant.
  
  Available as of the 2021.04 Rakudo compiler release.
  
  ## [method julian-date](#class_DateTime "go to top of document")[§](#method_julian-date "direct link")
  
  ```raku
  method julian-date(DateTime:D: --> Real:D)
  ```
  
  Returns the [Julian date](https://en.wikipedia.org/wiki/Julian_day) (JD) for the UTC date and time.
  
  ```raku
  say DateTime.new('2021-12-24T12:23:00.43Z').julian-date; # OUTPUT: «2459573.0159772␤»
  ```
  
  The `julian-date` starts at zero at the epoch of noon UTC on *November 24, 4714 B.C.* on the [proleptic](https://en.m.wiktionary.org/wiki/proleptic) Gregorian calendar (the calendar in use in much of the world and in international commerce and travel). The JD is used in astronomy to define times of celestial objects transiting the Earth's Prime Meridian. For any instant, it is the sum of the number of whole days and the fraction of a day from that epoch to that instant.
  
  Available as of the 2021.04 Rakudo compiler release.
  
  ## [method modified-julian-date](#class_DateTime "go to top of document")[§](#method_modified-julian-date "direct link")
  
  ```raku
  method modified-julian-date(DateTime:D: --> Real:D)
  ```
  
  Returns the [Modified Julian Date](https://en.wikipedia.org/wiki/Julian_day) (MJD) for the UTC date and time.
  
  ```raku
  say DateTime.new('2021-12-24T12:23:00.43Z').modified-julian-date; # OUTPUT: «59572.5159772␤»
  ```
  
  Notice the fractional part of the `modified-julian-date` is same value as the `day-fraction` for the same instant. Likewise, the integral part of the *MJD* is the same value as the `daycount` for the same instant since they reference the same epoch (November 17, 1858). The MJD is obtained by subtracting the constant `2_400_000.5` from the *Julian Date* and is used to simplify transformations between civil and astronomical time systems.
  
  Available as of the 2021.04 Rakudo compiler release.
  
  ## [method posix](#class_DateTime "go to top of document")[§](#method_posix "direct link")
  
  ```raku
  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, 1970-01-01T00:00:00Z).
  
  If `$ignore-timezone` is `True`, the `DateTime` object will be treated as if the time zone offset is zero.
  
  ```raku
  method posix(Bool:D: $ignore-timezone = False, :$real --> Num:D)
  ```
  
  As of release 2022.06 of the Rakudo compiler, it is also possible to specify a `:real` named argument. If specified with a true value, a [`Num`](/type/Num) will be returned, allowing for sub-second accuracy of the number of seconds since the POSIX epoch.
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00Z').posix;           # OUTPUT: «1450959780␤»
  say DateTime.new('2022-06-21T12:23:00.5Z').posix;         # OUTPUT: «1655814180␤»
  say DateTime.new('2022-06-21T12:23:00.5Z').posix(:real);  # OUTPUT: «1655814180.5␤»
  
  ```
  
  ## [method truncated-to](#class_DateTime "go to top of document")[§](#method_truncated-to "direct link")
  
  ```raku
  method truncated-to(DateTime:D: Cool $unit)
  ```
  
  Returns a copy of the invocant, with everything smaller than the specified unit truncated to the smallest possible value.
  
  ```raku
  my $d = DateTime.new("2012-02-29T12:34:56.946314Z");
  say $d.truncated-to('second');      # OUTPUT: «2012-02-29T12:34:56Z␤»
  say $d.truncated-to('minute');      # OUTPUT: «2012-02-29T12:34:00Z␤»
  say $d.truncated-to('hour');        # OUTPUT: «2012-02-29T12:00:00Z␤»
  say $d.truncated-to('day');         # OUTPUT: «2012-02-29T00:00:00Z␤»
  say $d.truncated-to('month');       # OUTPUT: «2012-02-01T00:00:00Z␤»
  say $d.truncated-to('year');        # OUTPUT: «2012-01-01T00:00:00Z␤»
  ```
  
  DateTimes with fractional seconds can be truncated to whole seconds with `.truncated-to('second')`.
  
  ## [method Date](#class_DateTime "go to top of document")[§](#method_Date "direct link")
  
  ```raku
  multi method Date(DateTime:U --> Date:U)
  multi method Date(DateTime:D --> Date:D)
  ```
  
  Converts the invocant to [`Date`](/type/Date).
  
  ```raku
  say DateTime.new("2012-02-29T12:34:56.946314Z").Date; # OUTPUT: «2012-02-29␤»
  say DateTime.Date;                                    # OUTPUT: «(Date)␤»
  
  ```
  
  ## [method DateTime](#class_DateTime "go to top of document")[§](#method_DateTime "direct link")
  
  ```raku
  method DateTime(--> DateTime)
  ```
  
  Returns the invocant.
  
  ```raku
  say DateTime.new("2012-02-29T12:34:56.946314Z").DateTime;
  # OUTPUT: «2012-02-29T12:34:56.946314Z␤»
  say DateTime.DateTime;
  # OUTPUT: «(DateTime)␤»
  ```
  
  ## [method utc](#class_DateTime "go to top of document")[§](#method_utc "direct link")
  
  ```raku
  method utc(DateTime:D: --> DateTime:D)
  ```
  
  Returns a DateTime object for the same time, but in time zone UTC.
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00+0200').utc;
  # OUTPUT: «2015-12-24T10:23:00Z␤»
  ```
  
  ## [method in-timezone](#class_DateTime "go to top of document")[§](#method_in-timezone "direct link")
  
  ```raku
  method in-timezone(DateTime:D: Int(Cool) $timezone = 0 --> DateTime:D)
  ```
  
  Returns a DateTime object for the same time, but in the specified `$timezone`, which is the offset **in seconds** from [GMT](https://en.wikipedia.org/wiki/Greenwich_Mean_Time).
  
  ```raku
  say DateTime.new('2015-12-24T12:23:00Z').in-timezone(3600 + 1800); # OUTPUT: «2015-12-24T13:53:00+0130␤»
  ```
  
  Per [RFC 7164](https://tools.ietf.org/html/rfc7164#section-3), leap seconds do not respect local time and always occur at the end of the *UTC* day:
  
  ```raku
  say DateTime.new: '2017-01-01T00:59:60+01:00'
  # OUTPUT: «2017-01-01T00:59:60+01:00␤»
  ```
  
  ## [method local](#class_DateTime "go to top of document")[§](#method_local "direct link")
  
  ```raku
  method local(DateTime:D: --> DateTime:D)
  ```
  
  Returns a DateTime object for the same time, but in the local time zone ([`$*TZ`](/language/variables#index-entry-%24*TZ)).
  
  ```raku
  my $*TZ = -3600;
  say DateTime.new('2015-12-24T12:23:00+0200').local; # OUTPUT: «2015-12-24T09:23:00-0100␤»
  ```
  
  ## [sub infix:<->](#class_DateTime "go to top of document")[§](#sub_infix:<-> "direct link")
  
  ```raku
  multi infix:<-> (DateTime:D, Duration:D --> DateTime:D)
  multi infix:<-> (DateTime:D, DateTime:D --> Duration:D)
  ```
  
  Takes a `DateTime` to subtract from and either a [`Duration`](/type/Duration) or another `DateTime` object. Returns a new `DateTime` object or the [`Duration`](/type/Duration) between the two dates, respectively. When subtracting [`Duration`](/type/Duration), time zone of the original `DateTime` is preserved in the returned `DateTime` object.
  
  ```raku
  say raku DateTime.new(:2016year) - DateTime.new(:2015year):;
  # OUTPUT: «Duration.new(31536001.0)␤»
  say DateTime.new(:2016year, :3600timezone) - Duration.new(31536001.0);
  # OUTPUT: «2015-01-01T00:00:00+01:00␤»
  ```
  
  ## [sub infix:<+>](#class_DateTime "go to top of document")[§](#sub_infix:<+> "direct link")
  
  ```raku
  multi infix:<+> (DateTime:D, Duration:D --> DateTime:D)
  multi infix:<+> (Duration:D, DateTime:D --> DateTime:D)
  ```
  
  Takes a `DateTime` and increases it by the given [`Duration`](/type/Duration), preserving the time zone.
  
  ```raku
  say DateTime.new(:2015year) + Duration.new(31536001.0);
  # OUTPUT: «2016-01-01T00:00:00Z␤»
  say Duration.new(42) + DateTime.new(:2015year, :3600timezone);
  # OUTPUT: «2015-01-01T00:00:42+01:00␤»
  ```
  
  ## [sub infix:<cmp>](#class_DateTime "go to top of document")[§](#sub_infix:<cmp> "direct link")
  
  ```raku
  multi infix:<cmp>(DateTime:D \a, DateTime:D \b --> Order:D)
  ```
  
  Compares the equivalent instant, returns the Order.
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `DateTime`
  
  
  
  raku-type-graph
  
  
  
  DateTime
  DateTime
  
  
  Any
  Any
  
  
  DateTime->Any
  
  
  
  Dateish
  Dateish
  
  
  DateTime->Dateish
  
  
  
  Mu
  Mu
  
  
  Any->Mu
  
  [Expand chart above](/assets/typegraphs/DateTime.svg)
  