class Date { }

A Date is an immutable object identifying a day in the Gregorian calendar.

Date objects support addition and subtraction of integers, where an integer is interpreted as the number of days. You can compare Date objects with the numeric comparison operators ==, <, <=, >, >=, != . Their stringification in YYYY-MM-DD format means that comparing them with the string operators eq, lt, le etc. also gives the right result.

Date.today creates an object the current day according to the system clock.

my $d = Date.new(2015, 12, 24); # Christmas Eve! 
say $d;                         # OUTPUT: «2015-12-24␤» 
say $d.year;                    # OUTPUT: «2015␤» 
say $d.month;                   # OUTPUT: «12␤» 
say $d.day;                     # OUTPUT: «24␤» 
say $d.day-of-week;             # OUTPUT: «4␤» (Thursday) 
say $d.later(days => 20);       # OUTPUT: «2016-01-13␤» 
my $n = Date.new('2015-12-31'); # New Year's Eve 
say $n - $d;                    # OUTPUT: «7␤», 7 days between New Years/Christmas Eve 
say $n + 1;                     # OUTPUT: «2016-01-01␤»

Note since version 6.d, .raku can be called on Date. It will also reject synthetic numerics such as 7̈ .

Methods

method new

Defined as:

multi method new($year, $month, $day, :&formatter --> Date:D)
multi method new(:$year!, :$month = 1, :$day = 1  --> Date:D)
multi method new(Str $date                        --> Date:D)
multi method new(Instant:D $dt                    --> Date:D)
multi method new(DateTime:D $dt                   --> Date:D)

Creates a new Date object, either from a triple of (year, month, day) that can be coerced to integers, or from a string of the form YYYY-MM-DD (ISO 8601), or from an Instant or DateTime object. Optionally accepts a formatter as a named parameter.

my $date = Date.new(2042, 1, 1);
$date = Date.new(year => 2042, month => 1, day => 1);
$date = Date.new("2042-01-01");
$date = Date.new(Instant.from-posix: 1482155532);
$date = Date.new(DateTime.now);

Since Rakudo 2022.03, the "day" argument can also be a callable, with * representing the last day in a month, and the possibility of getting to the day counting from the last one:

say Date.new(2042, 2, *); # OUTPUT: «2042-02-28␤» 
say Date.new(2044, 2, *); # OUTPUT: «2044-02-29␤»

method new-from-daycount

Defined as:

method new-from-daycount($daycount,:&formatter --> Date:D)

Creates a new Date object given $daycount which is the number of days from epoch Nov. 17, 1858, i.e. the Modified Julian Day. Optionally accepts a formatter as a named parameter.

say Date.new-from-daycount(49987);          # OUTPUT: «1995-09-27␤»

method last-date-in-month

Defined as:

method last-date-in-month(Date:D: --> Date:D)

Returns the last date in the month of the Date object. Otherwise, returns the invocant if the day value is already the last day of the month.

say Date.new('2015-11-24').last-date-in-month; # OUTPUT: «2015-11-30␤»

This should allow for much easier ranges like

$date .. $date.last-date-in-month

for all remaining dates in the month.

method first-date-in-month

Defined as:

method first-date-in-month(Date:D: --> Date:D)

Returns the first date in the month of the Date object. Otherwise, returns the invocant if the day value is already the first day of the month.

say Date.new('2015-11-24').first-date-in-month; # OUTPUT: «2015-11-01␤»

method clone

Defined as:

method clone(Date:D: :$year, :$month, :$day, :&formatter)

Creates a new Date object based on the invocant, but with the given arguments overriding the values from the invocant.

say Date.new('2015-11-24').clone(month => 12);    # OUTPUT: «2015-12-24␤»

method today

Defined as:

method today(:&formatter --> Date:D)

Returns a Date object for the current day. Optionally accepts a formatter named parameter.

say Date.today;

method truncated-to

Defined as:

method truncated-to(Date:D: Cool $unit)

Returns a Date truncated to the first day of its year, month or week. For example

my $c = Date.new('2012-12-24');
say $c.truncated-to('year');     # OUTPUT: «2012-01-01␤» 
say $c.truncated-to('month');    # OUTPUT: «2012-12-01␤» 
say $c.truncated-to('week');     # OUTPUT: «2012-12-24␤», because it's Monday already

method succ

Defined as:

method succ(Date:D: --> Date:D)

Returns a Date of the following day. "succ" is short for "successor".

say Date.new("2016-02-28").succ;   # OUTPUT: «2016-02-29␤»

method pred

Defined as:

method pred(Date:D: --> Date:D)

Returns a Date of the previous day. "pred" is short for "predecessor".

say Date.new("2016-01-01").pred;   # OUTPUT: «2015-12-31␤»

method Str

Defined as:

multi method Str(Date:D: --> Str:D)

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

say Date.new('2015-12-24').Str;                     # OUTPUT: «2015-12-24␤» 
 
my $fmt = { sprintf "%02d/%02d/%04d", .month, .day, .year };
say Date.new('2015-12-24', formatter => $fmt).Str;  # OUTPUT: «12/24/2015␤»

method gist

Defined as:

multi method gist(Date:D: --> Str:D)

Returns the date in YYYY-MM-DD format (ISO 8601)

say Date.new('2015-12-24').gist;                    # OUTPUT: «2015-12-24␤»

method Date

Defined as:

method Date(--> Date)

Returns the invocant.

say Date.new('2015-12-24').Date;  # OUTPUT: «2015-12-24␤» 
say Date.Date;                    # OUTPUT: «(Date)␤»

method DateTime

Defined as:

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

Converts the invocant to DateTime

say Date.new('2015-12-24').DateTime; # OUTPUT: «2015-12-24T00:00:00Z␤» 
say Date.DateTime;                   # OUTPUT: «(DateTime)␤»

Functions

sub sleep

sub sleep($seconds = Inf --> Nil)

Attempt to sleep for the given number of $seconds. Returns Nil on completion. Accepts Int, Num, Rat, or Duration types as an argument since all of these also do Real.

sleep 5;                # Int 
sleep 5.2;              # Num 
sleep (5/2);            # Rat 
sleep (now - now + 5);  # Duration 

It is thus possible to sleep for a non-integer amount of time. For instance, the following code shows that sleep (5/2) sleeps for 2.5 seconds and sleep 5.2 sleeps for 5.2 seconds:

my $before = now;
sleep (5/2);
my $after = now;
say $after-$before;  # OUTPUT: «2.502411561␤» 
 
$before = now;
sleep 5.2;
$after = now;
say $after-$before;  # OUTPUT: «5.20156987␤»

sub sleep-timer

sub sleep-timer(Real() $seconds = Inf --> Duration:D)

This function is implemented like sleep, but unlike the former it does return a Duration instance with the number of seconds the system did not sleep.

In particular, the returned Duration will handle the number of seconds remaining when the process has been awakened by some external event (e.g., Virtual Machine or Operating System events). Under normal condition, when sleep is not interrupted, the returned Duration has a value of 0, meaning no extra seconds remained to sleep. Therefore, in normal situations:

say sleep-timer 3.14;  # OUTPUT: «0␤»

The same result applies to edge cases, when a negative or zero time to sleep is passed as argument:

say sleep-timer -2; # OUTPUT: 0 
say sleep-timer 0;  # OUTPUT: 0 

See also sleep-until.

sub sleep-until

sub sleep-until(Instant $until --> Bool)

Works similar to sleep but checks the current time and keeps sleeping until the required instant in the future has been reached. It uses internally the sleep-timer method in a loop to ensure that, if accidentally woken up early, it will wait again for the specified amount of time remaining to reach the specified instant. goes back to sleep

Returns True if the Instant in the future has been achieved (either by mean of sleeping or because it is right now), False in the case an Instant in the past has been specified.

To sleep until 10 seconds into the future, one could write something like this:

say sleep-until now+10;   # OUTPUT: «True␤»

Trying to sleep until a time in the past doesn't work:

my $instant = now - 5;
say sleep-until $instant; # OUTPUT: «False␤»

However if we put the instant sufficiently far in the future, the sleep should run:

my $instant = now + 30;
# assuming the two commands are run within 30 seconds of one another... 
say sleep-until $instant; # OUTPUT: «True␤» 

To specify an exact instant in the future, first create a DateTime at the appropriate point in time, and cast to an Instant.

my $instant = DateTime.new(
    year => 2020,
    month => 9,
    day => 1,
    hour => 22,
    minute => 5);
say sleep-until $instant.Instant; # True (eventually...) 

This could be used as a primitive kind of alarm clock. For instance, say you need to get up at 7am on the 4th of September 2015, but for some reason your usual alarm clock is broken and you only have your laptop. You can specify the time to get up (being careful about time zones, since DateTime.new uses UTC by default) as an Instant and pass this to sleep-until, after which you can play an mp3 file to wake you up instead of your normal alarm clock. This scenario looks roughly like this:

# DateTime.new uses UTC by default, so get time zone from current time 
my $timezone = DateTime.now.timezone;
my $instant = DateTime.new(
    year => 2015,
    month => 9,
    day => 4,
    hour => 7,
    minute => 0,
    timezone => $timezone
).Instant;
sleep-until $instant;
qqx{mplayer wake-me-up.mp3};

sub infix:<->

multi sub infix:<-> (Date:D, Int:D --> Date:D)
multi sub infix:<-> (Date:D, Date:D --> Int:D)

Takes a date to subtract from and either an Int, representing the number of days to subtract, or another Date object. Returns a new Date object or the number of days between the two dates, respectively.

say Date.new('2016-12-25') - Date.new('2016-12-24'); # OUTPUT: «1␤» 
say Date.new('2015-12-25') - Date.new('2016-11-21'); # OUTPUT: «-332␤» 
say Date.new('2016-11-21') - 332;                    # OUTPUT: «2015-12-25␤»

sub infix:<+>

multi sub infix:<+> (Date:D, Int:D --> Date:D)
multi sub infix:<+> (Int:D, Date:D --> Date:D)

Takes an Int and adds that many days to the given Date object.

say Date.new('2015-12-25') + 332; # OUTPUT: «2016-11-21␤» 
say 1 + Date.new('2015-12-25');   # OUTPUT: «2015-12-26␤»

Type Graph

Expand above chart

Routines supplied by role Dateish

Date 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 Date.new('2015-12-31').year;                                  # OUTPUT: «2015␤» 
say DateTime.new(date => Date.new('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 Date.new('2015-12-31').month;                                  # OUTPUT: «12␤» 
say DateTime.new(date => Date.new('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 Date.new('2015-12-31').day;                                  # OUTPUT: «31␤» 
say DateTime.new(date => Date.new('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 = Date.new('2015-12-31');  # (no formatter specified) 
say $dt.formatter.^name;          # OUTPUT: «Callable␤» 
my $us-format = sub ($self) { sprintf "%02d/%02d/%04d", .month, .day, .year given $self; };
$dt = Date.new('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 DateTime.new(:year<2016>).is-leap-year; # OUTPUT: «True␤» 
say Date.new("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 Date.new('2015-12-31').day-of-month;                                  # OUTPUT: «31␤» 
say DateTime.new(date => Date.new('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 Date.new('2015-12-31').day-of-week;                                  # OUTPUT: «4␤» 
say DateTime.new(date => Date.new('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 Date.new('2015-12-31').day-of-year;                                  # OUTPUT: «365␤» 
say DateTime.new(date => Date.new('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 Date.new("2016-01-02").days-in-month;                # OUTPUT: «31␤» 
say DateTime.new(:year<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) = Date.new("2014-12-31").week;
say $year;                       # OUTPUT: «2015␤» 
say $week;                       # OUTPUT: «1␤» 
say Date.new('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 Date.new("2014-12-31").week-number;   # 1  (first week of 2015) 
say Date.new("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 Date.new("2015-11-15").week-year;   # 2015 
say Date.new("2014-12-31").week-year;   # 2015 (date belongs to the first week of 2015) 
say Date.new("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 Date.new("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 Date.new("2015-11-15").yyyy-mm-dd;   # OUTPUT: «2015-11-15␤» 
say DateTime.new(1470853583).yyyy-mm-dd; # OUTPUT: «2016-08-10␤» 
say Date.today.yyyy-mm-dd("/");          # 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 Date.new("2015-11-15").mm-dd-yyyy;   # OUTPUT: «11-15-2015␤» 
say DateTime.new(1470853583).mm-dd-yyyy; # OUTPUT: «08-10-2016␤» 
say Date.today.mm-dd-yyyy("/");          # 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 Date.new("2015-11-15").dd-mm-yyyy;    # OUTPUT: «15-11-2015␤» 
say DateTime.new(1470853583).dd-mm-yyyy;  # OUTPUT: «10-08-2016␤» 
say Date.today.dd-mm-yyyy("/");           # 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 Date.new('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:

Date.today.IO.say;   # OUTPUT: «"2016-10-03".IO␤» 
DateTime.now.IO.say; # 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 = Date.new('2015-02-27');
say $d.earlier(month => 5).earlier(:2days);  # OUTPUT: «2014-09-25␤» 
my $d = DateTime.new(date => Date.new('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 DateTime.new('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 Date.new('2021-03-31').earlier(  ( year => 3, month => 2, day => 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:

say DateTime.new('2015-12-24T12:23:00Z').later(:2years);
# 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 = DateTime.new(date => Date.new('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 DateTime.new(date => Date.new('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 DateTime.new('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 = Date.new('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