Rules / Types, classes & roles / basic

DateTime Reference

Calendar date with time

What it is #

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method new #

multi method new(Int :$year!, Int :$month = 1, Int :$day = 1,
multi method new(Date :$date!,
multi method new(Int() $year, Int() $month, Int() $day,
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 timezone and formatter. Or instead of an Instant you can supply a Numeric as a Unix timestamp

method now #

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

Returns 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. Note that one may use the methods shown below chained to the .now to easily express current

method clone #

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. Note that this can lead to invalid dates in some circumstances:

method hh-mm-ss #

method hh-mm-ss(DateTime:D: --> Str:D)

Returns Str:D.

Returns the time represented by the object as a string in 24-hour HH:MM:SS format:

method hour #

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

Returns Int:D.

Returns the hour component.

method minute #

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

Returns Int:D.

Returns the minute component.

method second #

method second(DateTime:D:)

Returns the second component, including potentially fractional seconds.

method whole-second #

method whole-second(DateTime:D:)

Returns the second component, rounded down to an Int.

method timezone #

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

Returns Int:D.

Returns the timezone in seconds as an offset from UTC.

method offset #

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

Returns Int:D.

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

method offset-in-minutes #

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

Returns Real:D.

Returns the timezone in minutes as an offset from UTC.

method offset-in-hours #

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

Returns Real:D.

Returns the timezone in hours as an offset from UTC.

method Str #

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

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

method Instant #

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

Returns Instant:D.

Returns an Instant object based on the invocant.

method Real #

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

Returns Instant:D.

Converts the invocant to Instant. The same value can be obtained with the Instant method. Available as of release 2023.02 of the Rakudo compiler.

method Numeric #

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

Returns Instant:D.

Available as of the 2021.09 release of the Rakudo compiler. Converts the invocant to Instant. The same value can be obtained with the Instant method. This allows DateTime objects to be used directly in arithmetic operations.

method day-fraction #

method day-fraction(DateTime:D: --> Real:D)

Returns Real:D.

Returns the instant's time as a fraction of a 24-hour day. Notice the day-fraction value is the same as the fractional part of the modified-julian-date for the same instant. Also note that leap seconds may cause some variations from expected values: Available as of the 2021.04 Rakudo compiler release.

method julian-date #

method julian-date(DateTime:D: --> Real:D)

Returns Real:D.

Returns the Julian date (JD) for the UTC date and time. The julian-date starts at zero at the epoch of noon UTC on November 24, 4714 B.C. on the 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

method modified-julian-date #

method modified-julian-date(DateTime:D: --> Real:D)

Returns Real:D.

Returns the Modified Julian Date (MJD) for the UTC date and time. Notice the fractional part of the modified-julian-date is same value as the day-fraction for the same instant, and is similarly affected by leap seconds. Likewise, the integral part of the MJD is the same value as the daycount for the same instant since they

method posix #

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

Returns Int:D.

Returns the date and time as a POSIX/Unix timestamp (non-leap seconds since the POSIX epoch, 1970-01-01T00:00:00Z). If $ignore-timezone is True, the DateTime object will be treated as if the timezone offset is zero. Note that this will collapse both a leap second and the second immediately following it into the same timestamp, because POSIX time ignores leap seconds. If you need better than this, see Instant for the relevant

method truncated-to #

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. DateTimes with fractional seconds can be truncated to whole seconds with .truncated-to('second').

method Date #

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

Returns Date:U or Date:D.

Converts the invocant to Date.

method DateTime #

method DateTime(--> DateTime)

Returns DateTime.

Returns the invocant.

method utc #

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

Returns DateTime:D.

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

method in-timezone #

method in-timezone(DateTime:D: Int(Cool) $timezone = 0 --> DateTime:D)

Returns DateTime:D.

Returns a DateTime object for the same time, but in the specified $timezone, which is the offset in seconds from GMT. Per RFC 7164, leap seconds do not respect local time and always occur at the end of the UTC day:

method local #

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

Returns DateTime:D.

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

sub infix:<-> #

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

Returns DateTime:D or 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, timezone of the original DateTime is preserved in the returned DateTime object.

sub infix:<+> #

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

Returns DateTime:D.

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

sub infix:<cmp> #

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

Returns Order:D.

Compares the equivalent instant, returns the Order.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

1 all-differ · 5 doc-drift · 3 no-output · 23 ok · 1 rakudo-differs · 2 rakupp-differs

class DateTime does Dateish {}

Not executed: the documentation states no expected output for this example.

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)
Documentation
2015-11-21T16:01:00Z
2015-12-11T16:01:00Z
2015-11-21T16:00:00Z
2015-11-21T08:01:00-0800
Rakudo
2015-11-21T16:01:00Z
2015-12-11T16:01:00Z
2015-11-21T16:00:00Z
2015-11-21T08:01:00-08:00
17:17
Raku++
2015-11-21T16:01:00Z
2015-12-11T16:01:00Z
2015-11-21T16:00:00Z
2015-11-21T08:01:00-08:00
17:17

Both engines agree; the documentation states something else. Trust the engines.

             Int :$hour = 0, Int :$minute = 0, :$second = 0,
             Int :$timezone = 0, :&formatter)
             Int :$hour = 0, Int :$minute = 0, :$second = 0,
             Int :$timezone = 0, :&formatter)
             Int() $hour, Int $minute, $second,
             Int() :$timezone = 0, :&formatter)

Not executed: the documentation states no expected output for this example.

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 timezone
$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
Output
2016-08-10T18:26:23.300000Z

Documentation, Rakudo and Raku++ all agree.

say DateTime.new("2023-03-04");  # OUTPUT: «2023-03-04T00:00:00Z␤»
Output
2023-03-04T00:00:00Z

Documentation, Rakudo and Raku++ all agree.

say DateTime.now; # OUTPUT: «2018-01-08T13:05:32.703292-06:00␤»
Documentation
2018-01-08T13:05:32.703292-06:00
Rakudo
2026-07-28T17:17:42.598780+02:00
Raku++
2026-07-28T17:17:42+02:00

All three differ. Needs a human.

Not yet examined. Which of these is correct has not been established — do not treat either engine as settled here.

say DateTime.now.year; # OUTPUT: «2018␤»
Documentation
2018
Rakudo
2026
Raku++
2026

Both engines agree; the documentation states something else. Trust the engines.

say DateTime.new('2015-12-24T12:23:00Z').clone(hour => 0);
# OUTPUT: «2015-12-24T00:23:00Z␤»
Output
2015-12-24T00:23:00Z

Documentation, Rakudo and Raku++ all agree.

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␤»
Documentation
X::OutOfRange: Day out of range. Is: 29, should be in 1..28
Rakudo
X::Temporal::OutOfRange: Day out of range. Is: 29, should be in 1..28
Raku++
X::OutOfRange: Day out of range. Is: 29, should be in 1..28

Raku++ matches the documentation; Rakudo does not. This is the one class where neither engine can be assumed right: it may be a stale doc that Raku++ was built from, or it may be a Rakudo bug that the documentation predates. Each case is examined individually.

Not yet examined. Which of these is correct has not been established — do not treat either engine as settled here.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

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
Documentation
56
56.789
Rakudo
56
56.789
56.789
Raku++
56
56.789
56.789

Both engines agree; the documentation states something else. Trust the engines.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

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

Raku++ disagrees with both the documentation and Rakudo — a defect.

say DateTime.new('2021-12-24T12:23:00.43Z').day-fraction; # OUTPUT: «0.5159772␤»
Output
0.5159772

Documentation, Rakudo and Raku++ all agree.

for 30, 31 { say DateTime.new(2016,12,$_,12,0,0).day-fraction }
# OUTPUT: «0.5␤0.499994␤»
Output
0.5
0.499994

Documentation, Rakudo and Raku++ all agree.

say DateTime.new('2021-12-24T12:23:00.43Z').julian-date; # OUTPUT: «2459573.0159772␤»
Output
2459573.0159772

Documentation, Rakudo and Raku++ all agree.

say DateTime.new('2021-12-24T12:23:00.43Z').modified-julian-date; # OUTPUT: «59572.5159772␤»
Output
59572.5159772

Documentation, Rakudo and Raku++ all agree.

method posix(Bool:D: $ignore-timezone = False, :$real --> Num:D)

Not executed: the documentation states no expected output for this example.

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␤»
Output
1450959780
1655814180
1655814180.5

Documentation, Rakudo and Raku++ all agree.

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␤»
Output
2012-02-29T12:34:56Z
2012-02-29T12:34:00Z
2012-02-29T12:00:00Z
2012-02-29T00:00:00Z
2012-02-01T00:00:00Z
2012-01-01T00:00:00Z

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

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

Both engines agree; the documentation states something else. Trust the engines.

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

Documentation, Rakudo and Raku++ all agree.

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

Both engines agree; the documentation states something else. Trust the engines.

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␤»
Documentation
Duration.new(31536001.0)
2015-01-01T00:00:00+01:00
Rakudo
Duration.new(31536001.0)
2015-01-01T00:00:00+01:00
Raku++
31536001e0
2015-01-01T00:00:00+01:00

Raku++ disagrees with both the documentation and Rakudo — a defect.

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␤»
Output
2016-01-01T00:00:00Z
2015-01-01T00:00:42+01:00

Documentation, Rakudo and Raku++ all agree.