update docs for $`, $&, $' changes

mention that they're now detected individually, and mention in reapi
the new RX_BUFF_IDX_* symbolic constants.

diff --git a/pod/perlre.pod b/pod/perlre.pod
index 6a073ba..b6d6677 100644 (file)
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -896,8 +896,10 @@ use C<$&>, C<$`> or C<$'>, then patterns I<without> capturing
 parentheses will not be penalized.  So avoid C<$&>, C<$'>, and C<$`>
 if you can, but if you can't (and some algorithms really appreciate
 them), once you've used them once, use them at will, because you've
-already paid the price.  As of 5.005, C<$&> is not so costly as the
-other two.
+already paid the price.  As of 5.17.4, the presence of each of the three
+variables in a program is recorded separately, and depending on
+circumstances, perl may be able be more efficient knowing that only C<$&>
+rather than all three have been seen, for example.
 X<$&> X<$`> X<$'>
 
 As a workaround for this problem, Perl 5.10.0 introduces C<${^PREMATCH}>,

diff --git a/pod/perlreapi.pod b/pod/perlreapi.pod
index 1ccc6d8..1cef9c1 100644 (file)
--- a/pod/perlreapi.pod
+++ b/pod/perlreapi.pod
@@ -287,8 +287,19 @@ Called to get/set the value of C<$`>, C<$'>, C<$&> and their named
 equivalents, ${^PREMATCH}, ${^POSTMATCH} and $^{MATCH}, as well as the
 numbered capture groups (C<$1>, C<$2>, ...).
 
-The C<paren> parameter will be C<-2> for C<$`>, C<-1> for C<$'>, C<0>
-for C<$&>, C<1> for C<$1> and so forth.
+The C<paren> parameter will be C<1> for C<$1>, C<2> for C<$2> and so
+forth, and have these symbolic values for the special variables:
+
+    ${^PREMATCH}  RX_BUFF_IDX_CARET_PREMATCH
+    ${^POSTMATCH} RX_BUFF_IDX_CARET_POSTMATCH
+    ${^MATCH}     RX_BUFF_IDX_CARET_FULLMATCH
+    $`            RX_BUFF_IDX_PREMATCH
+    $'            RX_BUFF_IDX_POSTMATCH
+    $&            RX_BUFF_IDX_FULLMATCH
+
+Note that in perl 5.17.3 and earlier, the last three constants were also
+used for the caret variants of the variables.
+
 
 The names have been chosen by analogy with L<Tie::Scalar> methods
 names with an additional B<LENGTH> callback for efficiency. However
@@ -662,7 +673,7 @@ C<regexp_paren_pair> struct is defined as follows:
 
 If C<< ->offs[num].start >> or C<< ->offs[num].end >> is C<-1> then that
 capture group did not match. C<< ->offs[0].start/end >> represents C<$&> (or
-C<${^MATCH> under C<//p>) and C<< ->offs[paren].end >> matches C<$$paren> where
+C<${^MATCH}> under C<//p>) and C<< ->offs[paren].end >> matches C<$$paren> where
 C<$paren >= 1>.
 
 =head2 C<precomp> C<prelen>