1<html> 2<head> 3<title>pcre2_substitute specification</title> 4</head> 5<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> 6<h1>pcre2_substitute man page</h1> 7<p> 8Return to the <a href="index.html">PCRE2 index page</a>. 9</p> 10<p> 11This page is part of the PCRE2 HTML documentation. It was generated 12automatically from the original man page. If there is any nonsense in it, 13please consult the man page, in case the conversion went wrong. 14<br> 15<br><b> 16SYNOPSIS 17</b><br> 18<P> 19<b>#include <pcre2.h></b> 20</P> 21<P> 22<b>int pcre2_substitute(const pcre2_code *<i>code</i>, PCRE2_SPTR <i>subject</i>,</b> 23<b> PCRE2_SIZE <i>length</i>, PCRE2_SIZE <i>startoffset</i>,</b> 24<b> uint32_t <i>options</i>, pcre2_match_data *<i>match_data</i>,</b> 25<b> pcre2_match_context *<i>mcontext</i>, PCRE2_SPTR <i>replacement</i>,</b> 26<b> PCRE2_SIZE <i>rlength</i>, PCRE2_UCHAR *<i>outputbuffer</i>,</b> 27<b> PCRE2_SIZE *<i>outlengthptr</i>);</b> 28</P> 29<br><b> 30DESCRIPTION 31</b><br> 32<P> 33This function matches a compiled regular expression against a given subject 34string, using a matching algorithm that is similar to Perl's. It then makes a 35copy of the subject, substituting a replacement string for what was matched. 36Its arguments are: 37<pre> 38 <i>code</i> Points to the compiled pattern 39 <i>subject</i> Points to the subject string 40 <i>length</i> Length of the subject string 41 <i>startoffset</i> Offset in the subject at which to start matching 42 <i>options</i> Option bits 43 <i>match_data</i> Points to a match data block, or is NULL 44 <i>mcontext</i> Points to a match context, or is NULL 45 <i>replacement</i> Points to the replacement string 46 <i>rlength</i> Length of the replacement string 47 <i>outputbuffer</i> Points to the output buffer 48 <i>outlengthptr</i> Points to the length of the output buffer 49</pre> 50A match data block is needed only if you want to inspect the data from the 51match that is returned in that block. A match context is needed only if you 52want to: 53<pre> 54 Set up a callout function 55 Set a matching offset limit 56 Change the backtracking match limit 57 Change the backtracking depth limit 58 Set custom memory management in the match context 59</pre> 60The <i>length</i>, <i>startoffset</i> and <i>rlength</i> values are code 61units, not characters, as is the contents of the variable pointed at by 62<i>outlengthptr</i>, which is updated to the actual length of the new string. 63The subject and replacement lengths can be given as PCRE2_ZERO_TERMINATED for 64zero-terminated strings. The options are: 65<pre> 66 PCRE2_ANCHORED Match only at the first position 67 PCRE2_ENDANCHORED Pattern can match only at end of subject 68 PCRE2_NOTBOL Subject is not the beginning of a line 69 PCRE2_NOTEOL Subject is not the end of a line 70 PCRE2_NOTEMPTY An empty string is not a valid match 71 PCRE2_NOTEMPTY_ATSTART An empty string at the start of the subject is not a valid match 72 PCRE2_NO_JIT Do not use JIT matching 73 PCRE2_NO_UTF_CHECK Do not check the subject or replacement for UTF validity (only relevant if 74 PCRE2_UTF was set at compile time) 75 PCRE2_SUBSTITUTE_EXTENDED Do extended replacement processing 76 PCRE2_SUBSTITUTE_GLOBAL Replace all occurrences in the subject 77 PCRE2_SUBSTITUTE_OVERFLOW_LENGTH If overflow, compute needed length 78 PCRE2_SUBSTITUTE_UNKNOWN_UNSET Treat unknown group as unset 79 PCRE2_SUBSTITUTE_UNSET_EMPTY Simple unset insert = empty string 80</pre> 81The function returns the number of substitutions, which may be zero if there 82were no matches. The result can be greater than one only when 83PCRE2_SUBSTITUTE_GLOBAL is set. In the event of an error, a negative error code 84is returned. 85</P> 86<P> 87There is a complete description of the PCRE2 native API in the 88<a href="pcre2api.html"><b>pcre2api</b></a> 89page and a description of the POSIX API in the 90<a href="pcre2posix.html"><b>pcre2posix</b></a> 91page. 92<p> 93Return to the <a href="index.html">PCRE2 index page</a>. 94</p> 95