Documentation update
This commit is contained in:
Philip.Hazel
parent
25cec7a966
commit
935183d2d5
|
|
@ -43,26 +43,25 @@ offsets to captured substrings. Its arguments are:
|
|||
A match context is needed only if you want to:
|
||||
<pre>
|
||||
Set up a callout function
|
||||
Change the limit for calling the internal function <i>match()</i>
|
||||
Change the limit for calling <i>match()</i> recursively
|
||||
Set custom memory management when the heap is used for recursion
|
||||
Set a matching offset limit
|
||||
Change the backtracking match limit
|
||||
Change the backtracking depth limit
|
||||
Set custom memory management in the match context
|
||||
</pre>
|
||||
The <i>length</i> and <i>startoffset</i> values are code
|
||||
units, not characters. The options are:
|
||||
units, not characters. The length may be given as PCRE2_ZERO_TERMINATE for a
|
||||
subject that is terminated by a binary zero code unit. The options are:
|
||||
<pre>
|
||||
PCRE2_ANCHORED Match only at the first position
|
||||
PCRE2_NOTBOL Subject string is not the beginning of a line
|
||||
PCRE2_NOTEOL Subject string is not the end of a line
|
||||
PCRE2_NOTEMPTY An empty string is not a valid match
|
||||
PCRE2_NOTEMPTY_ATSTART An empty string at the start of the subject
|
||||
is not a valid match
|
||||
PCRE2_NO_UTF_CHECK Do not check the subject for UTF
|
||||
validity (only relevant if PCRE2_UTF
|
||||
PCRE2_NOTEMPTY_ATSTART An empty string at the start of the subject is not a valid match
|
||||
PCRE2_NO_JIT Do not use JIT matching
|
||||
PCRE2_NO_UTF_CHECK Do not check the subject for UTF validity (only relevant if PCRE2_UTF
|
||||
was set at compile time)
|
||||
PCRE2_PARTIAL_SOFT Return PCRE2_ERROR_PARTIAL for a partial
|
||||
match if no full matches are found
|
||||
PCRE2_PARTIAL_HARD Return PCRE2_ERROR_PARTIAL for a partial match
|
||||
if that is found before a full match
|
||||
PCRE2_PARTIAL_HARD Return PCRE2_ERROR_PARTIAL for a partial match even if there is a full match
|
||||
PCRE2_PARTIAL_SOFT Return PCRE2_ERROR_PARTIAL for a partial match if no full matches are found
|
||||
</pre>
|
||||
For details of partial matching, see the
|
||||
<a href="pcre2partial.html"><b>pcre2partial</b></a>
|
||||
|
|
|
|||
|
|
@ -1082,14 +1082,14 @@ pattern.
|
|||
copy=<number or name> copy captured substring
|
||||
depth_limit=<n> set a depth limit
|
||||
dfa use <b>pcre2_dfa_match()</b>
|
||||
find_limits find match and recursion limits
|
||||
find_limits find match and depth limits
|
||||
get=<number or name> extract captured substring
|
||||
getall extract all captured substrings
|
||||
/g global global matching
|
||||
jitstack=<n> set size of JIT stack
|
||||
mark show mark values
|
||||
match_limit=<n> set a match limit
|
||||
memory show memory usage
|
||||
memory show heap memory usage
|
||||
null_context match with a NULL context
|
||||
offset=<n> set starting offset
|
||||
offset_limit=<n> set offset limit
|
||||
|
|
@ -1339,25 +1339,29 @@ limits in the match context. These values are ignored when the
|
|||
Finding minimum limits
|
||||
</b><br>
|
||||
<P>
|
||||
If the <b>find_limits</b> modifier is present, <b>pcre2test</b> calls
|
||||
<b>pcre2_match()</b> several times, setting different values in the match
|
||||
context via <b>pcre2_set_match_limit()</b> and <b>pcre2_set_depth_limit()</b>
|
||||
until it finds the minimum values for each parameter that allow
|
||||
<b>pcre2_match()</b> to complete without error.
|
||||
If the <b>find_limits</b> modifier is present on a subject line, <b>pcre2test</b>
|
||||
calls the relevant matching function several times, setting different values in
|
||||
the match context via <b>pcre2_set_match_limit()</b> or
|
||||
<b>pcre2_set_depth_limit()</b> until it finds the minimum values for each
|
||||
parameter that allows the match to complete without error.
|
||||
</P>
|
||||
<P>
|
||||
If JIT is being used, only the match limit is relevant. If DFA matching is
|
||||
being used, only the depth limit is relevant, but at present this modifier is
|
||||
ignored (with a warning message).
|
||||
being used, only the depth limit is relevant.
|
||||
</P>
|
||||
<P>
|
||||
The <i>match_limit</i> number is a measure of the amount of backtracking
|
||||
that takes place, and learning the minimum value can be instructive. For most
|
||||
simple matches, the number is quite small, but for patterns with very large
|
||||
numbers of matching possibilities, it can become large very quickly with
|
||||
increasing length of subject string. The <i>depth_limit</i> number is
|
||||
a measure of how much memory for recording backtracking points is needed to
|
||||
complete the match attempt.
|
||||
increasing length of subject string.
|
||||
</P>
|
||||
<P>
|
||||
For non-DFA matching, the minimum <i>depth_limit</i> number is a measure of how
|
||||
much memory for recording backtracking points is needed to complete the match
|
||||
attempt. In the case of DFA matching, <i>depth_limit</i> controls the depth of
|
||||
recursive calls of the internal function that is used for handling pattern
|
||||
recursion, lookaround assertions, and atomic groups.
|
||||
</P>
|
||||
<br><b>
|
||||
Showing MARK names
|
||||
|
|
@ -1373,8 +1377,11 @@ is added to the non-match message.
|
|||
Showing memory usage
|
||||
</b><br>
|
||||
<P>
|
||||
The <b>memory</b> modifier causes <b>pcre2test</b> to log all memory allocation
|
||||
and freeing calls that occur during a match operation.
|
||||
The <b>memory</b> modifier causes <b>pcre2test</b> to log all heap memory
|
||||
allocation and freeing calls that occur during a call to <b>pcre2_match()</b>.
|
||||
These occur only when a match requires a bigger vector than the default for
|
||||
remembering backtracking points. In many cases there will be none. No heap
|
||||
memory is allocated during matching with <b>pcre2_dfa_match</b> or with JIT.
|
||||
</P>
|
||||
<br><b>
|
||||
Setting a starting offset
|
||||
|
|
@ -1787,7 +1794,7 @@ Cambridge, England.
|
|||
</P>
|
||||
<br><a name="SEC21" href="#TOC1">REVISION</a><br>
|
||||
<P>
|
||||
Last updated: 21 March 2017
|
||||
Last updated: 24 March 2017
|
||||
<br>
|
||||
Copyright © 1997-2017 University of Cambridge.
|
||||
<br>
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
.TH PCRE2_MATCH 3 "21 October 2014" "PCRE2 10.00"
|
||||
.TH PCRE2_MATCH 3 "25 March 2017" "PCRE2 10.30"
|
||||
.SH NAME
|
||||
PCRE2 - Perl-compatible regular expressions (revised API)
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -31,26 +31,33 @@ offsets to captured substrings. Its arguments are:
|
|||
A match context is needed only if you want to:
|
||||
.sp
|
||||
Set up a callout function
|
||||
Change the limit for calling the internal function \fImatch()\fP
|
||||
Change the limit for calling \fImatch()\fP recursively
|
||||
Set custom memory management when the heap is used for recursion
|
||||
Set a matching offset limit
|
||||
Change the backtracking match limit
|
||||
Change the backtracking depth limit
|
||||
Set custom memory management in the match context
|
||||
.sp
|
||||
The \fIlength\fP and \fIstartoffset\fP values are code
|
||||
units, not characters. The options are:
|
||||
units, not characters. The length may be given as PCRE2_ZERO_TERMINATE for a
|
||||
subject that is terminated by a binary zero code unit. The options are:
|
||||
.sp
|
||||
PCRE2_ANCHORED Match only at the first position
|
||||
PCRE2_NOTBOL Subject string is not the beginning of a line
|
||||
PCRE2_NOTEOL Subject string is not the end of a line
|
||||
PCRE2_NOTEMPTY An empty string is not a valid match
|
||||
.\" JOIN
|
||||
PCRE2_NOTEMPTY_ATSTART An empty string at the start of the subject
|
||||
is not a valid match
|
||||
PCRE2_NO_JIT Do not use JIT matching
|
||||
.\" JOIN
|
||||
PCRE2_NO_UTF_CHECK Do not check the subject for UTF
|
||||
validity (only relevant if PCRE2_UTF
|
||||
was set at compile time)
|
||||
.\" JOIN
|
||||
PCRE2_PARTIAL_HARD Return PCRE2_ERROR_PARTIAL for a partial
|
||||
match even if there is a full match
|
||||
.\" JOIN
|
||||
PCRE2_PARTIAL_SOFT Return PCRE2_ERROR_PARTIAL for a partial
|
||||
match if no full matches are found
|
||||
PCRE2_PARTIAL_HARD Return PCRE2_ERROR_PARTIAL for a partial match
|
||||
if that is found before a full match
|
||||
.sp
|
||||
For details of partial matching, see the
|
||||
.\" HREF
|
||||
|
|
|
|||
|
|
@ -966,14 +966,14 @@ SUBJECT MODIFIERS
|
|||
copy=<number or name> copy captured substring
|
||||
depth_limit=<n> set a depth limit
|
||||
dfa use pcre2_dfa_match()
|
||||
find_limits find match and recursion limits
|
||||
find_limits find match and depth limits
|
||||
get=<number or name> extract captured substring
|
||||
getall extract all captured substrings
|
||||
/g global global matching
|
||||
jitstack=<n> set size of JIT stack
|
||||
mark show mark values
|
||||
match_limit=<n> set a match limit
|
||||
memory show memory usage
|
||||
memory show heap memory usage
|
||||
null_context match with a NULL context
|
||||
offset=<n> set starting offset
|
||||
offset_limit=<n> set offset limit
|
||||
|
|
@ -1202,23 +1202,26 @@ SUBJECT MODIFIERS
|
|||
|
||||
Finding minimum limits
|
||||
|
||||
If the find_limits modifier is present, pcre2test calls pcre2_match()
|
||||
several times, setting different values in the match context via
|
||||
pcre2_set_match_limit() and pcre2_set_depth_limit() until it finds the
|
||||
minimum values for each parameter that allow pcre2_match() to complete
|
||||
without error.
|
||||
If the find_limits modifier is present on a subject line, pcre2test
|
||||
calls the relevant matching function several times, setting different
|
||||
values in the match context via pcre2_set_match_limit() or
|
||||
pcre2_set_depth_limit() until it finds the minimum values for each
|
||||
parameter that allows the match to complete without error.
|
||||
|
||||
If JIT is being used, only the match limit is relevant. If DFA matching
|
||||
is being used, only the depth limit is relevant, but at present this
|
||||
modifier is ignored (with a warning message).
|
||||
is being used, only the depth limit is relevant.
|
||||
|
||||
The match_limit number is a measure of the amount of backtracking that
|
||||
takes place, and learning the minimum value can be instructive. For
|
||||
most simple matches, the number is quite small, but for patterns with
|
||||
very large numbers of matching possibilities, it can become large very
|
||||
quickly with increasing length of subject string. The depth_limit num-
|
||||
ber is a measure of how much memory for recording backtracking points
|
||||
is needed to complete the match attempt.
|
||||
quickly with increasing length of subject string.
|
||||
|
||||
For non-DFA matching, the minimum depth_limit number is a measure of
|
||||
how much memory for recording backtracking points is needed to complete
|
||||
the match attempt. In the case of DFA matching, depth_limit controls
|
||||
the depth of recursive calls of the internal function that is used for
|
||||
handling pattern recursion, lookaround assertions, and atomic groups.
|
||||
|
||||
Showing MARK names
|
||||
|
||||
|
|
@ -1231,8 +1234,12 @@ SUBJECT MODIFIERS
|
|||
|
||||
Showing memory usage
|
||||
|
||||
The memory modifier causes pcre2test to log all memory allocation and
|
||||
freeing calls that occur during a match operation.
|
||||
The memory modifier causes pcre2test to log all heap memory allocation
|
||||
and freeing calls that occur during a call to pcre2_match(). These
|
||||
occur only when a match requires a bigger vector than the default for
|
||||
remembering backtracking points. In many cases there will be none. No
|
||||
heap memory is allocated during matching with pcre2_dfa_match or with
|
||||
JIT.
|
||||
|
||||
Setting a starting offset
|
||||
|
||||
|
|
@ -1619,5 +1626,5 @@ AUTHOR
|
|||
|
||||
REVISION
|
||||
|
||||
Last updated: 21 March 2017
|
||||
Last updated: 24 March 2017
|
||||
Copyright (c) 1997-2017 University of Cambridge.
|
||||
|
|
|
|||
Loading…
Reference in New Issue