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

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

1 files changed, 14 insertions, 3 deletions

diff --git a/pod/perlreapi.pod b/pod/perlreapi.pod
index 1ccc6d869f..1cef9c1c8c 100644
--- 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>