diff --git a/doc/Language/control.rakudoc b/doc/Language/control.rakudoc index d86e89acf..62ed4ea06 100644 --- a/doc/Language/control.rakudoc +++ b/doc/Language/control.rakudoc @@ -1071,7 +1071,9 @@ Both C and C can be used as statement modifiers. E. g. my $x = 42; $x-- while $x > 12 -Also see C and C below. +See L|#next>, L|#last>, and related below for ways to +fine-tune loop control. Also see C and C for +other loop syntax. All these forms may produce a return value the same way C does. @@ -1124,59 +1126,6 @@ is evaluated at the end of the loop, even if it appears at the front. All these forms may produce a return value the same way C does. -=head1 X - -The sub C will stop execution of a subroutine or method, run all -relevant L and provide the -given return value to the caller. The default return value is L|/type/Nil>. If -a return L is -provided it will be checked unless the return value is L|/type/Nil>. If the -type check fails the exception -L|/type/X::TypeCheck::Return> is thrown. If it -passes a control exception is raised and can be caught with -L. - -Any C in a block is tied to the first L|/type/Routine> in the outer -lexical scope of that block, no matter how deeply nested. Please note -that a C in the root of a package will fail at runtime. A -C in a block that is evaluated lazily (e.g. inside C) may -find the outer lexical routine gone by the time the block is executed. -In almost any case C is the better alternative. Please check -L for -more information on how return values are handled and produced. - -=head1 X - -The sub C will return values, not containers. Those are -immutable and will lead to runtime errors when attempted to be mutated. - - sub s(){ my $a = 41; return $a }; - say ++s(); - CATCH { default { say .^name, ': ', .Str } }; - # OUTPUT: «X::Multi::NoMatch.new(dispatcher … - -To return a mutable container, use C. - - sub s(){ my $a = 41; return-rw $a }; - say ++s(); - # OUTPUT: «42␤» - -The same rules as for C regarding phasers and control exceptions apply. - -=head1 X - -Leaves the current routine and returns the provided -L|/type/Exception> or L|/type/Str> wrapped inside a -L|/type/Failure>, after all relevant -L are executed. If the caller -activated fatal exceptions via the pragma C, the exception is -thrown instead of being returned as a L|/type/Failure>. - - sub f { fail "WELP!" }; - say f; - CATCH { default { say .^name, ': ', .Str } } - # OUTPUT: «X::AdHoc: WELP!␤» - =head1 X A block or statement prefixed with C will be executed exactly once, @@ -1389,4 +1338,58 @@ for 1..5 -> $current-level { } } # OUTPUT: «Entering #1... Entering #2... Entering #3... Entering #3... Entering #4... Entering #5... Entering #5... » + +=head1 X + +The sub C will stop execution of a subroutine or method, run all +relevant L and provide the +given return value to the caller. The default return value is L|/type/Nil>. If +a return L is +provided it will be checked unless the return value is L|/type/Nil>. If the +type check fails the exception +L|/type/X::TypeCheck::Return> is thrown. If it +passes a control exception is raised and can be caught with +L. + +Any C in a block is tied to the first L|/type/Routine> in the outer +lexical scope of that block, no matter how deeply nested. Please note +that a C in the root of a package will fail at runtime. A +C in a block that is evaluated lazily (e.g. inside C) may +find the outer lexical routine gone by the time the block is executed. +In almost any case C is the better alternative. Please check +L for +more information on how return values are handled and produced. + +=head1 X + +The sub C will return values, not containers. Those are +immutable and will lead to runtime errors when attempted to be mutated. + + sub s(){ my $a = 41; return $a }; + say ++s(); + CATCH { default { say .^name, ': ', .Str } }; + # OUTPUT: «X::Multi::NoMatch.new(dispatcher … + +To return a mutable container, use C. + + sub s(){ my $a = 41; return-rw $a }; + say ++s(); + # OUTPUT: «42␤» + +The same rules as for C regarding phasers and control exceptions apply. + +=head1 X + +Leaves the current routine and returns the provided +L|/type/Exception> or L|/type/Str> wrapped inside a +L|/type/Failure>, after all relevant +L are executed. If the caller +activated fatal exceptions via the pragma C, the exception is +thrown instead of being returned as a L|/type/Failure>. + + sub f { fail "WELP!" }; + say f; + CATCH { default { say .^name, ': ', .Str } } + # OUTPUT: «X::AdHoc: WELP!␤» + =end pod