src/external/pcre2-10.32/doc/html/pcre2_substitute.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>