mirror of
https://github.com/PCRE2Project/pcre2.git
synced 2025-10-17 15:25:55 +08:00
eb3bd3cf14
* The primary purpose of pcre2_next_match() is to make it much easier for PCRE2 clients to iterate over matches, without needing an advanced knowledge of regular expressions. * Secondly, we can simplify our own code by merging the three duplicate implementations of the /g global match behaviour: pcre2demo, pcre2_substitute, and pcre2test. * Thirdly, as I look closely at the issue, I can improve the documentation. * Fourthly, I would like to actually simplify the logic, removing a complex loop which makes several match attempts, swallows duplicate matches, and more. We can have identical behaviour with a simple retry using PCRE2_NOTEMPTY_ATSTART.
42 lines
1.4 KiB
Groff
42 lines
1.4 KiB
Groff
.TH PCRE2_NEXT_MATCH 3 "01 March 2025" "PCRE2 10.46-DEV"
|
|
.SH NAME
|
|
PCRE2 - Perl-compatible regular expressions (revised API)
|
|
.SH SYNOPSIS
|
|
.rs
|
|
.sp
|
|
.B #include <pcre2.h>
|
|
.PP
|
|
.nf
|
|
.B int pcre2_next_match(pcre2_match_data *\fImatch_data\fP,
|
|
.B " PCRE2_SIZE *\fIpstart_offset\fP, uint32_t *\fIpoptions\fP);"
|
|
.fi
|
|
.
|
|
.SH DESCRIPTION
|
|
.rs
|
|
.sp
|
|
This function can be called after one of the match functions
|
|
(\fBpcre2_match()\fP, \fBpcre2_dfa_match()\fP, or \fBpcre2_jit_match()\fP), and
|
|
must be provided with the same \fImatch_data\fP parameter. It outputs the
|
|
appropriate parameters for searching for the next match in the same subject
|
|
string, and is suitable for applications providing "global" matching behaviour
|
|
(for example, replacing all matches in the subject, or splitting the subject on
|
|
all matches, or simply counting the number of matches).
|
|
.P
|
|
It returns 0 ("false") if there is no need to make any further match attempts,
|
|
or 1 ("true") if another match should be attempted.
|
|
.P
|
|
The *\fIpstart_offset\fP and *\fIpoptions\fP are set if the function returns 1.
|
|
The *\fIpstart_offset\fP should be passed to the next match attempt directly,
|
|
and the *\fIpoptions\fP should be passed to the next match attempt by combining
|
|
with the application's match options using OR.
|
|
.P
|
|
There is a complete description of the PCRE2 native API in the
|
|
.\" HREF
|
|
\fBpcre2api\fP
|
|
.\"
|
|
page and a description of the POSIX API in the
|
|
.\" HREF
|
|
\fBpcre2posix\fP
|
|
.\"
|
|
page.
|