move sleep routines from Date to independent-routines (#4644)

Author: arkiuat

doc/Type/Date.rakudoc

@@ -218,127 +218,6 @@ Available as of release 2023.02 of the Rakudo compiler.
 
 =head1 Functions
 
-=head2 sub sleep
-
-    sub sleep($seconds = Inf --> Nil)
-
-Attempt to sleep for the given number of C<$seconds>.  Returns L<C<Nil>|/type/Nil> on
-completion.  Accepts L<C<Int>|/type/Int>, L<C<Num>|/type/Num>, L<C<Rat>|/type/Rat>, or L<C<Duration>|/type/Duration> types as an
-argument since all of these also do L<C<Real>|/type/Real>.
-
-=for code
-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 C<sleep (5/2)> sleeps for 2.5
-seconds and C<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␤»
-
-=head2 sub sleep-timer
-
-    sub sleep-timer(Real() $seconds = Inf --> Duration:D)
-
-This function is implemented like C<sleep>, but unlike the former it does
-return a L<C<Duration>|/type/Duration> instance with the number of seconds the system did not
-sleep.
-
-In particular, the returned L<C<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 L<C<Duration>|/type/Duration>
-has a value of C<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:
-
-=begin code
-say sleep-timer -2; # OUTPUT: 0
-say sleep-timer 0;  # OUTPUT: 0
-=end code
-
-See also L<sleep-until|/routine/sleep-until>.
-
-=head2 sub sleep-until
-
-    sub sleep-until(Instant $until --> Bool)
-
-Works similar to C<sleep> but checks the current time and keeps sleeping
-until the required instant in the future has been reached.
-It uses internally the C<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 C<True> if the L<C<Instant>|/type/Instant> in the future has been achieved (either
-by mean of sleeping or because it is right now), C<False> in the case
-an L<C<Instant>|/type/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:
-
-=for code
-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 L<C<DateTime>|/type/DateTime> at the
-appropriate point in time, and cast to an L<C<Instant>|/type/Instant>.
-
-=for code
-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
-C<DateTime.new> uses UTC by default) as an L<C<Instant>|/type/Instant> and pass this to
-C<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:
-
-=for code
-# 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};
-
 =head2 sub infix:<->
 
     multi infix:<-> (Date:D, Int:D --> Date:D)

doc/Type/independent-routines.rakudoc

@@ -1187,6 +1187,127 @@ operator:
     say [42, "42"].squish(with => &infix:<eq>); # OUTPUT: «(42)␤»
     # The resulting item is Int
 
+=head2 sub sleep
+
+    sub sleep($seconds = Inf --> Nil)
+
+Attempt to sleep for the given number of C<$seconds>.  Returns L<C<Nil>|/type/Nil> on
+completion.  Accepts L<C<Int>|/type/Int>, L<C<Num>|/type/Num>, L<C<Rat>|/type/Rat>, or L<C<Duration>|/type/Duration> types as an
+argument since all of these also do L<C<Real>|/type/Real>.
+
+=for code
+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 C<sleep (5/2)> sleeps for 2.5
+seconds and C<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␤»
+
+=head2 sub sleep-timer
+
+    sub sleep-timer(Real() $seconds = Inf --> Duration:D)
+
+This function is implemented like C<sleep>, but unlike the former it does
+return a L<C<Duration>|/type/Duration> instance with the number of seconds the system did not
+sleep.
+
+In particular, the returned L<C<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 L<C<Duration>|/type/Duration>
+has a value of C<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:
+
+=begin code
+say sleep-timer -2; # OUTPUT: 0
+say sleep-timer 0;  # OUTPUT: 0
+=end code
+
+See also L<sleep-until|/routine/sleep-until>.
+
+=head2 sub sleep-until
+
+    sub sleep-until(Instant $until --> Bool)
+
+Works similar to C<sleep> but checks the current time and keeps sleeping
+until the required instant in the future has been reached.
+It uses internally the C<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 C<True> if the L<C<Instant>|/type/Instant> in the future has been achieved (either
+by mean of sleeping or because it is right now), C<False> in the case
+an L<C<Instant>|/type/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:
+
+=for code
+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 L<C<DateTime>|/type/DateTime> at the
+appropriate point in time, and cast to an L<C<Instant>|/type/Instant>.
+
+=for code
+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
+C<DateTime.new> uses UTC by default) as an L<C<Instant>|/type/Instant> and pass this to
+C<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:
+
+=for code
+# 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};
+
 =head2 sub emit
 
     sub emit(\value --> Nil)