From 03720de840f4afd066d8fe1f6eb2c1da965f57ed Mon Sep 17 00:00:00 2001 From: "Philip.Hazel" Date: Sun, 5 Jan 2020 12:32:29 +0000 Subject: [PATCH] Documentation update and another cunning test pattern. --- doc/html/pcre2_substitute.html | 26 ++++++++++++++++++-------- doc/pcre2_substitute.3 | 26 +++++++++++++++++--------- testdata/testinput1 | 9 +++++++++ testdata/testoutput1 | 18 ++++++++++++++++++ 4 files changed, 62 insertions(+), 17 deletions(-) diff --git a/doc/html/pcre2_substitute.html b/doc/html/pcre2_substitute.html index 4656b20..781a39a 100644 --- a/doc/html/pcre2_substitute.html +++ b/doc/html/pcre2_substitute.html @@ -48,8 +48,8 @@ Its arguments are: outlengthptr Points to the length of the output buffer 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: 
   Set up a callout function
   Set a matching offset limit
@@ -57,9 +57,14 @@ match context is needed only if you want to:
   Change the backtracking depth limit
   Set custom memory management in the match context
-The length, startoffset and rlength values are code -units, not characters, as is the contents of the variable pointed at by -outlengthptr, which is updated to the actual length of the new string. +The length, startoffset and rlength values are code units, +not characters, as is the contents of the variable pointed at by +outlengthptr. 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. +

+

The subject and replacement lengths can be given as PCRE2_ZERO_TERMINATED for zero-terminated strings. The options are: 

@@ -74,16 +79,21 @@ zero-terminated strings. The options are:
                               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
-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.

+If PCRE2_SUBSTITUTE_MATCHED is set, match_data must be non-zero; its +contents must be the result of a call to pcre2_match() using the same +pattern and subject. +

+

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 diff --git a/doc/pcre2_substitute.3 b/doc/pcre2_substitute.3 index e53159d..9382648 100644 --- a/doc/pcre2_substitute.3 +++ b/doc/pcre2_substitute.3 @@ -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 @@ Its arguments are: \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 @@ match context is needed only if you want to: 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 @@ zero-terminated strings. The options are: 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 diff --git a/testdata/testinput1 b/testdata/testinput1 index 9d7821d..a002b78 100644 --- a/testdata/testinput1 +++ b/testdata/testinput1 @@ -6402,4 +6402,13 @@ ef) x/x,mark 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 diff --git a/testdata/testoutput1 b/testdata/testoutput1 index 79acf04..f196d56 100644 --- a/testdata/testoutput1 +++ b/testdata/testoutput1 @@ -10147,4 +10147,22 @@ No match 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