Date Reference

Calendar date

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($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)

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

method new-from-daycount #

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

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

method daycount #

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

Returns Int:D.

Returns the number of days from epoch Nov. 17, 1858, i.e. the Modified Julian Day.

method last-date-in-month #

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

Returns 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. This should allow for much easier ranges like for all remaining dates in the month.

method first-date-in-month #

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

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

method clone #

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.

method today #

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

Returns Date:D.

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

method truncated-to #

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

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

method succ #

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

Returns Date:D.

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

method pred #

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

Returns Date:D.

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

method Str #

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

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

method gist #

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

Returns Str:D.

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

method Date #

method Date(--> Date)

Returns Date.

Returns the invocant.

method DateTime #

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

Returns DateTime:U or DateTime:D.

Converts the invocant to DateTime

method Int #

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

Returns Int:D.

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

method Real #

multi method Real(Date:D: --> Int:D)

Returns Int:D.

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

method Numeric #

multi method Numeric(Date:D: --> Int:D)

Returns Int:D.

Converts the invocant to Int. The same value can be obtained with the daycount method. This allows Date objects to be used directly in arithmetic operations. Available as of release 2023.02 of the Rakudo compiler.

sub infix:<-> #

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

Returns Date:D or 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.

sub infix:<+> #

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

Returns Date:D.

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

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.

4 no-output · 16 ok

class Date { }

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␤»

2015-12-24
2015
12
24
4
2016-01-13
7
2016-01-01

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);

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

2042-02-28
2044-02-29

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

1995-09-27

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

2015-11-30

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

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

2015-11-01

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

2015-12-24

say Date.today;

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

2012-01-01
2012-12-01
2012-12-24

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

2016-02-29

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

2015-12-31

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

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␤»

12/24/2015

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

2015-12-24

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

2015-12-24
(Date)

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

2015-12-24T00:00:00Z
(DateTime)

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␤»

1
-332
2015-12-25

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

2016-11-21
2015-12-26