Home | History | Annotate | Download | only in html 
      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>
      8 Return to the <a href="index.html">PCRE2 index page</a>.
      9 </p>
     10 <p>
     11 This page is part of the PCRE2 HTML documentation. It was generated
     12 automatically from the original man page. If there is any nonsense in it,
     13 please consult the man page, in case the conversion went wrong.
     14 <br>
     15 <br><b>
     16 SYNOPSIS
     17 </b><br>
     18 <P>
     19 <b>#include &#60;pcre2.h&#62;</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>
     30 DESCRIPTION
     31 </b><br>
     32 <P>
     33 This function matches a compiled regular expression against a given subject
     34 string, using a matching algorithm that is similar to Perl's. It then makes a
     35 copy of the subject, substituting a replacement string for what was matched.
     36 Its 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>
     50 A match data block is needed only if you want to inspect the data from the
     51 match that is returned in that block. A match context is needed only if you
     52 want 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>
     60 The <i>length</i>, <i>startoffset</i> and <i>rlength</i> values are code
     61 units, 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.
     63 The subject and replacement lengths can be given as PCRE2_ZERO_TERMINATED for
     64 zero-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>
     81 The function returns the number of substitutions, which may be zero if there
     82 were no matches. The result can be greater than one only when
     83 PCRE2_SUBSTITUTE_GLOBAL is set. In the event of an error, a negative error code
     84 is returned.
     85 </P>
     86 <P>
     87 There is a complete description of the PCRE2 native API in the
     88 <a href="pcre2api.html"><b>pcre2api</b></a>
     89 page and a description of the POSIX API in the
     90 <a href="pcre2posix.html"><b>pcre2posix</b></a>
     91 page.
     92 <p>
     93 Return to the <a href="index.html">PCRE2 index page</a>.
     94 </p>
     95