Revision: 1203
http://www.exim.org/viewvc/pcre2?view=rev&revision=1203
Author: ph10
Date: 2020-01-05 12:32:29 +0000 (Sun, 05 Jan 2020)
Log Message:
-----------
Documentation update and another cunning test pattern.
Modified Paths:
--------------
code/trunk/doc/html/pcre2_substitute.html
code/trunk/doc/pcre2_substitute.3
code/trunk/testdata/testinput1
code/trunk/testdata/testoutput1
Modified: code/trunk/doc/html/pcre2_substitute.html
===================================================================
--- code/trunk/doc/html/pcre2_substitute.html 2020-01-01 12:07:02 UTC (rev 1202)
+++ code/trunk/doc/html/pcre2_substitute.html 2020-01-05 12:32:29 UTC (rev 1203)
@@ -48,8 +48,8 @@
<i>outlengthptr</i> Points to the length of the output buffer
</pre>
A match data block is needed only if you want to inspect the data from the
-match that is returned in that block or if PCRE2_SUBSTITUTE_MATCHED is set. A
-match context is needed only if you want to:
+final match that is returned in that block or if PCRE2_SUBSTITUTE_MATCHED is
+set. A match context is needed only if you want to:
<pre>
Set up a callout function
Set a matching offset limit
@@ -57,9 +57,14 @@
Change the backtracking depth limit
Set custom memory management in the match context
</pre>
-The <i>length</i>, <i>startoffset</i> and <i>rlength</i> values are code
-units, not characters, as is the contents of the variable pointed at by
-<i>outlengthptr</i>, which is updated to the actual length of the new string.
+The <i>length</i>, <i>startoffset</i> and <i>rlength</i> values are code units,
+not characters, as is the contents of the variable pointed at by
+<i>outlengthptr</i>. This variable must contain the length of the output buffer
+when the function is called. If the function is successful, the value is
+changed to the length of the new string, excluding the trailing zero that is
+automatically added.
+</P>
+<P>
The subject and replacement lengths can be given as PCRE2_ZERO_TERMINATED for
zero-terminated strings. The options are:
<pre>
@@ -74,16 +79,21 @@
PCRE2_UTF was set at compile time)
PCRE2_SUBSTITUTE_EXTENDED Do extended replacement processing
PCRE2_SUBSTITUTE_GLOBAL Replace all occurrences in the subject
- PCRE2_SUBSTITUTE_LITERAL The replacement string is literal
- PCRE2_SUBSTITUTE_MATCHED Use pre-existing match data for 1st match
+ PCRE2_SUBSTITUTE_LITERAL The replacement string is literal
+ PCRE2_SUBSTITUTE_MATCHED Use pre-existing match data for 1st match
PCRE2_SUBSTITUTE_OVERFLOW_LENGTH If overflow, compute needed length
PCRE2_SUBSTITUTE_UNKNOWN_UNSET Treat unknown group as unset
PCRE2_SUBSTITUTE_UNSET_EMPTY Simple unset insert = empty string
</pre>
-If PCRE2_SUBSTITUTE_LITERAL is set, PCRE2_SUBSTITUTE_EXTENDED,
+If PCRE2_SUBSTITUTE_LITERAL is set, PCRE2_SUBSTITUTE_EXTENDED,
PCRE2_SUBSTITUTE_UNKNOWN_UNSET, and PCRE2_SUBSTITUTE_UNSET_EMPTY are ignored.
</P>
<P>
+If PCRE2_SUBSTITUTE_MATCHED is set, <i>match_data</i> must be non-zero; its
+contents must be the result of a call to <b>pcre2_match()</b> using the same
+pattern and subject.
+</P>
+<P>
The function returns the number of substitutions, which may be zero if there
are no matches. The result may be greater than one only when
PCRE2_SUBSTITUTE_GLOBAL is set. In the event of an error, a negative error code
Modified: code/trunk/doc/pcre2_substitute.3
===================================================================
--- code/trunk/doc/pcre2_substitute.3 2020-01-01 12:07:02 UTC (rev 1202)
+++ code/trunk/doc/pcre2_substitute.3 2020-01-05 12:32:29 UTC (rev 1203)
@@ -1,4 +1,4 @@
-.TH PCRE2_SUBSTITUTE 3 "27 December 2019" "PCRE2 10.35"
+.TH PCRE2_SUBSTITUTE 3 "05 January 2020" "PCRE2 10.35"
.SH NAME
PCRE2 - Perl-compatible regular expressions (revised API)
.SH SYNOPSIS
@@ -36,8 +36,8 @@
\fIoutlengthptr\fP Points to the length of the output buffer
.sp
A match data block is needed only if you want to inspect the data from the
-match that is returned in that block or if PCRE2_SUBSTITUTE_MATCHED is set. A
-match context is needed only if you want to:
+final match that is returned in that block or if PCRE2_SUBSTITUTE_MATCHED is
+set. A match context is needed only if you want to:
.sp
Set up a callout function
Set a matching offset limit
@@ -45,9 +45,13 @@
Change the backtracking depth limit
Set custom memory management in the match context
.sp
-The \fIlength\fP, \fIstartoffset\fP and \fIrlength\fP values are code
-units, not characters, as is the contents of the variable pointed at by
-\fIoutlengthptr\fP, which is updated to the actual length of the new string.
+The \fIlength\fP, \fIstartoffset\fP and \fIrlength\fP values are code units,
+not characters, as is the contents of the variable pointed at by
+\fIoutlengthptr\fP. This variable must contain the length of the output buffer
+when the function is called. If the function is successful, the value is
+changed to the length of the new string, excluding the trailing zero that is
+automatically added.
+.P
The subject and replacement lengths can be given as PCRE2_ZERO_TERMINATED for
zero-terminated strings. The options are:
.sp
@@ -66,15 +70,19 @@
PCRE2_UTF was set at compile time)
PCRE2_SUBSTITUTE_EXTENDED Do extended replacement processing
PCRE2_SUBSTITUTE_GLOBAL Replace all occurrences in the subject
- PCRE2_SUBSTITUTE_LITERAL The replacement string is literal
- PCRE2_SUBSTITUTE_MATCHED Use pre-existing match data for 1st match
+ PCRE2_SUBSTITUTE_LITERAL The replacement string is literal
+ PCRE2_SUBSTITUTE_MATCHED Use pre-existing match data for 1st match
PCRE2_SUBSTITUTE_OVERFLOW_LENGTH If overflow, compute needed length
PCRE2_SUBSTITUTE_UNKNOWN_UNSET Treat unknown group as unset
PCRE2_SUBSTITUTE_UNSET_EMPTY Simple unset insert = empty string
.sp
-If PCRE2_SUBSTITUTE_LITERAL is set, PCRE2_SUBSTITUTE_EXTENDED,
+If PCRE2_SUBSTITUTE_LITERAL is set, PCRE2_SUBSTITUTE_EXTENDED,
PCRE2_SUBSTITUTE_UNKNOWN_UNSET, and PCRE2_SUBSTITUTE_UNSET_EMPTY are ignored.
.P
+If PCRE2_SUBSTITUTE_MATCHED is set, \fImatch_data\fP must be non-zero; its
+contents must be the result of a call to \fBpcre2_match()\fP using the same
+pattern and subject.
+.P
The function returns the number of substitutions, which may be zero if there
are no matches. The result may be greater than one only when
PCRE2_SUBSTITUTE_GLOBAL is set. In the event of an error, a negative error code
Modified: code/trunk/testdata/testinput1
===================================================================
--- code/trunk/testdata/testinput1 2020-01-01 12:07:02 UTC (rev 1202)
+++ code/trunk/testdata/testinput1 2020-01-05 12:32:29 UTC (rev 1203)
@@ -6402,4 +6402,13 @@
Hackdaws love my big sphinx of quartz.
Pack my fox with five dozen liquor jugs.
+/^(?>.*?([A-Z])(?!.*\1)){26}/i
+ The quick brown fox jumps over the lazy dog.
+ Jackdaws love my big sphinx of quartz.
+ Pack my box with five dozen liquor jugs.
+\= Expect no match
+ The quick brown fox jumps over the lazy cat.
+ Hackdaws love my big sphinx of quartz.
+ Pack my fox with five dozen liquor jugs.
+
# End of testinput1
Modified: code/trunk/testdata/testoutput1
===================================================================
--- code/trunk/testdata/testoutput1 2020-01-01 12:07:02 UTC (rev 1202)
+++ code/trunk/testdata/testoutput1 2020-01-05 12:32:29 UTC (rev 1203)
@@ -10147,4 +10147,22 @@
Pack my fox with five dozen liquor jugs.
No match
+/^(?>.*?([A-Z])(?!.*\1)){26}/i
+ The quick brown fox jumps over the lazy dog.
+ 0: The quick brown fox jumps over the lazy dog
+ 1: g
+ Jackdaws love my big sphinx of quartz.
+ 0: Jackdaws love my big sphinx of quartz
+ 1: z
+ Pack my box with five dozen liquor jugs.
+ 0: Pack my box with five dozen liquor jugs
+ 1: s
+\= Expect no match
+ The quick brown fox jumps over the lazy cat.
+No match
+ Hackdaws love my big sphinx of quartz.
+No match
+ Pack my fox with five dozen liquor jugs.
+No match
+
# End of testinput1
