class DateTime

Calendar date with time

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 (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 Integers in seconds offset from UTC, not by time zone name.

my $dt =
    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 $ * 3600);     # OUTPUT: «2015-11-21T08:01:00-0800␤» 
my $now = => { 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.


method new

Defined as:

multi method new(Int :$year!Int :$month = 1Int :$day = 1,
                 Int :$hour = 0Int :$minute = 0:$second = 0,
                 Int :$timezone = 0:&formatter)
multi method new(Date :$date!,
                 Int :$hour = 0Int :$minute = 0:$second = 0,
                 Int :$timezone = 0:&formatter)
multi method new(Int() $yearInt() $monthInt() $day,
                 Int() $hourInt $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 = => 2015,
                            month => 1,
                            day => 1,
                            hour => 1,
                            minute => 1,
                            second => 1,
                            timezone => 1);
$datetime = =>'2015-12-24'),
                         hour => 1,
                         minute => 1,
                         second => 1,
                         timezone => 1);
$datetime = First January of 2015 
                         111);   # Hour, minute, second with default time zone 
$datetime =;                       # Instant. 
# from a Unix timestamp 
say $datetime =;          # OUTPUT: «2016-08-10T18:26:23.300000Z␤» 
$datetime ="2015-01-01T03:17:30+0500"# Formatted string

Since Rakudo release 2022.03, the day parameter can be a Callable, with * returning the last day in the month, and *-n returning the last but n.

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 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 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'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"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:

# OUTPUT: «22:34:56␤»

method hour

Defined as:

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

Returns the hour component.

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

method minute

Defined as:

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

Returns the minute component.

say'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'2012-02-29T12:34:56Z').second;     # OUTPUT: «56␤» 
say'2012-02-29T12:34:56.789Z').second# OUTPUT: «56.789␤» 
say'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'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'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'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'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'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.

# 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'2015-12-24T12:23:00+0200').Instant# OUTPUT: «Instant:1450952616␤»

method day-fraction

Defined as:

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

Returns the instant's time as a fraction of a 24-hour day.

say'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.

method julian-date

Defined as:

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

Returns the Julian date (JD) for the UTC date and time.

say'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 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.

method modified-julian-date

Defined as:

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

Returns the Modified Julian Date (MJD) for the UTC date and time.

say'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.

method posix

Defined as:

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.

say'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 ="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"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.

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

# 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'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 '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'2015-12-24T12:23:00+0200').local# OUTPUT: «2015-12-24T09:23:00-0100␤»

sub infix:<->

multi sub infix:<-> (DateTime:DDuration:D --> DateTime:D)
multi sub infix:<-> (DateTime:DDateTime: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 -;
# OUTPUT: «␤» 
say, :3600timezone) -;
# OUTPUT: «2015-01-01T00:00:00+01:00␤»

sub infix:<+>

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

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

say +;
# OUTPUT: «2016-01-01T00:00:00Z␤» 
say, :3600timezone);
# OUTPUT: «2015-01-01T00:00:42+01:00␤»

sub infix:«<=>»

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

Compares the equivalent instant, returns the Order.

say <=> OUTPUT: «Less␤»

sub infix:<cmp>

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

Compares the equivalent instant, returns the Order.

sub infix:«<»

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

Compares the equivalent instant, returns a Bool

sub infix:«>»

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

Compares the equivalent instant, returns a Bool

sub infix:«<=»

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

Compares the equivalent instant, returns a Bool

sub infix:«>=»

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

Compares the equivalent instant, returns a Bool

sub infix:«==»

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

Compares the equivalent instant, returns a Bool

sub infix:«!=»

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

Compares the equivalent instant, returns a Bool

Type Graph

Type relations for DateTime
perl6-type-graph DateTime DateTime Any Any DateTime->Any Dateish Dateish DateTime->Dateish Mu Mu Any->Mu

Expand above chart

Routines supplied by role Dateish

DateTime does role Dateish, which provides the following routines:

(Dateish) method year

Defined as:

method year(Date:D: --> Int:D)

Returns the year of the date.

say'2015-12-31').year;                                  # OUTPUT: «2015␤» 
say =>'2015-12-24'), hour => 1).year# OUTPUT: «2015␤»

(Dateish) method month

Defined as:

method month(Date:D: --> Int:D)

Returns the month of the date (1..12).

say'2015-12-31').month;                                  # OUTPUT: «12␤» 
say =>'2015-12-24'), hour => 1).month# OUTPUT: «12␤»

(Dateish) method day

Defined as:

method day(Date:D: --> Int:D)

Returns the day of the month of the date (1..31).

say'2015-12-31').day;                                  # OUTPUT: «31␤» 
say =>'2015-12-24'), hour => 1).day# OUTPUT: «24␤»

(Dateish) method formatter

Defined as:

method formatter(Dateish:D:)

Returns the formatting function which is used for conversion to Str. If none was provided at object construction, a default formatter is used. In that case the method will return a Callable type object.

The formatting function is called by DateTime method Str with the invocant as its only argument.

my $dt ='2015-12-31');  # (no formatter specified) 
say $dt.formatter.^name;          # OUTPUT: «Callable␤» 
my $us-format = sub ($self{ sprintf "%02d/%02d/%04d" given $self};
$dt ='2015-12-31'formatter => $us-format);
say $dt.formatter.^name;           # OUTPUT: «Sub␤» 
say $dt;                          # OUTPUT: «12/31/2015␤»

(Dateish) method is-leap-year

Defined as:

method is-leap-year(Dateish:D: --> Bool:D)

Returns True if the year of the Dateish object is a leap year.

say<2016>).is-leap-year# OUTPUT: «True␤» 
say"1900-01-01").is-leap-year;    # OUTPUT: «False␤»

(Dateish) method day-of-month

Defined as:

method day-of-month(Date:D: --> Int:D)

Returns the day of the month of the date (1..31). Synonymous to the day method.

say'2015-12-31').day-of-month;                                  # OUTPUT: «31␤» 
say =>'2015-12-24'), hour => 1).day-of-month# OUTPUT: «24␤»

(Dateish) method day-of-week

Defined as:

method day-of-week(Date:D: --> Int:D)

Returns the day of the week, where 1 is Monday, 2 is Tuesday and Sunday is 7.

say'2015-12-31').day-of-week;                                  # OUTPUT: «4␤» 
say =>'2015-12-24'), hour => 1).day-of-week# OUTPUT: «4␤»

(Dateish) method day-of-year

Defined as:

method day-of-year(Date:D: --> Int:D)

Returns the day of the year (1..366).

say'2015-12-31').day-of-year;                                  # OUTPUT: «365␤» 
say =>'2015-03-24'), hour => 1).day-of-year# OUTPUT: «83␤»

(Dateish) method days-in-month

Defined as:

method days-in-month(Dateish:D: --> Int:D)

Returns the number of days in the month represented by the Dateish object:

say"2016-01-02").days-in-month;                # OUTPUT: «31␤» 
say<10000>:month<2>).days-in-month# OUTPUT: «29␤»

(Dateish) method week

Defined as:

method week()

Returns a list of two integers: the year, and the week number. This is because at the start or end of a year, the week may actually belong to the other year.

my ($year$week="2014-12-31").week;
say $year;                       # OUTPUT: «2015␤» 
say $week;                       # OUTPUT: «1␤» 
say'2015-01-31').week# OUTPUT: «(2015 5)␤»

(Dateish) method week-number

Defined as:

method week-number(Date:D: --> Int:D)

Returns the week number (1..53) of the date specified by the invocant. The first week of the year is defined by ISO as the one which contains the fourth day of January. Thus, dates early in January often end up in the last week of the prior year, and similarly, the final few days of December may be placed in the first week of the next year.

say"2014-12-31").week-number;   # 1  (first week of 2015) 
say"2016-01-02").week-number;   # 53 (last week of 2015)

(Dateish) method week-year

Defined as:

method week-year(Date:D: --> Int:D)

Returns the week year of the date specified by the invocant. Normally week-year is equal to Date.year. Note however that dates early in January often end up in the last week of the prior year, and similarly, the final few days of December may be placed in the first week of the next year.

say"2015-11-15").week-year;   # 2015 
say"2014-12-31").week-year;   # 2015 (date belongs to the first week of 2015) 
say"2016-01-02").week-year;   # 2015 (date belongs to the last week of 2015)

(Dateish) method weekday-of-month

Defined as:

method weekday-of-month(Date:D: --> Int:D)

Returns a number (1..5) indicating the number of times a particular day-of-week has occurred so far during that month, the day itself included.

say"2003-06-09").weekday-of-month;  # 2  (second Monday of the month)

(Dateish) method yyyy-mm-dd

Defined as:

method yyyy-mm-dd(str $sep = "-" --> Str:D)

Returns the date in YYYY-MM-DD format (ISO 8601). The optional positional argument $sep, which defaults to -, is a one-character separator placed between the different parts of the date.

say"2015-11-15").yyyy-mm-dd;   # OUTPUT: «2015-11-15␤» 
say OUTPUT: «2016-08-10␤» 
say"/");          # OUTPUT: «2020/03/14␤» 

(Dateish) method mm-dd-yyyy

Defined as:

method mm-dd-yyyy(str $sep = "-" --> Str:D)

Returns the date in MM-DD-YYYY format (ISO 8601). The optional positional argument $sep, which defaults to -, is a one-character separator placed between the different parts of the date.

say"2015-11-15").mm-dd-yyyy;   # OUTPUT: «11-15-2015␤» 
say OUTPUT: «08-10-2016␤» 
say"/");          # OUTPUT: «03/14/2020␤» 

(Dateish) method dd-mm-yyyy

Defined as:

method dd-mm-yyyy(str $sep = "-" --> Str:D)

Returns the date in DD-MM-YYYY format (ISO 8601). The optional positional argument $sep, which defaults to -, is a one-character separator placed between the different parts of the date.

say"2015-11-15").dd-mm-yyyy;    # OUTPUT: «15-11-2015␤» 
say;  # OUTPUT: «10-08-2016␤» 
say"/");           # OUTPUT: «14/03/2020␤» 

(Dateish) method daycount

Defined as:

method daycount(Dateish:D: --> Int:D)

Returns the number of days from the epoch Nov. 17, 1858, to the day of the invocant. The daycount returned by this method is the integral part of the Modified Julian Day (MJD) which is used routinely by astronomers, geodesists, scientists, and others. The MJD convention is designed to facilitate simplified chronological calculations. The fractional part of the MJD consists of the hours, minutes, and seconds of the using DateTime object converted to the equivalent fraction of 24 hours. Those two values added define the MJD of that instant.

say'1995-09-27').daycount;    # OUTPUT: «49987␤»

(Dateish) method IO

Defined as:

method IO(Dateish:D: --> IO::Path:D)

Returns an IO::Path object representing the stringified value of the Dateish object:;   # OUTPUT: «"2016-10-03".IO␤» OUTPUT: «"2016-10-03T11:14:47.977994-04:00".IO␤»

PORTABILITY NOTE: some operating systems (e.g. Windows) do not permit colons (:) in filenames, which would be present in IO::Path created from a DateTime object.

(Dateish) method earlier

Defined as:

multi method earlier(Dateish:D: *%unit)
multi method earlier(Dateish:D: @pairs)

Returns an object based on the current one, but with a date delta towards the past applied. Unless the given unit is second or seconds, the given value will be converted to an Int. See .later for usage. It will generally be used through classes that implement this role, Date or DateTime

my $d ='2015-02-27');
say $d.earlier(month => 5).earlier(:2days);  # OUTPUT: «2014-09-25␤» 
my $d = =>'2015-02-27'));
say $d.earlier(month => 1).earlier(:2days);  # OUTPUT: «2015-01-25T00:00:00Z␤»

If the resultant time has value 60 for seconds, yet no leap second actually exists for that time, seconds will be set to 59:

say'2008-12-31T23:59:60Z').earlier: :1day;
# OUTPUT: «2008-12-30T23:59:59Z␤»

Negative offsets are allowed, though later is more idiomatic for that.

If you need to use more than one unit, you will need to build them into a List of Pairs to use the second form of the method:

say'2021-03-31').earlier(  ( year => 3month => 2day => 8 ) ); # OUTPUT: «2018-01-23␤» 

This feature was introduced in release 2021.02 of the Rakudo compiler.

(Dateish) method later

Defined as:

multi method later(DateTime:D: *%unit)

Returns an object based on the current one (belonging to any class that mixes this role in), but with a time delta applied. The time delta can be passed as a named argument where the argument name is the unit.

Unless the given unit is second or seconds, the given value will be converted to an Int.

Allowed units are second, seconds, minute, minutes, hour, hours, day, days, week, weeks, month, months, year, years. Please note that the plural forms can only be used with the later and earlier methods.

The :2nd form of colonpairs can be used as a compact and self-documenting way of specifying the delta:

# OUTPUT: «2017-12-24T12:23:00Z␤»

Since addition of several different time units is not commutative, only one unit may be passed (and the first multi will be used).

my $d = =>'2015-02-27'));
say $d.later(month => 1).later(:2days);  # OUTPUT: «2015-03-29T00:00:00Z␤» 
say $d.later(days => 2).later(:1month);  # OUTPUT: «2015-04-01T00:00:00Z␤» 
say $d.later(days => 2).later(:month);   # same, as +True === 1

You can also (since release 2021.02 of the Rakudo compiler) pass several units at the same time, but you will have to join them in a List to activate the second form:

say =>'2015-02-27')).later( (:1month, :2days) )
# OUTPUT: «2015-03-29T00:00:00Z␤» 

If the resultant time has value 60 for seconds, yet no leap second actually exists for that time, seconds will be set to 59:

say'2008-12-31T23:59:60Z').later: :1day;
# OUTPUT: «2009-01-01T23:59:59Z␤»

Negative offsets are allowed, though earlier is more idiomatic for that.

Objects of type Date will behave in the same way:

my $d ='2015-02-27');
say $d.later(month => 1).later(:2days);  # OUTPUT: «2015-03-29␤» 
say $d.later(days => 2).later(:1month);  # OUTPUT: «2015-04-01␤» 
say $d.later(days => 2).later(:month);   # same, as +True === 1