txt: ## date.md
  class Date
  
  Calendar date
  
  ```raku
  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.
  
  ```raku
  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](#class_Date "go to top of document")[§](#Methods "direct link")
  
  ## [method new](#class_Date "go to top of document")[§](#method_new "direct link")
  
  ```raku
  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](https://en.wikipedia.org/wiki/ISO_8601)), or from an Instant or DateTime object. Optionally accepts a formatter as a named parameter.
  
  ```raku
  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:
  
  ```raku
  say Date.new(2042, 2, *); # OUTPUT: «2042-02-28␤»
  say Date.new(2044, 2, *); # OUTPUT: «2044-02-29␤»
  ```
  
  ## [method new-from-daycount](#class_Date "go to top of document")[§](#method_new-from-daycount "direct link")
  
  ```raku
  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](https://en.wikipedia.org/wiki/Julian_day). Optionally accepts a formatter as a named parameter.
  
  ```raku
  say Date.new-from-daycount(49987);          # OUTPUT: «1995-09-27␤»
  ```
  
  ## [method daycount](#class_Date "go to top of document")[§](#method_daycount "direct link")
  
  ```raku
  method daycount(Date:D: --> Int:D)
  ```
  
  Returns the number of days from epoch Nov. 17, 1858, i.e. the [Modified Julian Day](https://en.wikipedia.org/wiki/Julian_day).
  
  ## [method last-date-in-month](#class_Date "go to top of document")[§](#method_last-date-in-month "direct link")
  
  ```raku
  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.
  
  ```raku
  say Date.new('2015-11-24').last-date-in-month; # OUTPUT: «2015-11-30␤»
  ```
  
  This should allow for much easier ranges like
  
  ```raku
  $date .. $date.last-date-in-month
  
  ```
  
  for all remaining dates in the month.
  
  ## [method first-date-in-month](#class_Date "go to top of document")[§](#method_first-date-in-month "direct link")
  
  ```raku
  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.
  
  ```raku
  say Date.new('2015-11-24').first-date-in-month; # OUTPUT: «2015-11-01␤»
  ```
  
  ## [method clone](#class_Date "go to top of document")[§](#method_clone "direct link")
  
  ```raku
  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.
  
  ```raku
  say Date.new('2015-11-24').clone(month => 12);    # OUTPUT: «2015-12-24␤»
  ```
  
  ## [method today](#class_Date "go to top of document")[§](#method_today "direct link")
  
  ```raku
  method today(:&formatter --> Date:D)
  ```
  
  Returns a `Date` object for the current day. Optionally accepts a formatter named parameter.
  
  ```raku
  say Date.today;
  ```
  
  ## [method truncated-to](#class_Date "go to top of document")[§](#method_truncated-to "direct link")
  
  ```raku
  method truncated-to(Date:D: Cool $unit)
  ```
  
  Returns a `Date` truncated to the first day of its year, month or week. For example
  
  ```raku
  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](#class_Date "go to top of document")[§](#method_succ "direct link")
  
  ```raku
  method succ(Date:D: --> Date:D)
  ```
  
  Returns a `Date` of the following day. "succ" is short for "successor".
  
  ```raku
  say Date.new("2016-02-28").succ;   # OUTPUT: «2016-02-29␤»
  ```
  
  ## [method pred](#class_Date "go to top of document")[§](#method_pred "direct link")
  
  ```raku
  method pred(Date:D: --> Date:D)
  ```
  
  Returns a `Date` of the previous day. "pred" is short for "predecessor".
  
  ```raku
  say Date.new("2016-01-01").pred;   # OUTPUT: «2015-12-31␤»
  ```
  
  ## [method Str](#class_Date "go to top of document")[§](#method_Str "direct link")
  
  ```raku
  multi method Str(Date:D: --> Str:D)
  ```
  
  Returns a string representation of the invocant, as specified by [the formatter](/type/Dateish#method_formatter). If no formatter was specified, an ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) date will be returned.
  
  ```raku
  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](#class_Date "go to top of document")[§](#method_gist "direct link")
  
  ```raku
  multi method gist(Date:D: --> Str:D)
  ```
  
  Returns the date in `YYYY-MM-DD` format ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601))
  
  ```raku
  say Date.new('2015-12-24').gist;                    # OUTPUT: «2015-12-24␤»
  ```
  
  ## [method Date](#class_Date "go to top of document")[§](#method_Date "direct link")
  
  ```raku
  method Date(--> Date)
  ```
  
  Returns the invocant.
  
  ```raku
  say Date.new('2015-12-24').Date;  # OUTPUT: «2015-12-24␤»
  say Date.Date;                    # OUTPUT: «(Date)␤»
  ```
  
  ## [method DateTime](#class_Date "go to top of document")[§](#method_DateTime "direct link")
  
  ```raku
  multi method DateTime(Date:U: --> DateTime:U)
  multi method DateTime(Date:D: --> DateTime:D)
  ```
  
  Converts the invocant to [`DateTime`](/type/DateTime)
  
  ```raku
  say Date.new('2015-12-24').DateTime; # OUTPUT: «2015-12-24T00:00:00Z␤»
  say Date.DateTime;                   # OUTPUT: «(DateTime)␤»
  ```
  
  ## [method Int](#class_Date "go to top of document")[§](#method_Int "direct link")
  
  ```raku
  multi method Int(Date:D: --> Int:D)
  ```
  
  Converts the invocant to [`Int`](/type/Int). The same value can be obtained with the `daycount` method.
  
  Available as of release 2023.02 of the Rakudo compiler.
  
  ## [method Real](#class_Date "go to top of document")[§](#method_Real "direct link")
  
  ```raku
  multi method Real(Date:D: --> Int:D)
  ```
  
  Converts the invocant to [`Int`](/type/Int). The same value can be obtained with the `daycount` method.
  
  Available as of release 2023.02 of the Rakudo compiler.
  
  ## [method Numeric](#class_Date "go to top of document")[§](#method_Numeric "direct link")
  
  ```raku
  multi method Numeric(Date:D: --> Int:D)
  ```
  
  Converts the invocant to [`Int`](/type/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.
  
  # [Functions](#class_Date "go to top of document")[§](#Functions "direct link")
  
  ## [sub sleep](#class_Date "go to top of document")[§](#sub_sleep "direct link")
  
  ```raku
  sub sleep($seconds = Inf --> Nil)
  ```
  
  Attempt to sleep for the given number of `$seconds`. Returns [`Nil`](/type/Nil) on completion. Accepts [`Int`](/type/Int), [`Num`](/type/Num), [`Rat`](/type/Rat), or [`Duration`](/type/Duration) types as an argument since all of these also do [`Real`](/type/Real).
  
  ```raku
  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:
  
  ```raku
  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](#class_Date "go to top of document")[§](#sub_sleep-timer "direct link")
  
  ```raku
  sub sleep-timer(Real() $seconds = Inf --> Duration:D)
  ```
  
  This function is implemented like `sleep`, but unlike the former it does return a [`Duration`](/type/Duration) instance with the number of seconds the system did not sleep.
  
  In particular, the returned [`Duration`](/type/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`](/type/Duration) has a value of `0`, meaning no extra seconds remained to sleep. Therefore, in normal situations:
  
  ```raku
  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:
  
  ```raku
  say sleep-timer -2; # OUTPUT: 0
  say sleep-timer 0;  # OUTPUT: 0
  
  ```
  
  See also [sleep-until](/routine/sleep-until).
  
  ## [sub sleep-until](#class_Date "go to top of document")[§](#sub_sleep-until "direct link")
  
  ```raku
  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`](/type/Instant) in the future has been achieved (either by mean of sleeping or because it is right now), `False` in the case an [`Instant`](/type/Instant) in the past has been specified.
  
  To sleep until 10 seconds into the future, one could write something like this:
  
  ```raku
  say sleep-until now+10;   # OUTPUT: «True␤»
  ```
  
  Trying to sleep until a time in the past doesn't work:
  
  ```raku
  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:
  
  ```raku
  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`](/type/DateTime) at the appropriate point in time, and cast to an [`Instant`](/type/Instant).
  
  ```raku
  my $instant = DateTime.new(
      year => 2023,
      month => 9,
      day => 1,
      hour => 22,
      minute => 5);
  say sleep-until $instant.Instant; # OUTPUT: «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`](/type/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:
  
  ```raku
  # 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:<->](#class_Date "go to top of document")[§](#sub_infix:<-> "direct link")
  
  ```raku
  multi infix:<-> (Date:D, Int:D --> Date:D)
  multi infix:<-> (Date:D, Date:D --> Int:D)
  ```
  
  Takes a date to subtract from and either an [`Int`](/type/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.
  
  ```raku
  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:<+>](#class_Date "go to top of document")[§](#sub_infix:<+> "direct link")
  
  ```raku
  multi infix:<+> (Date:D, Int:D --> Date:D)
  multi infix:<+> (Int:D, Date:D --> Date:D)
  ```
  
  Takes an [`Int`](/type/Int) and adds that many days to the given `Date` object.
  
  ```raku
  say Date.new('2015-12-25') + 332; # OUTPUT: «2016-11-21␤»
  say 1 + Date.new('2015-12-25');   # OUTPUT: «2015-12-26␤»
  ```
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `Date`
  
  
  
  raku-type-graph
  
  
  
  Date
  Date
  
  
  Any
  Any
  
  
  Date->Any
  
  
  
  Dateish
  Dateish
  
  
  Date->Dateish
  
  
  
  Mu
  Mu
  
  
  Any->Mu
  
  [Expand chart above](/assets/typegraphs/Date.svg)
  