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 context is needed only if you want to: 51<pre> 52 Set up a callout function 53 Change the limit for calling the internal function <i>match()</i> 54 Change the limit for calling <i>match()</i> recursively 55 Set custom memory management when the heap is used for recursion 56</pre> 57The <i>length</i>, <i>startoffset</i> and <i>rlength</i> values are code 58units, not characters, as is the contents of the variable pointed at by 59<i>outlengthptr</i>, which is updated to the actual length of the new string. 60The options are: 61<pre> 62 PCRE2_ANCHORED Match only at the first position 63 PCRE2_NOTBOL Subject is not the beginning of a line 64 PCRE2_NOTEOL Subject is not the end of a line 65 PCRE2_NOTEMPTY An empty string is not a valid match 66 PCRE2_NOTEMPTY_ATSTART An empty string at the start of the 67 subject is not a valid match 68 PCRE2_NO_UTF_CHECK Do not check the subject or replacement 69 for UTF validity (only relevant if 70 PCRE2_UTF was set at compile time) 71 PCRE2_SUBSTITUTE_EXTENDED Do extended replacement processing 72 PCRE2_SUBSTITUTE_GLOBAL Replace all occurrences in the subject 73 PCRE2_SUBSTITUTE_OVERFLOW_LENGTH If overflow, compute needed length 74 PCRE2_SUBSTITUTE_UNKNOWN_UNSET Treat unknown group as unset 75 PCRE2_SUBSTITUTE_UNSET_EMPTY Simple unset insert = empty string 76</pre> 77The function returns the number of substitutions, which may be zero if there 78were no matches. The result can be greater than one only when 79PCRE2_SUBSTITUTE_GLOBAL is set. In the event of an error, a negative error code 80is returned. 81</P> 82<P> 83There is a complete description of the PCRE2 native API in the 84<a href="pcre2api.html"><b>pcre2api</b></a> 85page and a description of the POSIX API in the 86<a href="pcre2posix.html"><b>pcre2posix</b></a> 87page. 88<p> 89Return to the <a href="index.html">PCRE2 index page</a>. 90</p> 91