Skip to content

Commit f63b5d2

Browse files
authored
Add a little additional documentation on how to emulate pcre2_substitute's loop (#735)
We won't implement more advanced/alternative global replacement strategies, but we can at least write a few sentences explaining how to do it in application code.
1 parent d606adf commit f63b5d2

File tree

3 files changed

+306
-267
lines changed

3 files changed

+306
-267
lines changed

doc/html/pcre2api.html

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3742,7 +3742,8 @@ <h2><a name="SEC37" href="#TOC1">CREATING A NEW STRING WITH SUBSTITUTIONS</a></h
37423742
end before it starts are not supported, and give rise to an error return. For
37433743
global replacements, matches in which \K in a lookbehind causes the match to
37443744
start earlier than the point that was reached in the previous iteration are
3745-
also not supported.
3745+
also not supported. (These cases are only possible if the pattern was compiled
3746+
with the backwards-compatibility option PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK.)
37463747
</p>
37473748
<p>
37483749
The first seven arguments of <b>pcre2_substitute()</b> are the same as for
@@ -3875,6 +3876,18 @@ <h2><a name="SEC37" href="#TOC1">CREATING A NEW STRING WITH SUBSTITUTIONS</a></h
38753876
set in the match context, searching stops when that limit is reached.
38763877
</p>
38773878
<p>
3879+
Because global substitutions apply the pattern repeatedly to the subject string,
3880+
and always iterate over non-overlapping matches, the substitutions done by
3881+
<b>pcre2_substitute()</b> do not match and substitute text inside the replacement
3882+
strings themselves (no recursive/iterative substitution). However, applications
3883+
can easily implement other alternative replacement strategies, such as
3884+
iteratively replacing, then matching and replacing on the result. The
3885+
replacement loop inside <b>pcre2_substitute()</b> is simple and can be emulated
3886+
in client code by allocating a buffer, searching for matches in a loop, and
3887+
calling <b>pcre2_substitute()</b> with PCRE2_SUBSTITUTE_REPLACEMENT_ONLY an
3888+
PCRE2_SUBSTITUTE_MATCHED, and without PCRE2_SUBSTITUTE_GLOBAL.
3889+
</p>
3890+
<p>
38783891
You can restrict the effect of a global substitution to a portion of the
38793892
subject string by setting either or both of <i>startoffset</i> and an offset
38803893
limit. Here is a <b>pcre2test</b> example:

0 commit comments

Comments
 (0)