Source of: /manual/en/regexp.reference.back-references.php
<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/reference.pcre.pattern.syntax.inc";
$setup = array (
'home' =>
array (
0 => 'index.php',
1 => 'PHP Manual',
),
'head' =>
array (
0 => 'UTF-8',
1 => 'en',
),
'this' =>
array (
0 => 'regexp.reference.back-references.php',
1 => 'Back references',
),
'up' =>
array (
0 => 'reference.pcre.pattern.syntax.php',
1 => 'Pattern Syntax',
),
'prev' =>
array (
0 => 'regexp.reference.repetition.php',
1 => 'Repetition',
),
'next' =>
array (
0 => 'regexp.reference.assertions.php',
1 => 'Assertions',
),
);
$setup["toc"] = $TOC;
$setup["parents"] = $PARENTS;
manual_setup($setup);
manual_header();
?>
<div id="regexp.reference.back-references" class="section">
<h2 class="title">Back references</h2>
<p class="para">
Outside a character class, a backslash followed by a digit
greater than 0 (and possibly further digits) is a back
reference to a capturing subpattern earlier (i.e. to its
left) in the pattern, provided there have been that many
previous capturing left parentheses.
</p>
<p class="para">
However, if the decimal number following the backslash is
less than 10, it is always taken as a back reference, and
causes an error only if there are not that many capturing
left parentheses in the entire pattern. In other words, the
parentheses that are referenced need not be to the left of
the reference for numbers less than 10. See the section
entitled "Backslash" above for further details of the handling
of digits following a backslash.
</p>
<p class="para">
A back reference matches whatever actually matched the capturing
subpattern in the current subject string, rather than
anything matching the subpattern itself. So the pattern
<i>(sens|respons)e and \1ibility</i>
matches "sense and sensibility" and "response and responsibility",
but not "sense and responsibility". If case-sensitive (caseful)
matching is in force at the time of the back reference, then
the case of letters is relevant. For example,
<i>((?i)rah)\s+\1</i>
matches "rah rah" and "RAH RAH", but not "RAH rah", even
though the original capturing subpattern is matched
case-insensitively (caselessly).
</p>
<p class="para">
There may be more than one back reference to the same subpattern.
If a subpattern has not actually been used in a
particular match, then any back references to it always
fail. For example, the pattern
<i>(a|(bc))\2</i>
always fails if it starts to match "a" rather than "bc".
Because there may be up to 99 back references, all digits
following the backslash are taken as part of a potential
back reference number. If the pattern continues with a digit
character, then some delimiter must be used to terminate the
back reference. If the <a href="reference.pcre.pattern.modifiers.php" class="link">PCRE_EXTENDED</a> option
is set, this can be whitespace. Otherwise an empty comment can be used.
</p>
<p class="para">
A back reference that occurs inside the parentheses to which
it refers fails when the subpattern is first used, so, for
example, (a\1) never matches. However, such references can
be useful inside repeated subpatterns. For example, the pattern
<i>(a|b\1)+</i>
matches any number of "a"s and also "aba", "ababba" etc. At
each iteration of the subpattern, the back reference matches
the character string corresponding to the previous iteration.
In order for this to work, the pattern must be such
that the first iteration does not need to match the back
reference. This can be done using alternation, as in the
example above, or by a quantifier with a minimum of zero.
</p>
<p class="para">
Back references to the named subpatterns can be achieved by
<i>(?P=name)</i> or, since PHP 5.2.4, also by
<i>\k<name></i>, <i>\k'name'</i>,
<i>\k{name}</i> or <i>\g{name}</i>.
</p>
</div><?php manual_footer(); ?>
