perldelta: clarify what these new capture variables are for

[Ævar: I originally had a worse patch for this, but Yves had a better
one to fixup into mine. See "Re: Perl 5.26.0-RC1 is now available!"[1]
on list for context.].

1. <CANgJU+Uh0Kg_fS=3Ux5WvZtskOcOQT2Gjvy8tgYHjCTd0-d90Q@mail.gmail.com>

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index bcd625f..ef8a193 100644 (file)
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -75,11 +75,19 @@ C<.> to @INC in all child processes.
 =head2 @{^CAPTURE}, %{^CAPTURE}, and %{^CAPTURE_ALL}
 
 C<@{^CAPTURE}> exposes the capture buffers of the last match as an
-array. So C<$1> is C<${^CAPTURE}[0]>.
+array. So C<$1> is C<${^CAPTURE}[0]>. This is a more efficient equivalent
+to code like C<substr($matched_string,$-[0],$+[0]-$-[0])>, and you don't
+have to keep track of the C<$matched_string> either. This variable has no
+single character equivalent. Note like the other regex magic variables
+the contents of this variable is dynamic, if you wish to store it beyond
+the lifetime of the match you must copy it to another array.
 
-C<%{^CAPTURE}> is the equivalent to C<%+> (ie named captures)
+C<%{^CAPTURE}> is the equivalent to C<%+> (ie named captures). Other than
+being more self documenting there is no difference between the two forms.
 
 C<%{^CAPTURE_ALL}> is the equivalent to C<%-> (ie all named captures).
+Other than being more self documenting there is no difference between the
+two forms.
 
 =head2 Unicode 9.0 is now supported
 

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 2f77648..0bd7471 100644 (file)
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -925,8 +925,8 @@ Mnemonic: like \digits.
 =item @{^CAPTURE}
 X<@{^CAPTURE}> X<@^CAPTURE>
 
-An array which contains the capture buffers, if any, of the last
-successful pattern match, not counting patterns matched
+An array which exposes the contents of the capture buffers, if any, of
+the last successful pattern match, not counting patterns matched
 in nested blocks that have been exited already.
 
 Note that the 0 index of @{^CAPTURE} is equivalent to $1, the 1 index
@@ -940,6 +940,9 @@ should output "f-o-a-l".
 
 See also L</$I<digits>>, L</%{^CAPTURE}> and L</%{^CAPTURE_ALL}>.
 
+Note that unlike most other regex magic variables there is no single
+letter equivalent to C<@{^CAPTURE}>.
+
 This variable was added in 5.25.7
 
 =item $MATCH