class DateTime does Dateish {}

For handling points in civil time, a DateTime object stores year, month, day, hour, minute (all Int), second (potentially fractional) and a time zone.

It provides methods for calculating with date and time.

DateTime methods are immutable; if you are tempted to modify one, create a modified copy instead.

Time zones are handled as Integers in seconds offset from UTC, not by time zone name.

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

method new

Defined as:

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 object for the date component, and specify the time component-wise. Yet another is to obtain the time from an Instant, and only supply the time zone and formatter. Or instead of an Instant you can supply an Numeric as a UNIX timestamp.

You can also supply a Str formatted in ISO 8601 timestamp notation or as a full RFC 3339 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. If you supply a string that includes a time zone and supply the timezone named argument, an exception of type X::DateTime::TimezoneClash is thrown.

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

method now

Defined as:

method now(:$timezone = $*TZ, :&formatter --> DateTime:D)

Creates a new DateTime object from the current system time. A custom formatter and timezone can be provided. The :$timezone is the offset in seconds from GMT and defaults to the value of $*TZ variable.

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.,

say DateTime.now.year; # OUTPUT: «2018␤»

method clone

Defined as:

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.

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:

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

Defined as:

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:

say DateTime.new("2052-02-29T22:34:56Z").hh-mm-ss;
# OUTPUT: «22:34:56␤»

method hour

Defined as:

method hour(DateTime:D: --> Int:D)

Returns the hour component.

say DateTime.new('2012-02-29T12:34:56Z').hour;      # OUTPUT: «12␤»

method minute

Defined as:

method minute(DateTime:D: --> Int:D)

Returns the minute component.

say DateTime.new('2012-02-29T12:34:56Z').minute;     # OUTPUT: «34␤»

method second

Defined as:

method second(DateTime:D:)

Returns the second component, including potentially fractional seconds.

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

Defined as:

method whole-second(DateTime:D:)

Returns the second component, rounded down to an Int.

say DateTime.new('2012-02-29T12:34:56.789Z').whole-second;      # OUTPUT: «56␤»

method timezone

Defined as:

method timezone(DateTime:D: --> Int:D)

Returns the time zone in seconds as an offset from UTC.

say DateTime.new('2015-12-24T12:23:00+0200').timezone;          # OUTPUT: «7200␤»

method offset

Defined as:

method offset(DateTime:D: --> Int:D)

Returns the time zone in seconds as an offset from UTC. This is an alias for #method timezone.

say DateTime.new('2015-12-24T12:23:00+0200').offset;            # OUTPUT: «7200␤»

method offset-in-minutes

Defined as:

method offset-in-minutes(DateTime:D: --> Real:D)

Returns the time zone in minutes as an offset from UTC.

say DateTime.new('2015-12-24T12:23:00+0200').offset-in-minutes; # OUTPUT: «120␤»

method offset-in-hours

Defined as:

method offset-in-hours(DateTime:D: --> Real:D)

Returns the time zone in hours as an offset from UTC.

say DateTime.new('2015-12-24T12:23:00+0200').offset-in-hours;   # OUTPUT: «2␤» 

method Str

Defined as:

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

Returns a string representation of the invocant, as done by the formatter. If no formatter was specified, an ISO 8601 timestamp will be returned.

say DateTime.new('2015-12-24T12:23:00+0200').Str;
# OUTPUT: «2015-12-24T12:23:00+02:00␤» 

method Instant

Defined as:

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

Returns an Instant object based on the invocant.

say DateTime.new('2015-12-24T12:23:00+0200').Instant; # OUTPUT: «Instant:1450952616␤»

method posix

Defined as:

method posix(Bool:D: $ignore-timezone = False --> Int:D)

Returns the date and time as a POSIX/UNIX timestamp (seconds since the Epoch, 1st January 1970 UTC).

If $ignore-timezone is True, the DateTime object will be treated as if the time zone offset is zero.

say DateTime.new('2015-12-24T12:23:00Z').posix;       # OUTPUT: «1450959780␤» 

method truncated-to

Defined as:

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.

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

Defined as:

multi method Date(DateTime:U --> Date:U)
multi method Date(DateTime:D --> Date:D)

Converts the invocant to Date.

say DateTime.new("2012-02-29T12:34:56.946314Z").Date; # OUTPUT: «2012-02-29␤» 
say DateTime.Date;                                    # OUTPUT: «(Date)␤» 

method DateTime

Defined as:

method DateTime(--> DateTime)

Returns the invocant.

say DateTime.new("2012-02-29T12:34:56.946314Z").DateTime;
# OUTPUT: «2012-02-29T12:34:56.946314Z␤» 
say DateTime.DateTime;
# OUTPUT: «(DateTime)␤»

method utc

Defined as:

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

Returns a DateTime object for the same time, but in time zone UTC.

say DateTime.new('2015-12-24T12:23:00+0200').utc;
# OUTPUT: «2015-12-24T10:23:00Z␤»

method in-timezone

Defined as:

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.

say DateTime.new('2015-12-24T12:23:00Z').in-timezone(3600 + 1800); # OUTPUT: «2015-12-24T13:53:00+0130␤»

Per RFC 7164, leap seconds do not respect local time and always occur at the end of the UTC day:

say DateTime.new: '2017-01-01T00:59:60+01:00'
# OUTPUT: «2017-01-01T00:59:60+01:00␤»

method local

Defined as:

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

Returns a DateTime object for the same time, but in the local time zone ($*TZ).

my $*TZ = -3600;
say DateTime.new('2015-12-24T12:23:00+0200').local; # OUTPUT: «2015-12-24T09:23:00-0100␤»

sub infix:<->

multi sub infix:<-> (DateTime:D, Duration:D --> DateTime:D)
multi sub infix:<-> (DateTime:D, DateTime:D --> Duration:D)

Takes a DateTime to subtract from and either a Duration or another DateTime object. Returns a new DateTime object or the Duration between the two dates, respectively. When subtracting Duration, time zone of the original DateTime is preserved in the returned DateTime object.

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:<+>

multi sub infix:<+> (DateTime:D, Duration:D --> DateTime:D)
multi sub infix:<+> (Duration:D, DateTime:D --> DateTime:D)

Takes a DateTime and increases it by the given Duration, preserving the time zone.

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:«<=>»

multi sub infix:«<=>»(DateTime:D \a, DateTime:D \b --> Order:D)

Compares the equivalent instant, returns the Order.

say DateTime.now <=> DateTime.now; # OUTPUT: «Less␤»

sub infix:<cmp>

multi sub infix:<cmp>(DateTime:D \a, DateTime:D \b --> Order:D)

Compares the equivalent instant, returns the Order.

sub infix:«<»

multi sub infix:«<»(DateTime:D \a, DateTime:D \b --> Bool:D)

Compares the equivalent instant, returns a Bool

sub infix:«>»

multi sub infix:«>»(DateTime:D \a, DateTime:D \b --> Bool:D)

Compares the equivalent instant, returns a Bool

sub infix:«<=»

multi sub infix:«<=»(DateTime:D \a, DateTime:D \b --> Bool:D)

Compares the equivalent instant, returns a Bool

sub infix:«>=»

multi sub infix:«>=»(DateTime:D \a, DateTime:D \b --> Bool:D)

Compares the equivalent instant, returns a Bool

sub infix:«==»

multi sub infix:«==»(DateTime:D \a, DateTime:D \b --> Bool:D)

Compares the equivalent instant, returns a Bool

sub infix:«!=»

multi sub infix:«!=»(DateTime:D \a, DateTime:D \b --> Bool:D)

Compares the equivalent instant, returns a Bool