Re: [DOC PATCH bleadperl] Document $count = () = $string =~ /\d+/g

Message-ID: <3B38B7C7.32635.1E8DC14@localhost>

p4raw-id: //depot/perl@10960

diff --git a/pod/perldata.pod b/pod/perldata.pod
index b7c3b1c..ffb47f0 100644 (file)
--- a/pod/perldata.pod
+++ b/pod/perldata.pod
@@ -565,7 +565,7 @@ interpolating an array with no elements is the same as if no
 array had been interpolated at that point.
 
 This interpolation combines with the facts that the opening
-and closing parentheses are optional (except necessary for
+and closing parentheses are optional (except when necessary for
 precedence) and lists may end with an optional comma to mean that
 multiple commas within lists are legal syntax. The list C<1,,3> is a
 concatenation of two lists, C<1,> and C<3>, the first of which ends
@@ -611,7 +611,27 @@ This is handy when you want to do a list assignment in a Boolean
 context, because most list functions return a null list when finished,
 which when assigned produces a 0, which is interpreted as FALSE.
 
-The final element may be an array or a hash:
+It's also the source of a useful idiom for executing a function or
+performing an operation in list context and then counting the number of
+return values, by assigning to an empty list and then using that
+assignment in scalar context. For example, this code:
+
+    $count = () = $string =~ /\d+/g;
+
+will place into $count the number of digit groups found in $string.
+This happens because the pattern match is in list context (since it
+is being assigned to the empty list), and will therefore return a list
+of all matching parts of the string. The list assignment in scalar
+context will translate that into the number of elements (here, the
+number of times the pattern matched) and assign that to $count. Note
+that simply using
+
+    $count = $string =~ /\d+/g;
+
+would not have worked, since a pattern match in scalar context will
+only return true or false, rather than a count of matches.
+
+The final element of a list assignment may be an array or a hash:
 
     ($a, $b, @rest) = split;
     my($a, $b, %rest) = @_;