diff --git a/ext/Pod-Functions/t/Functions.t b/ext/Pod-Functions/t/Functions.t index ee3c3d3eaf2c7..d6b774dac9c8a 100644 --- a/ext/Pod-Functions/t/Functions.t +++ b/ext/Pod-Functions/t/Functions.t @@ -91,7 +91,8 @@ Functions for real @ARRAYs: each, keys, pop, push, shift, splice, unshift, values Functions for list data: - grep, join, map, qw/STRING/, reverse, sort, unpack + all, any, grep, join, map, qw/STRING/, reverse, sort, + unpack Functions for real %HASHes: delete, each, exists, keys, values diff --git a/lib/feature.pm b/lib/feature.pm index 3a43a87e5e108..d6afdd09f2f95 100644 --- a/lib/feature.pm +++ b/lib/feature.pm @@ -523,11 +523,32 @@ always enabled. =head2 The 'any' feature -TODO write some docs +B: This feature is still experimental and the implementation may +change or be removed in future versions of Perl. For this reason, Perl will +warn when you use the feature, unless you have explicitly disabled the warning: + + no warnings "experimental::any"; + +This feature enables the L|perlfunc/any BLOCK LIST> operator keyword. +This allow testing whether any of the values in a list satisfy a given +condition, with short-circuiting behaviour as soon as it finds one. =head2 The 'all' feature -TODO write some docs +B: This feature is still experimental and the implementation may +change or be removed in future versions of Perl. For this reason, Perl will +warn when you use the feature, unless you have explicitly disabled the warning: + + no warnings "experimental::all"; + +This feature enables the L|perlfunc/all BLOCK LIST> operator keyword. +This allow testing whether all of the values in a list satisfy a given +condition, with short-circuiting behaviour as soon as it finds one that does +not. + +B remember that this enables one specific feature whose name is C; +it does not enable all of the features. This is not C. +For that, see the section below. =head1 FEATURE BUNDLES diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 6a2e5807fec3f..bee3560c5884a 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -173,6 +173,7 @@ X =for Pod::Functions =LIST +L|/all BLOCK LIST>, L|/any BLOCK LIST>, L|/grep BLOCK LIST>, L|/join EXPR,LIST>, L|/map BLOCK LIST>, LE>|/qwESTRINGE>, L|/reverse LIST>, L|/sort SUBNAME LIST>, @@ -805,6 +806,67 @@ For more information see L. Portability issues: L. +=item all BLOCK LIST + +=for Pod::Functions test if every value in a list satisfies the given condition + +Evaluates the BLOCK for each element of the LIST (locally setting +L|perlvar/$_> to each element) and checks the truth of the result of +that block. Returns true if every element makes the block yield true, or +returns false if at least one element makes the block false. + +As soon as any element makes the block yield false, then the result of this +operator is determined. It will short-circuit in that case and not consider +any further elements. + +When used as a condition, this is similar to using L|/grep BLOCK LIST> +to count that every value satisfies the condition, except for this +short-circuit behaviour. + + if( all { length $_ } @strings ) { + say "Every string is non-empty"; + } + +is roughly equivalent to + + if( @strings == grep { length $_ } @strings ) ... + +This operator is only available if the +L feature|feature/"The 'all' feature"> is enabled. + +It is currently considered B, and will issue a compile-time +warning in the category C unless that category is silenced. + +=item any BLOCK LIST + +=for Pod::Functions test if at least one value in a list satisfies the given condition + +Evaluates the BLOCK for each element of the LIST (locally setting +L|perlvar/$_> to each element) and checks the truth of the result of +that block. Returns true if at least one element makes the block yield +true, or returns false if no element is found to make it true. + +As soon as any element makes the block yield true, then the result of this +operator is determined. It will short-circuit in that case and not consider +any further elements. + +When used as a condition, this is similar to L|/grep BLOCK LIST>, +except for this short-circuit behaviour. + + if( any { length $_ } @strings ) { + say "At least one string is non-empty"; + } + +is roughly equivalent to + + if( grep { length $_ } @strings ) ... + +This operator is only available if the +L feature|feature/"The 'any' feature"> is enabled. + +It is currently considered B, and will issue a compile-time +warning in the category C unless that category is silenced. + =item atan2 Y,X X X X X diff --git a/regen/feature.pl b/regen/feature.pl index 6449c092ac8ca..cd1ad98fcc365 100755 --- a/regen/feature.pl +++ b/regen/feature.pl @@ -985,11 +985,32 @@ =head2 The 'apostrophe_as_package_separator' feature =head2 The 'any' feature -TODO write some docs +B: This feature is still experimental and the implementation may +change or be removed in future versions of Perl. For this reason, Perl will +warn when you use the feature, unless you have explicitly disabled the warning: + + no warnings "experimental::any"; + +This feature enables the L|perlfunc/any BLOCK LIST> operator keyword. +This allow testing whether any of the values in a list satisfy a given +condition, with short-circuiting behaviour as soon as it finds one. =head2 The 'all' feature -TODO write some docs +B: This feature is still experimental and the implementation may +change or be removed in future versions of Perl. For this reason, Perl will +warn when you use the feature, unless you have explicitly disabled the warning: + + no warnings "experimental::all"; + +This feature enables the L|perlfunc/all BLOCK LIST> operator keyword. +This allow testing whether all of the values in a list satisfy a given +condition, with short-circuiting behaviour as soon as it finds one that does +not. + +B remember that this enables one specific feature whose name is C; +it does not enable all of the features. This is not C. +For that, see the section below. =head1 FEATURE BUNDLES