Lines Matching full:is

20        PCRE2 is the name used for a revised API for the PCRE library, which is
25        Python syntax. There is also some support for one or two .NET and Onig-
35        Unicode general category properties. Unicode  support  is  optional  at
36        build  time  (but  is  the default). However, processing strings as UTF
46        generic names such as pcre2_compile(), and the documentation is written
47        assuming that this is the case.
57        pcre2pattern and pcre2compat pages. There is a syntax  summary  in  the
61        library is built. The pcre2_config() function makes it possible  for  a
71        any name clashes. In some environments, it is possible to control which
72        external  symbols  are  exported when a shared library is built, and in
84        tern and any data against which it is matched to be checked  for  UTF-8
85        validity.  If the data string is very long, such a check might use suf-
89        One  way  of guarding against this possibility is to use the pcre2_pat-
99        If  your  application  is one that supports UTF, be aware that validity
100        checking can take time. If the same data string is to be  matched  many
108        a compile-time error if it is encountered. It is also possible to build
111        Another  way  that  performance can be hit is by running a pattern that
121        tions. In the "man" format, each of these is a separate "man page".  In
122        the  HTML  format, each is a separate page, linked from the index page.
126        (which  is a program listing), and the short pages for individual func-
152        In  the  "man"  and HTML formats, there is also a short page for each C
162        Putting an actual email address here is a spam magnet. If you  want  to
183        PCRE2  is  a  new API for PCRE. This document contains a description of
399        code units, respectively. However,  there  is  just  one  header  file,
421        For  example,  PCRE2_UCHAR16 is usually defined as `uint16_t'. The SPTR
422        types are constant pointers to the equivalent  UCHAR  types,  that  is,
429        tion and macro names.  PCRE2_CODE_UNIT_WIDTH is not defined by default.
436        Any code that is to be included in an environment where  the  value  of
437        PCRE2_CODE_UNIT_WIDTH  is  unknown  should  also  use the real function
438        names. (Unfortunately, it is not possible in C code to save and restore
441        If  PCRE2_CODE_UNIT_WIDTH  is  not  defined before including pcre2.h, a
457        PCRE2 has its own native API, which  is  described  in  this  document.
475        program that demonstrates the simplest way of using them is provided in
477        of this program is  given  in  the  pcre2demo  documentation,  and  the
480        Just-in-time  compiler support is an optional feature of PCRE2 that can
485        support is not available.
492        JIT matching is automatically used by pcre2_match() if it is available,
493        unless the PCRE2_NO_JIT option is set. There is also a direct interface
497        A second matching function, pcre2_dfa_match(), which is  not  Perl-com-
498        patible,  is  also  provided.  This  uses a different algorithm for the
503        rithms  and  their  advantages  and  disadvantages  is  given  in   the
504        pcre2matching    documentation.   There   is   no   JIT   support   for
536        blocks  of  various  sorts.  In all cases, if one of these functions is
544        which is an unsigned integer type, currently always defined as  size_t.
545        The  largest  value  that  can  be  stored  in  such  a  type  (that is
546        ~(PCRE2_SIZE)0) is reserved as a special indicator for  zero-terminated
548        handled is one less than this maximum.
561        Each of the first three conventions is used by at least  one  operating
562        system as its standard newline sequence. When PCRE2 is built, a default
563        can be specified.  The default default is LF, which is the  Unix  stan-
569        In the PCRE2 documentation the word "newline"  is  used  to  mean  "the
573        CRLF is a recognized line ending sequence, the match position  advance-
574        ment for a non-anchored pattern. There is more detail about this in the
584        In a multithreaded application it is important to keep  thread-specific
586        library code itself is thread-safe: it contains  no  static  or  global
587        variables.  The  API  is  designed to be fairly simple for non-threaded
596        A pointer to the compiled form of a pattern is  returned  to  the  user
597        when pcre2_compile() is successful. The data in the compiled pattern is
598        fixed, and does not change when the pattern is matched.  Therefore,  it
599        is  thread-safe, that is, the same compiled pattern can be used by more
602        use them. However, if the just-in-time optimization  feature  is  being
624        If JIT is being used, but the JIT compilation is not being done immedi-
625        ately, (perhaps waiting to see if the pattern  is  used  often  enough)
626        similar logic is required. JIT compilation updates a pointer within the
635        PCRE2 functions are called. A context is nothing more than a collection
637        parameters together in a context is a convenient way of passing them to
662        in a context instead of directly. A context is just a block  of  memory
665        pointer is required.
667        There  are  three different types of context: a general context that is
675        places in the PCRE2 library. The context is named `general' rather than
678        you do not need to bother with a general context. A general context  is
691        Whenever code in PCRE2 calls these functions, the final argument is the
694        tions  malloc()  and free() are used. (This is not currently useful, as
696        might  be.)   The  private_malloc()  function  is used (if supplied) to
702        was  used.  When  the  time  comes  to free the block, this function is
717        A compile context is required if you want to change the default  values
727        A  compile context is also required if you are using custom memory man-
731        A  compile context is created, copied, and freed by the following func-
742        A compile context is created with default values  for  its  parameters.
744        on success, or PCRE2_ERROR_BADDATA if invalid data is detected.
751        Unicode line ending sequence. The value is used by the JIT compiler and
759        only argument is a general context. This function builds a set of char-
766        is  to  be  compiled.  If the pattern is longer, an error is generated.
767        This facility is provided so that  applications  that  accept  patterns
768        from  external sources can limit their size. The default is the largest
769        number that a PCRE2_SIZE variable can hold, which is effectively unlim-
781        When a pattern is compiled with the PCRE2_EXTENDED option, the value of
783        internal comments starting with #. The value is saved with the compiled
790        This parameter ajusts the limit, set when PCRE2 is built (default 250),
797        There  is at least one application that runs PCRE2 in threads with very
798        limited system stack, where running out of stack is to  be  avoided  at
800        stack is actually available. For a finer  control,  you  can  supply  a
801        function  that  is  called whenever pcre2_compile() starts to compile a
806        nesting, and the second is user data that is set up by the  last  argu-
808        should return zero if all is well, or non-zero to force an error.
812        A match context is required if you want to change the default values of
820        A match context is also required if you are using custom memory manage-
824        A  match  context  is created, copied, and freed by the following func-
835        A match context is created with  default  values  for  its  parameters.
837        on success, or PCRE2_ERROR_BADDATA if invalid data is detected.
851        advance  in  the  subject string. The default value is PCRE2_UNSET. The
854        given offset is not found. For example, if the pattern /abc/ is matched
855        against  "123abc"  with  an  offset  limit  less  than 3, the result is
857        argument of pcre2_match() or pcre2_dfa_match() is greater than the off-
861        calling  pcre2_compile() so that when JIT is in use, different code can
862        be compiled. If a match is started with a non-default match limit  when
863        PCRE2_USE_OFFSET_LIMIT is not set, an error is generated.
868        is set with an offset limit, a match must occur in the first  line  and
870        first is used.
878        search  trees. The classic example is a pattern that uses nested unlim-
883        is imposed on the number of times this  function  is  called  during  a
886        from  zero  for  each position in the subject string. This limit is not
889        When pcre2_match() is called with a pattern that was successfully  pro-
890        cessed by pcre2_jit_compile(), the way in which matching is executed is
891        entirely different. However, there is still the possibility of  runaway
893        value is also used in this case (but in a different way) to  limit  how
896        The  default  value  for  the limit can be set when PCRE2 is built; the
897        default default is 10 million, which handles all but the  most  extreme
898        cases.    If    the    limit   is   exceeded,   pcre2_match()   returns
904        where  ddd  is  a  decimal  number.  However, such a setting is ignored
905        unless ddd is less than the limit set by the  caller  of  pcre2_match()
906        or, if no such limit is set, less than the default.
911        The recursion_limit parameter is similar to match_limit, but instead of
912        limiting the total number of times that match() is  called,  it  limits
913        the  depth  of  recursion. The recursion depth is a smaller number than
915        sive.  This limit is of use only if it is set smaller than match_limit.
920        limit is not relevant, and is ignored, when matching is done using  JIT
923        The  default  value for recursion_limit can be set when PCRE2 is built;
924        the default default is the same value as the default  for  match_limit.
925        If  the limit is exceeded, pcre2_match() returns PCRE2_ERROR_RECURSION-
931        where  ddd  is  a  decimal  number.  However, such a setting is ignored
932        unless ddd is less than the limit set by the  caller  of  pcre2_match()
933        or, if no such limit is set, less than the default.
941        for use by pcre2_match() when PCRE2 is compiled to  use  the  heap  for
943        use the system stack. There is a discussion about PCRE2's  stack  usage
947        Using the heap for recursion is a non-standard way of  building  PCRE2,
953        retained by pcre2_match() until it is about to exit so that they can be
968        The first argument for pcre2_config() specifies  which  information  is
969        required.  The  second  argument  is a pointer to memory into which the
970        information is placed. If NULL is  passed,  the  function  returns  the
971        amount  of  memory  that  is  needed for the requested information. For
972        calls that return  numerical  values,  the  value  is  in  bytes;  when
974        memory. For calls that return strings, the required length is given  in
977        When  requesting information, the returned value from pcre2_config() is
979        TION  if the value in the first argument is not recognized. The follow-
980        ing information is available:
984        The output is a uint32_t integer whose value indicates  what  character
988        LF, or CRLF. The default can be overridden when a pattern is compiled.
992        The output is a uint32_t integer that is set  to  one  if  support  for
993        just-in-time compiling is available; otherwise it is set to zero.
997        The  where  argument  should point to a buffer that is at least 48 code
999        pcre2_config()  with  where  set  to NULL.) The buffer is filled with a
1001        compiler  is  configured,  for  example  "x86  32bit  (little  endian +
1002        unaligned)". If JIT support is not available, PCRE2_ERROR_BADOPTION  is
1003        returned,  otherwise the number of code units used is returned. This is
1008        The output is a uint32_t integer that contains the number of bytes used
1009        for  internal  linkage  in  compiled regular expressions. When PCRE2 is
1011        2.  This is the value that is returned by pcre2_config(). However, when
1012        the 16-bit library is compiled, a value of 3 is rounded up  to  4,  and
1013        when  the  32-bit  library  is compiled, internal linkages always use 4
1014        bytes, so the configured value is not relevant.
1016        The default value of 2 for the 8-bit and 16-bit libraries is sufficient
1024        The output is a uint32_t integer that gives the default limit  for  the
1030        The output is a uint32_t integer  whose  value  specifies  the  default
1031        character  sequence that is recognized as meaning "newline". The values
1045        The  output is a uint32_t integer that gives the maximum depth of nest-
1046        ing of parentheses (of any kind) in a pattern. This limit is imposed to
1047        cap  the  amount of system stack used when a pattern is compiled. It is
1048        specified when PCRE2 is built; the default is 250. This limit does  not
1055        The  output  is a uint32_t integer that gives the default limit for the
1062        The output is a uint32_t integer that is set to one if internal  recur-
1063        sion  when  running  pcre2_match() is implemented by recursive function
1064        calls that use the system stack to remember their state.  This  is  the
1065        usual  way that PCRE2 is compiled. The output is zero if PCRE2 was com-
1071        The  where  argument  should point to a buffer that is at least 24 code
1074        without Unicode support, the buffer is filled with  the  text  "Unicode
1076        "8.0.0") is inserted. The number of code units used is  returned.  This
1077        is the length of the string plus one unit for the terminating zero.
1081        The  output is a uint32_t integer that is set to one if Unicode support
1082        is available; otherwise it is set to zero. Unicode support implies  UTF
1087        The  where  argument  should point to a buffer that is at least 12 code
1089        pcre2_config()  with  where set to NULL.) The buffer is filled with the
1090        PCRE2 version string, zero-terminated. The number of code units used is
1091        returned. This is the length of the string plus one unit for the termi-
1106        The  pattern  is  defined  by a pointer to a string of code units and a
1107        length. If the pattern is zero-terminated, the length can be  specified
1112        If  the  compile context argument ccontext is NULL, memory for the com-
1113        piled pattern  is  obtained  by  calling  malloc().  Otherwise,  it  is
1116        when it is no longer needed.
1121        below), the JIT information cannot be copied (because it  is  position-
1128        NOTE:  When  one  of  the matching functions is called, pointers to the
1151        If errorcode or erroroffset is NULL, pcre2_compile() returns NULL imme-
1155        error has occurred. The values are not defined when compilation is suc-
1161        negative. For an invalid UTF-8 or UTF-16 string, the offset is that  of
1165        in these cases, the offset passed back is the length  of  the  pattern.
1166        Note  that  the  offset is in code units, not characters, even in a UTF
1178            PCRE2_ZERO_TERMINATED,  /* the pattern is zero-terminated */
1189        If this bit is set, the pattern is forced to be "anchored", that is, it
1190        is constrained to match only at the first matching point in the  string
1191        that  is being searched (the "subject string"). This effect can also be
1192        achieved by appropriate constructs in the pattern itself, which is  the
1198        immediately follows an opening one is treated as a data  character  for
1199        the  class.  When  PCRE2_ALLOW_EMPTY_CLASS  is  set,  it terminates the
1206        When it is set:
1211        (2) \u matches a lower case "u" character unless it is followed by four
1216        (3) \x matches a lower case "x" character unless it is followed by  two
1218        code point to match. By default, as in Perl, a  hexadecimal  number  is
1224        In  multiline  mode  (when  PCRE2_MULTILINE  is  set),  the  circumflex
1226        is set), and also after any internal  newline.  However,  it  does  not
1234        such as (*MARK:NAME) is  any  sequence  of  characters  that  does  not
1235        include  a  closing  parenthesis. The name is not processed in any way,
1236        and it is not possible to include a closing parenthesis  in  the  name.
1237        However,  if  the  PCRE2_ALT_VERBNAMES  option is set, normal backslash
1238        processing is applied to verb  names  and  only  an  unescaped  closing
1241        option is set, unescaped whitespace in verb names is skipped and #-com-
1246        If this bit  is  set,  pcre2_compile()  automatically  inserts  callout
1252        If this bit is set, letters in the pattern match both upper  and  lower
1253        case  letters in the subject. It is equivalent to Perl's /i option, and
1258        If this bit is set, a dollar metacharacter in the pattern matches  only
1261        before  any other newlines). The PCRE2_DOLLAR_ENDONLY option is ignored
1262        if PCRE2_MULTILINE is set. There is no equivalent  to  this  option  in
1267        If  this  bit  is  set,  a dot metacharacter in the pattern matches any
1271        ject  is  at  a newline. This option is equivalent to Perl's /s option,
1278        If this bit is set, names used to identify capturing  subpatterns  need
1280        is known that only one instance of the named  subpattern  can  ever  be
1286        If this bit is set, most white space  characters  in  the  pattern  are
1288        ever, white space is not allowed within  sequences  such  as  (?>  that
1290        tifiers such as {1,3}.  Ignorable white space is permitted  between  an
1297        that  the  end of this type of comment is a literal newline sequence in
1299        count.  PCRE2_EXTENDED is equivalent to Perl's /x option, and it can be
1303        ting  in  the compile context that is passed to pcre2_compile() or by a
1306        A default is defined when PCRE2 is built.
1310        If this option is set, an  unanchored  pattern  is  required  to  match
1314        PCRE2_FIRSTLINE is set with an offset limit, a match must occur in  the
1316        limit comes first is used.
1320        If this option is set, a back reference to an  unset  subpattern  group
1323        option  is set (assuming it can find an "a" in the subject), whereas it
1335        LAR_ENDONLY  is  set).  Note, however, that unless PCRE2_DOTALL is set,
1337        behaviour (for ^, $, and dot) is the same as Perl.
1339        When  PCRE2_MULTILINE  it is set, the "start of line" and "end of line"
1342        start and end. This is equivalent to Perl's /m option, and  it  can  be
1352        This option locks out the use of \C in the pattern that is  being  com-
1357        there is also a build-time option that permanently locks out the use of
1373        or UTF-32, depending on which library is in use. In particular, it pre-
1381        If this option is set, it disables the use of numbered capturing paren-
1382        theses in the pattern. Any opening parenthesis that is not followed  by
1385        There  is  no  equivalent  of  this  option in Perl. Note that, if this
1386        option is set, references  to  capturing  groups  (back  references  or
1392        If this option is set, it disables "auto-possessification", which is an
1397        a  full  unoptimized  search and run all the callouts, but it is mainly
1402        If this option is set, it disables an optimization that is applied when
1403        .*  is  the  first significant item in a top-level branch of a pattern,
1405        The  optimization  is  automatically disabled for .* if it is inside an
1406        atomic group or a capturing group that is the subject of a back  refer-
1408        mization is not disabled, such a pattern is automatically  anchored  if
1409        PCRE2_DOTALL is set for all the .* items and PCRE2_MULTILINE is not set
1411        at  the start of the subject or following a newline is remembered. Like
1416        This is an option whose main effect is at matching time.  It  does  not
1421        match,  in  order  to speed up the process. For example, if it is known
1426        start of a pattern is not considered until after  a  suitable  starting
1429        skipped  if  the pattern is never actually used. The start-up optimiza-
1431        the pattern is run.
1435        where  the  result is "no match", the callouts do occur, and that items
1444        When this is compiled, PCRE2 records the fact that a match  must  start
1445        with  the  character  "A".  Suppose the subject string is "DEFABC". The
1449        does.  However,  if  the same match is run with PCRE2_NO_START_OPTIMIZE
1451        first  match  attempt  is  run  starting  from "D" and when this fails,
1453        result is "no match". There are also other start-up optimizations.  For
1459        The  minimum  length  for  a  match is one character. If the subject is
1462        because PCRE2 knows that the subject is  now  too  short,  and  so  the
1463        (*MARK)  is  never encountered. In this case, the optimization does not
1464        affect the overall match result, which is still "no match", but it does
1465        affect the auxiliary information that is returned.
1469        When  PCRE2_UTF  is set, the validity of the pattern as a UTF string is
1472        document.  If an invalid UTF sequence is found, pcre2_compile() returns
1475        If you know that your pattern is valid, and you want to skip this check
1477        When  it  is set, the effect of passing an invalid UTF string as a pat-
1478        tern is undefined. It may cause your program to  crash  or  loop.  Note
1486        characters are recognized, but if PCRE2_UCP is set, Unicode  properties
1490        option is available only if PCRE2 has been compiled with  Unicode  sup-
1496        are not greedy by default, but become greedy if followed by "?". It  is
1503        is  going  to be used to set a non-default offset limit in a match con-
1504        text for matches that use this pattern. An error  is  generated  if  an
1505        offset  limit  is  set  without  this option. For more details, see the
1513        instead  of  single-code-unit  strings.  It  is available when PCRE2 is
1514        built to include Unicode support (which is  the  default).  If  Unicode
1515        support  is  not  available,  the use of this option provokes an error.
1551        just-in-time compiler is available, further processes a  compiled  pat-
1556        JIT  compilation  is  a heavyweight optimization. It can take some time
1569        match  escapes  such  as \w or \d.  However, if PCRE2 is built with UTF
1571        tively,  the  PCRE2_UCP  option  can be set when a pattern is compiled;
1575        The  use  of  locales  with Unicode is discouraged. If you are handling
1581        internal tables recognize only ASCII characters. However, when PCRE2 is
1582        built, it is possible to cause the internal tables to be rebuilt in the
1589        code, the need for this locale support is expected to die away.
1605        The  locale  name "fr_FR" is used on Linux and other Unix-like systems;
1606        if you are using Windows, the name for the French locale  is  "french".
1607        It  is the caller's responsibility to ensure that the memory containing
1608        the tables remains available for as long as it is needed.
1610        The pointer that is passed (via the compile context) to pcre2_compile()
1611        is  saved  with  the  compiled pattern, and the same tables are used by
1623        The first argument for pcre2_pattern_info() is a pointer  to  the  com-
1625        is required, and the third argument is  a  pointer  to  a  variable  to
1626        receive  the data. If the third argument is NULL, the first argument is
1628        that is required for the information requested. Otherwise, The yield of
1629        the function is zero for success, or one of the following negative num-
1635          PCRE2_ERROR_UNSET          the requested field is not set
1637        The  "magic  number" is placed at the start of each compiled pattern as
1638        an simple check against passing an arbitrary memory pointer. Here is  a
1646            PCRE2_INFO_SIZE,  /* what is required */
1661        For   example,   if  the  pattern  /(*UTF)abc/  is  compiled  with  the
1662        PCRE2_EXTENDED  option,  the  result   for   PCRE2_INFO_ALLOPTIONS   is
1668        A pattern compiled without PCRE2_ANCHORED is automatically anchored  by
1669        PCRE2 if the first significant item in every top-level branch is one of
1672          ^     unless PCRE2_MULTILINE is set
1677        When .* is the first significant item, anchoring is possible only  when
1680          .* is not in an atomic group
1681          .* is not in a capturing group that is the subject
1683          PCRE2_DOTALL is in force for .*
1685          PCRE2_NO_DOTSTAR_ANCHOR is not set.
1687        For  patterns  that are auto-anchored, the PCRE2_ANCHORED bit is set in
1697        capturing group is set in a conditional subpattern such as (?(3)a|b) is
1698        also a back reference. Zero is returned if there  are  no  back  refer-
1703        The output is a uint32_t whose value indicates what character sequences
1711        terns where (?| is not used, this is also the total number of capturing
1722        structed, a pointer to it is returned. Otherwise NULL is returned.  The
1729        variable.  If there is a fixed first value, for example, the letter "c"
1730        from a pattern such as (cat|cow|coyote), 1 is returned, and the charac-
1731        ter  value can be retrieved using PCRE2_INFO_FIRSTCODEUNIT. If there is
1732        no fixed first value, but it is known that a match can  occur  only  at
1733        the  start  of  the subject or following a newline in the subject, 2 is
1734        returned. Otherwise, and for anchored patterns, 0 is returned.
1741        library,  the  value is always less than 256. In the 16-bit library the
1755        variable.  An explicit match is either a literal CR or LF character, or
1760        Return 1 if the (?J) or (?-J) option setting is used  in  the  pattern,
1773        Returns  1 if there is a rightmost literal code unit that must exist in
1775        point  to  an  uint32_t  variable.  If  there  is  no  such value, 0 is
1776        returned. When 1 is  returned,  the  code  unit  value  itself  can  be
1778        literal value is recorded only if  it  follows  something  of  variable
1779        length.  For example, for the pattern /^a\d+z\d+/ the returned value is
1781        the returned value is 0.
1788        there is no such value, 0 is returned.
1794        contains recursive subroutine calls it is not always possible to deter-
1801        (*LIMIT_MATCH=nnnn)  at  the  start,  the  value is returned. The third
1810        unsigned 32-bit integer. This information is useful when  doing  multi-
1814        inspect the previous character. This is to ensure  that  at  least  one
1815        character  from  the old segment is retained when a new segment is pro-
1822        value is returned. Otherwise the returned value is 0. The  value  is  a
1825        variable.  The  value  is  a  lower bound to the length of any matching
1827        match, but every string that does match is at least that long.
1837        strings  by  name. It is also possible to extract the data directly, by
1840        do the conversion, you need to use the  name-to-number  map,  which  is
1849        This  is  a  PCRE2_SPTR  pointer to a block of code units. In the 8-bit
1855        The rest of the entry is the corresponding name, zero terminated.
1857        The  names are in alphabetical order. If (?| is used to create multiple
1860        the same name, but there is only one  entry  in  the  table.  Different
1864        but only if PCRE2_DUPNAMES is set. They appear  in  the  table  in  the
1866        this is the order of increasing number; when (?| is used  this  is  not
1871        is set, so white space - including newlines - is ignored):
1877        each entry in the table is eight bytes long. The table is  as  follows,
1887        name-to-number  map,  remember that the length of the entries is likely
1892        The output is a uint32_t with one of the following values:
1906        (*LIMIT_RECURSION=nnnn) at the start, the value is returned. The  third
1916        code units of the compiled pattern itself. The value that is used  when
1917        pcre2_compile()  is  getting memory in which to place the compiled pat-
1933        argument is a pointer to a compiled pattern, the  second  points  to  a
1934        callback  function,  and the third is arbitrary user data. The callback
1935        function is called for every callout in the pattern  in  the  order  in
1936        which they appear. Its first argument is a pointer to a callout enumer-
1937        ation block, and its second argument is the user_data  value  that  was
1945        It  is  possible  to  save  compiled patterns on disc or elsewhere, and
1961        Information about a successful or unsuccessful match  is  placed  in  a
1962        match  data  block,  which  is  an opaque structure that is accessed by
1965        subject and any substrings that were captured.  This  is  know  as  the
1970        tions  above.  For pcre2_match_data_create(), the first argument is the
1971        number of pairs of offsets in the  ovector.  One  pair  of  offsets  is
1975        three captured substrings. A minimum of at least 1 pair is  imposed  by
1976        pcre2_match_data_create(), so it is always possible to return the over-
1979        The second argument of pcre2_match_data_create() is a pointer to a gen-
1984        For  pcre2_match_data_create_from_pattern(),  the  first  argument is a
1985        pointer to a compiled pattern. The ovector is created to be exactly the
1987        ond argument is again a pointer to a general context, but in this  case
1988        if NULL is passed, the memory is obtained using the same allocator that
1997        When a call of pcre2_match() fails, valid  data  is  available  in  the
1998        match    block    only   when   the   error   is   PCRE2_ERROR_NOMATCH,
2000        string. Exactly what is available depends on the error, and is detailed
2003        When one of the matching functions is called, pointers to the  compiled
2010        When  a match data block itself is no longer needed, it should be freed
2021        The function pcre2_match() is called to match a subject string  against
2022        a  compiled pattern, which is passed in the code argument. You can call
2027        This function is the main matching facility  of  the  library,  and  it
2028        operates  in  a  Perl-like  manner. For specialist use there is also an
2029        alternative matching function, which is described below in the  section
2032        Here is an example of a simple call to pcre2_match():
2044        If  the  subject  string is zero-terminated, the length can be given as
2051        The subject string is passed to pcre2_match() as a pointer in  subject,
2053        and offset are in code units, not characters.  That  is,  they  are  in
2056        cessing is enabled.
2058        If startoffset is greater than the length of the subject, pcre2_match()
2059        returns PCRE2_ERROR_BADOFFSET. When the starting offset  is  zero,  the
2060        search  for a match starts at the beginning of the subject, and this is
2067        A non-zero starting offset is useful when searching for  another  match
2076        only  if  the  current position in the subject is not a word boundary.)
2078        finds  the first occurrence. If pcre2_match() is called again with just
2080        because \B is always false at the start of the subject, which is deemed
2081        to be a word boundary. However, if pcre2_match() is passed  the  entire
2083        rence of "iss" because it is able to look behind the starting point  to
2084        discover that it is preceded by a letter.
2086        Finding  all  the  matches  in a subject is tricky when the pattern can
2087        match an empty string. It is possible to emulate Perl's /g behaviour by
2091        again. There is some code that demonstrates  how  to  do  this  in  the
2094        so,  and the current character is CR followed by LF, advance the start-
2097        If a non-zero starting offset is passed when the pattern  is  anchored,
2098        one attempt to match at the given offset is made. This can only succeed
2108        action is described below.
2110        Setting  PCRE2_ANCHORED  at match time is not supported by the just-in-
2111        time (JIT) compiler. If it is set, JIT matching  is  disabled  and  the
2112        normal   interpretive   code   in  pcre2_match()  is  run.  Apart  from
2126        This option specifies that first character of the subject string is not
2134        This option specifies that the end of the subject string is not the end
2143        An empty string is not considered to be a valid match if this option is
2150        is  applied  to  a  string not beginning with "a" or "b", it matches an
2152        match  is  not valid, so pcre2_match() searches further into the string
2157        This is like PCRE2_NOTEMPTY, except that it locks out an  empty  string
2158        match only at the first matching position, that is, at the start of the
2160        subject  is  permitted.   If  the pattern is anchored, such a match can
2166        pcre2_jit_compile(),  JIT  is  automatically used when pcre2_match() is
2172        When PCRE2_UTF is set at compile time, the validity of the subject as a
2173        UTF string is checked by default  when  pcre2_match()  is  subsequently
2174        called.   If  a non-zero starting offset is given, the check is applied
2176        ing,  and there is a check that the starting offset points to the first
2184        The check is carried out before any other processing takes place, and a
2185        negative error code is returned if the check fails. There  are  several
2191        If you know that your subject is valid, and  you  want  to  skip  these
2197        NOTE: When PCRE2_NO_UTF_CHECK is set, the effect of passing an  invalid
2198        string  as a subject, or an invalid value of startoffset, is undefined.
2205        occurs  if  the  end of the subject string is reached successfully, but
2207        happens  when  PCRE2_PARTIAL_SOFT  (but not PCRE2_PARTIAL_HARD) is set,
2209        complete  match can be found is PCRE2_ERROR_PARTIAL returned instead of
2211        the  caller  is prepared to handle a partial match, but only if no com-
2214        If PCRE2_PARTIAL_HARD is set, it overrides PCRE2_PARTIAL_SOFT. In  this
2215        case,  if  a  partial match is found, pcre2_match() immediately returns
2217        other words, when PCRE2_PARTIAL_HARD is set, a partial match is consid-
2220        There is a more detailed discussion of partial and multi-segment match-
2226        When  PCRE2 is built, a default newline convention is set; this is usu-
2233        alter the way the match starting position is  advanced  after  a  match
2236        When PCRE2_NEWLINE_CRLF, PCRE2_NEWLINE_ANYCRLF, or PCRE2_NEWLINE_ANY is
2238        pattern fails when the current starting position is at a CRLF sequence,
2240        the  match  position  is  advanced by two characters instead of one, in
2243        The above rule is a compromise that makes the most common cases work as
2244        expected.  For  example,  if  the  pattern is .+A (and the PCRE2_DOTALL
2245        option is not set), it does not match the string "\r\nA" because, after
2251        An explicit match for CR of LF is either a literal appearance of one of
2257        is a valid newline sequence and explicit \r or \n escapes appear in the
2270        Friedl's book, this is called "capturing"  in  what  follows,  and  the
2271        phrase  "capturing subpattern" or "capturing group" is used for a frag-
2282        strings.  It  is  part  of  the  match  data   block.    The   function
2287        Within the ovector, the first in each pair of values is set to the off-
2288        set of the first code unit of a substring, and the second is set to the
2290        ues are always code unit offsets, not character offsets. That is,  they
2295        first  pair  of  offsets  (that is, ovector[0] and ovector[1]) are set.
2301        next  pair  is  used for the first capturing subpattern, and so on. The
2302        value returned by pcre2_match() is one more than the  highest  numbered
2304        tured, the returned value is 3. If there are no capturing  subpatterns,
2305        the return value from a successful match is 1, indicating that just the
2310        the match.  For example, if the pattern  (?=ab\K)  is  matched  against
2313        If  a  capturing subpattern group is matched repeatedly within a single
2314        match operation, it is the last portion of the subject that it  matched
2315        that is returned.
2317        If the ovector is too small to hold all the captured substring offsets,
2318        as much as possible is filled in, and the function returns a  value  of
2320        called with a match data block whose ovector is of minimum length (that
2321        is, one pair). However, if the pattern contains back references and the
2322        ovector is not big enough to remember the related substrings, PCRE2 has
2323        to  get  additional  memory for use during matching. Thus it is usually
2327        It  is  possible for capturing subpattern number n+1 to match some part
2329        if  the  string  "abc"  is  matched against the pattern (a|(z))(bc) the
2330        return from the function is 4, and subpatterns 1 and 3 are matched, but
2331        2  is  not.  When  this happens, both values in the offset pairs corre-
2336        "abc" is matched against the pattern (abc)(x(yz)?)? subpatterns 2 and 3
2337        are  not matched.  The return from the function is 2, because the high-
2338        est used capturing subpattern number is 1. The offsets for for the sec-
2339        ond  and  third  capturing  subpatterns  (assuming  the vector is large
2343        in the pattern are never changed. That is, if a pattern contains n cap-
2356        is  retained  in the match data block and can be retrieved by the above
2358        times, the result is undefined.
2363        zero-terminated name, which is within the compiled  pattern.  Otherwise
2364        NULL  is returned. The length of the (*MARK) name (excluding the termi-
2365        nating zero) is stored in the code unit that  preceeds  the  name.  You
2369        After a successful match, the (*MARK) name that is returned is the last
2371        match" or a  partial  match,  the  last  encountered  (*MARK)  name  is
2376        When  it  matches "bc", the returned mark is A. The B mark is "seen" in
2377        the first branch of the group, but it is not on the matching  path.  On
2379        mark is B.
2387        value is always the same as ovector[0] because \K does not  affect  the
2401        them.  The codes are given names in the header file. If UTF checking is
2402        in force and an invalid UTF subject string is detected, one of a number
2403        of  UTF-specific negative error codes is returned. Details are given in
2419        to  catch  the case when it is passed a junk pointer. This is the error
2420        that is returned when the magic number is not present.
2424        This error is given when a pattern  that  was  compiled  by  the  8-bit
2425        library  is  passed  to  a  16-bit  or 32-bit library function, or vice
2445        This  error  is never generated by pcre2_match() itself. It is provided
2457        This  error  is  returned  when a pattern that was successfully studied
2458        using JIT is being matched, but the matching mode (partial or  complete
2460        fast path function is used, this error may be also  given  for  invalid
2465        This  error  is  returned  when a pattern that was successfully studied
2466        using JIT is being matched, but the memory available for  the  just-in-
2467        time  processing stack is not large enough. See the pcre2jit documenta-
2476        If a pattern contains back references,  but  the  ovector  is  not  big
2479        other  special cases where extra memory is needed during matching. This
2480        error is given when memory cannot be obtained.
2488        This error is returned when  pcre2_match()  detects  a  recursion  loop
2494        subpatterns, cannot be detected until matching is attempted.
2508        sage(). The code is passed as the first argument,  with  the  remaining
2510        the text message is placed. Note that the message is returned  in  code
2511        units of the appropriate width for the library that is being used.
2513        The  returned message is terminated with a trailing zero, and the func-
2515        zero.  If  the  error  number  is  unknown,  the  negative  error  code
2516        PCRE2_ERROR_BADDATA is returned. If the buffer is too small,  the  mes-
2517        sage  is  truncated  (but still with a trailing zero), and the negative
2518        error code PCRE2_ERROR_NOMEMORY is returned.  None of the messages  are
2519        very long; a buffer size of 120 code units is ample.
2540        strings. A substring that contains a binary zero is correctly extracted
2541        and  has  a  further  zero  added on the end, but the result is not, of
2547        match,  only  substring  zero  is  available. An attempt to extract any
2553        the  match.   For  example,  if the pattern (?=ab\K) is matched against
2560        argument is a pointer to the match data block, the second is the  group
2561        number,  and the third is a pointer to a variable into which the length
2562        is placed. If you just want to know whether or not  the  substring  has
2574        units.  This is updated to contain the actual number of code units used
2580        terminating zero. When the substring is no longer  needed,  the  memory
2583        The  return  value  from  all these functions is zero for success, or a
2585        code  is  returned.   If  a  substring number greater than zero is used
2586        after a partial match, PCRE2_ERROR_PARTIAL is returned. Other  possible
2596        There is no substring with that number in the  pattern,  that  is,  the
2597        number is greater than the number of capturing parentheses.
2602        the pattern, is greater than the number of slots in the ovector, so the
2608        pattern is (abc)|(def) and the subject is "def", and the  ovector  con-
2609        tains at least two capturing slots, substring number 1 is unset.
2622        excluding a terminating zero that is added to each of them. All this is
2623        done in a single block of memory that is obtained using the same memory
2627        after a partial match, the error code PCRE2_ERROR_PARTIAL is returned.
2629        The  address of the memory block is returned via listptr, which is also
2630        the start of the list of string pointers. The end of the list is marked
2631        by  a  NULL pointer. The address of the list of lengths is returned via
2635        function  is zero if all went well, or PCRE2_ERROR_NOMEMORY if the mem-
2636        ory block could not be obtained. When the list is no longer needed,  it
2639        If this function encounters a substring that is unset, which can happen
2669        the number of the subpattern called "xxx" is 2. If the name is known to
2672        ment  is the compiled pattern, and the second is the name. The yield of
2673        the function is the subpattern number, PCRE2_ERROR_NOSUBSTRING if there
2674        is  no  subpattern  of  that  name, or PCRE2_ERROR_NOUNIQUESUBSTRING if
2675        there is more than one subpattern of that name. Given the  number,  you
2681        argument is a name instead of a number. If PCRE2_DUPNAMES  is  set  and
2683        given name, and return the first named string that is set.
2685        If there are no groups with the given name, PCRE2_ERROR_NOSUBSTRING  is
2687        than the number of slots in  the  ovector,  PCRE2_ERROR_UNAVAILABLE  is
2688        returned.  If  there  is at least one group with a slot in the ovector,
2689        but no group is found to be set, PCRE2_ERROR_UNSET is returned.
2711        replacement string, whose length is supplied in rlength.  This  can  be
2719        block is obtained and freed within this function, using memory  manage-
2724        length,  in  code  units, of the output buffer. If the function is suc-
2725        cessful, the value is updated to contain the length of the new  string,
2726        excluding the trailing zero that is automatically added.
2728        If  the  function  is  not  successful,  the value set via outlengthptr
2730        string,  the  value  is  the offset in the replacement string where the
2731        error was detected. For other  errors,  the  value  is  PCRE2_UNSET  by
2733        unless PCRE2_SUBSTITUTE_OVERFLOW_LENGTH is set (see  below),  in  which
2734        case  the  value  is the minimum length needed, including space for the
2738        also that the length is in code units, not bytes.
2740        In  the replacement string, which is interpreted as a UTF string in UTF
2741        mode, and is checked for UTF  validity  unless  the  PCRE2_NO_UTF_CHECK
2742        option is set, a dollar character is an escape character that can spec-
2753        the entire matched string.   For  example,  if  the  pattern  a(b)c  is
2755        is "=+babcb+=".
2768        string,  replacing  every  matching substring. If this is not set, only
2769        the first matching substring is replaced. If any matched substring  has
2771        non-empty match at the same position is performed. If this is not  suc-
2772        cessful,  the current position is advanced by one character except when
2773        CRLF is a valid newline sequence and the next two  characters  are  CR,
2774        LF. In this case, the current position is advanced by two characters.
2777        buffer is too small. The default action is to return PCRE2_ERROR_NOMEM-
2778        ORY  immediately.  If  this  option is set, however, pcre2_substitute()
2781        fer that is needed. This value is  passed  back  via  the  outlengthptr
2785        Passing a buffer size of zero is a permitted way  of  finding  out  how
2786        much  memory  is needed for given substitution. However, this does mean
2787        that the entire operation is carried out twice. Depending on the appli-
2799        unknown  groups  when  PCRE2_SUBSTITUTE_UNKNOWN_UNSET  is  set)  to  be
2801        option is not set, an attempt to  insert  an  unset  group  causes  the
2806        replacement  string.  Without this option, only the dollar character is
2808        When PCRE2_SUBSTITUTE_EXTENDED is set, two things change:
2810        Firstly,  backslash in a replacement string is interpreted as an escape
2822        it  is  a  letter)  to  upper or lower case, respectively, and then the
2828        ple,  the  result of processing "\Uaa\LBB\Ecc\E" is "AAbbcc"; the final
2831        The second effect of setting PCRE2_SUBSTITUTE_EXTENDED is to  add  more
2832        flexibility  to  group substitution. The syntax is similar to that used
2839        fies  a  default  value. If group <n> is set, its value is inserted; if
2840        not, <string> is expanded and the  result  inserted.  The  second  form
2841        specifies  strings that are expanded and inserted when group <n> is set
2842        or unset, respectively. The first form is just a  convenient  shorthand
2863        that were made. This may be zero if no matches were found, and is never
2864        greater than 1 unless PCRE2_SUBSTITUTE_GLOBAL is set.
2866        In the event of an error, a negative error code is returned. Except for
2867        PCRE2_ERROR_NOMATCH    (which   is   never   returned),   errors   from
2870        PCRE2_ERROR_NOSUBSTRING is returned for a non-existent substring inser-
2871        tion, unless PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set.
2873        PCRE2_ERROR_UNSET is returned for an unset substring insertion (includ-
2874        ing an unknown substring when  PCRE2_SUBSTITUTE_UNKNOWN_UNSET  is  set)
2875        when  the  simple  (non-extended)  syntax  is  used  and  PCRE2_SUBSTI-
2876        TUTE_UNSET_EMPTY is not set.
2878        PCRE2_ERROR_NOMEMORY is returned  if  the  output  buffer  is  not  big
2879        enough. If the PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option is set, the size
2880        of buffer that is needed is returned via outlengthptr. Note  that  this
2883        PCRE2_ERROR_BADREPLACEMENT  is  used for miscellaneous syntax errors in
2888        (the pattern match ended before it started, which can happen if  \K  is
2901        When  a  pattern  is compiled with the PCRE2_DUPNAMES option, names for
2908        only one of the named subpatterns participates. An example is shown  in
2913        to   the   given   name   that   is  set.  Only  if  none  are  set  is
2914        PCRE2_ERROR_UNSET is returned.  The  pcre2_substring_number_from_name()
2920        first argument is the compiled pattern, and the second is the name.  If
2928        units. In both cases, PCRE2_ERROR_NOSUBSTRING is returned if there  are
2931        The format of the name table is described above in the section entitled
2945        is described in the pcre2callout documentation.
2947        What you have to do is to insert a callout right at the end of the pat-
2948        tern.   When your callout function is called, extract and save the cur-
2962        The function pcre2_dfa_match() is called  to  match  a  subject  string
2965        characteristics  to  the  normal  algorithm, and is not compatible with
2974        is used in a different way, and this is described below. The other com-
2976        description is not repeated here.
2979        workspace  vector  should  contain at least 20 elements. It is used for
2981        workspace  is needed for patterns and subjects where there are a lot of
2984        Here is an example of a simple call to pcre2_dfa_match():
3007        is not repeated here.
3013        the  details are slightly different. When PCRE2_PARTIAL_HARD is set for
3015        subject is reached and there is still at least one matching possibility
3017        matches  have  already  been found. When PCRE2_PARTIAL_SOFT is set, the
3018        return code PCRE2_ERROR_NOMATCH is converted  into  PCRE2_ERROR_PARTIAL
3019        if  the  end  of  the  subject  is reached, there have been no complete
3020        matches, but there is still at least one matching possibility. The por-
3022        was found is set as the first matching string in both cases. There is a
3030        tive algorithm works, this is necessarily the shortest  possible  match
3035        When  pcre2_dfa_match() returns a partial match, it is possible to call
3038        it is set, the workspace and wscount options must  reference  the  same
3039        vector  as  before  because data about the match so far is left in them
3040        after a partial match. There is more discussion of this facility in the
3053        is matched against the string
3055          This is <something> <something else> <something further> no more
3063        On  success,  the  yield of the function is a number greater than zero,
3064        which is the number of matched substrings.  The  offsets  of  the  sub-
3078        The ovector is not big enough to include a slot for the given substring
3083        There  is  a  slot  in  the  ovector for this substring, but there were
3087        length;  that  is,  the longest matching string is first. If there were
3088        too many matches to fit into the ovector, the yield of the function  is
3089        zero, and the vector is filled with the longest matches.
3093        example,  the pattern "a\d+" is compiled as if it were "a\d++". For DFA
3094        matching, this means that only one possible  match  is  found.  If  you
3108        This return is given if pcre2_dfa_match() encounters  an  item  in  the
3114        This return is given if pcre2_dfa_match() encounters a  condition  item
3120        This return is given if pcre2_dfa_match() runs  out  of  space  in  the
3125        When  a  recursive subpattern is processed, the matching function calls
3127        This  error  is given if the internal ovector is not large enough. This
3128        should be extremely rare, as a vector of size 1000 is used.
3132        When pcre2_dfa_match() is called  with  the  PCRE2_DFA_RESTART  option,
3135        these checks fail, this error is given.
3168        PCRE2  is distributed with a configure script that can be used to build
3172        information  about  building  with Autotools (some of which is repeated
3174        systems.  There  is a lot more information about building PCRE2 without
3184        can be selected when the library is compiled. It  assumes  use  of  the
3206        is not described.
3211        By default, a library called libpcre2-8 is built, containing  functions
3228        the POSIX wrapper is for the 8-bit library only, and that pcre2grep  is
3247        By default, PCRE2 is built with support for Unicode and  UTF  character
3253        It is not possible to build  one  library  with  Unicode  support,  and
3281        option when calling pcre2_compile(). There is also a build-time option
3290        Just-in-time compiler support is included in the build by specifying
3294        This  support  is available only for certain hardware architectures. If
3295        this option is set for an unsupported architecture,  a  building  error
3297        When JIT support is enabled, pcre2grep automatically makes use  of  it,
3308        the end of a line. This is the normal newline  character  on  Unix-like
3312          --enable-newline-is-cr
3314        to the configure  command.  There  is  also  an  --enable-newline-is-lf
3321          --enable-newline-is-crlf
3323        to the configure command. There is a fourth option, specified by
3325          --enable-newline-is-anycrlf
3330          --enable-newline-is-any
3338        Whatever default line ending convention is selected when PCRE2 is built
3340        it is conventional to use the standard for your operating system.
3351        the default is changed so that \R matches only CR, LF, or  CRLF.  What-
3352        ever  is selected when PCRE2 is built can be overridden by applications
3362        for a compiled pattern of around 64K code units. This is sufficient  to
3364        want to process truly enormous patterns, so it is possible  to  compile
3371        16-bit  library,  a  value of 3 is rounded up to 4. In these libraries,
3374        value is always 4 and cannot be overridden; the value  of  --with-link-
3375        size is ignored.
3382        match().  In  environments where the size of the stack is limited, this
3385        increase  the  maximum  stack  size.  There  is  a  discussion  in  the
3395        free() are called to manage the heap memory that is required, but  cus-
3398        the pcre2_match() function; it is not relevant for pcre2_dfa_match().
3409        tation.  The default is 10 million, but this can be changed by adding a
3417        In  some  environments  it is desirable to limit the depth of recursive
3420        for-recursion is specified) that is used. A second limit controls this;
3421        it  defaults  to  the  value  that is set for --with-match-limit, which
3434        less than 256. By default, PCRE2 is built with a set of tables that are
3441        Instead, a program called dftables is compiled and  run.  This  outputs
3444        if  you are cross compiling, because dftables is run on the local host.
3452        character code is ASCII or Unicode, which is a superset of ASCII.  This
3453        is the case for most computer operating systems. PCRE2 can, however, be
3462        It is not possible to support both EBCDIC and UTF-8 codes in  the  same
3466        The EBCDIC character that corresponds to an ASCII LF is assumed to have
3468        is used. In such an environment you should use
3474        0x25 is not chosen as LF is made to correspond to the Unicode NEL char-
3475        acter (which, in Unicode, is 0x85).
3477        The options that select newline behaviour, such as --enable-newline-is-
3485        outs with string arguments within the patterns it is matching, in order
3507        pcre2grep  uses an internal buffer to hold a "window" on the file it is
3509        it  finds  a match. The size of the buffer is controlled by a parameter
3510        whose default value is 20K. The buffer itself is three times this size,
3511        but because of the way it is used for holding "before" lines, the long-
3512        est line that is guaranteed to be processable is  the  parameter  size.
3528        to the configure command, pcre2test  is  linked  with  the  libreadline
3529        orlibedit library, respectively, and when its input is from a terminal,
3531        and  history  facilities.  Note that libreadline is GPL-licensed, so if
3538        sytem-installed readline library this is sufficient. However,  in  some
3539        environments (e.g. if an unmodified distribution version of readline is
3548        is automatically included, you may need to add something like
3561        to the configure command, additional debugging code is included in  the
3562        build. This feature is intended for use by the PCRE2 maintainers.
3573        invalid  memory  accesses,  and  is  mostly  useful for debugging PCRE2
3579        If your C compiler is gcc, you can build a version of  PCRE2  that  can
3587        Note that using ccache (a caching C compiler) is incompatible with code
3593        before running make to build PCRE2, so that ccache is not used.
3595        When --enable-coverage is used,  the  following  addition  targets  are
3600        This  creates  a  fresh coverage report for the PCRE2 test suite. It is
3672        PCRE2  provides  a feature called "callout", which is a means of tempo-
3679        external function is to be called.  Different  callout  points  can  be
3681        default value is zero.  Alternatively, the argument may be a  delimited
3683        ending delimiter is the same as the start, except for {, where the end-
3684        ing  delimiter  is  }.  If  the  ending  delimiter is needed within the
3690        If the PCRE2_AUTO_CALLOUT option bit is set when a pattern is compiled,
3692        item  in  the  pattern. For example, if PCRE2_AUTO_CALLOUT is used with
3697        it is processed as if it were
3701        Notice that there is a callout before and after  each  parenthesis  and
3703        dition is an assertion, an automatic callout  is  inserted  immediately
3715        pcre2test indicates how the pattern is being matched.  This  is  useful
3729        that  what follows cannot be part of the repeat. For example, a+[bc] is
3731        is compiled with PCRE2_ANCHORED and PCRE2_AUTO_CALLOUT and then applied
3732        to the string "aaaa" is:
3739        This indicates that when matching [bc] fails, there is no  backtracking
3758        By default, an optimization is applied when .* is the first significant
3759        item in a pattern. If PCRE2_DOTALL is set, so that the  dot  can  match
3760        any  character,  the pattern is automatically anchored. If PCRE2_DOTALL
3761        is not set, a match can start only after an internal newline or at  the
3763        optimization is disabled, however, if .* is in an atomic  group  or  if
3764        there  is  a back reference to the capturing group in which it appears.
3765        It is also disabled if the pattern contains (*PRUNE) or  (*SKIP).  How-
3768        For  example,  if  the pattern .*\d is compiled with PCRE2_AUTO_CALLOUT
3769        and applied to the string "aa", the pcre2test output is:
3779        ject.  In  other  words,  the pattern is anchored. You can disable this
3796        there is no subsequent attempt to match with an empty subject.
3804        callouts.  For example, if the pattern is
3809        the  subject  string  is  "abyz",  the  lack of "d" means that matching
3810        doesn't ever start, and the callout is  never  reached.  However,  with
3811        "abyd", though the result is still no match, the callout is obeyed.
3815        if  the  subject is not long enough, or, for unanchored patterns, if it
3827        function is set in the match context, it is  called.  This  applies  to
3829        tion is a pointer to a pcre2_callout block. The second argument is  the
3851        current version is 1; the three callout string fields  were  added  for
3855        future if more fields are added, but the intention is never  to  remove
3860        For  a  numerical  callout,  callout_string is NULL, and callout_number
3861        contains the number of the callout, in the range  0-255.  This  is  the
3862        number  that  follows  (?C for manual callouts; it is 255 for automati-
3867        For callouts with string arguments, callout_number is always zero,  and
3868        callout_string  points  to the string that is contained within the com-
3869        piled pattern. Its length is given by callout_string_length. Duplicated
3871        been turned into single characters, but there is no other processing of
3873        zero is present after the string, but is not included  in  the  length.
3874        The  delimiter  that was used to start the string is also stored within
3878        The callout_string_offset field is the code unit offset to the start of
3879        the callout argument string within the original pattern string. This is
3888        The offset_vector field is a pointer to the vector of capturing offsets
3890        data  block.  When pcre2_match() is used, the contents can be inspected
3893        the DFA matching function, this field is not useful.
3900        sequence  \K has been encountered, this value is changed to reflect the
3901        modified starting point. If the pattern is not  anchored,  the  callout
3908        When the pcre2_match() is used, the capture_top field contains one more
3910        no substrings have been captured, the value of capture_top is one. This
3911        is always the case when the DFA functions are used, because they do not
3918        ture_last is 0. This is always the case for the DFA matching functions.
3926        length  is  zero. When the callout precedes an opening parenthesis, the
3927        length is that of the entire subpattern.
3946        is zero, matching proceeds as normal. If  the  value  is  greater  than
3949        failed. If the value is less than zero, the match is abandoned, and the
3954        standard "no match" failure. The error  number  PCRE2_ERROR_CALLOUT  is
3968        argument  is  a  pointer  to a compiled pattern, the second points to a
3969        callback function, and the third is arbitrary user data.  The  callback
3970        function  is  called  for  every callout in the pattern in the order in
3971        which they appear. Its first argument is a pointer to a callout enumer-
3972        ation  block,  and  its second argument is the user_data value that was
3982          callout_string         Points to callout string or is NULL
3984        The  version  number is currently 0. It will increase if new fields are
3986        namesakes  in  the pcre2_callout block that is used for callouts during
3989        Note that the value of pattern_position is  unique  for  each  callout.
3990        However,  if  a callout occurs inside a group that is quantified with a
3991        non-zero minimum or a fixed maximum, the group is replicated inside the
3992        compiled  pattern.  For example, a pattern such as /(a){2}/ is compiled
3998        zero value, scanning the pattern stops, and that value is returned from
4035        that  the  next  character  is not "a" three times (in principle: PCRE2
4047        its own, matching a non-newline character, is supported.) In fact these
4050        an error is generated by default. However, if the PCRE2_ALT_BSUX option
4051        is set, \U and \u are interpreted as ECMAScript interprets them.
4054        is built with Unicode support. The properties that can be  tested  with
4060        there is no need to implement the  somewhat  messy  concept  of  surro-
4064        acters in between are treated as literals. This is  slightly  different
4076        The  \Q...\E  sequence  is recognized both inside and outside character
4080        (??{code})  constructions. However, there is support for recursive pat-
4081        terns. This is not available in Perl 5.8, but it is in Perl 5.10. Also,
4087        groups.  Atomic recursion is like Python,  but  unlike  Perl.  Captured
4089        inside in PCRE2, but not in Perl. There is a discussion  that  explains
4094        that  is  called  as  a  subroutine (whether or not recursively), their
4095        effect is confined to that subpattern; it does not extend to  the  sur-
4096        rounding  pattern.  This is not always the case in Perl. In particular,
4097        if (*THEN) is present in a group that is called as  a  subroutine,  its
4098        action is limited to that group, even if the group does not contain any
4103        first one that is backtracked onto acts. For example,  in  the  pattern
4105        in C triggers (*PRUNE). Perl's behaviour is more complex; in many cases
4106        it is the same as PCRE2, but there are examples where it differs.
4112        captured  strings  when  part  of  a  pattern is repeated. For example,
4114        unset, but in PCRE2 it is set to "b".
4117        pattern names is not as general as Perl's. This is a consequence of the
4121        the same number but different names, is not supported,  and  causes  an
4125        is given at compile time.
4129        modifier is set, Perl allows white space between ( and ?  (though  cur-
4130        rent  Perls warn that this is deprecated) but PCRE2 never does, even if
4131        the PCRE2_EXTENDED option is set.
4139        not affected when case-independent matching is specified. For  example,
4142        \p{Ll} match all letters, regardless of case, when case independence is
4148        in PCRE2 for some time. This list is with respect to Perl 5.10:
4155        (b) If PCRE2_DOLLAR_ENDONLY is set and PCRE2_MULTILINE is not set,  the
4158        (c)  A  backslash  followed  by  a  letter  with  no special meaning is
4161        (d) If PCRE2_UNGREEDY is set, the greediness of the repetition  quanti-
4162        fiers is inverted, that is, by default they are not greedy, but if fol-
4175        (h) The callout facility is PCRE2-specific.
4177        (i) The partial matching facility is PCRE2-specific.
4180        different way and is not Perl-compatible.
4210        Just-in-time  compiling  is a heavyweight optimization that can greatly
4212        cessing  before  the  match is performed, so it is of most benefit when
4213        the same pattern is going to be matched many times. This does not  nec-
4214        essarily  mean many calls of a matching function; if the pattern is not
4217        string is very long, it may still pay  to  use  JIT  even  for  one-off
4218        matches.  JIT  support  is  available  for all of the 8-bit, 16-bit and
4222        function.   It  does  not apply when the DFA matching function is being
4228        JIT support is an optional feature of  PCRE2.  The  "configure"  option
4229        --enable-jit  (or  equivalent  CMake  option) must be set when PCRE2 is
4230        built if you want to use JIT. The support is limited to  the  following
4240        If --enable-jit is set on an unsupported platform, compilation fails.
4242        A  program  can  tell if JIT support is available by calling pcre2_con-
4243        fig() with the PCRE2_CONFIG_JIT option. The result is  1  when  JIT  is
4245        check this in order to use JIT. The API is implemented in  a  way  that
4246        falls  back  to the interpretive code if JIT is not available. For pro-
4247        grams that need the best possible performance, there is  also  a  "fast
4248        path" API that is JIT-specific.
4254        is to call pcre2_jit_compile() after successfully compiling  a  pattern
4255        with pcre2_compile(). This function has two arguments: the first is the
4257        second  is  zero  or  more of the following option bits: PCRE2_JIT_COM-
4260        If JIT support is not available, a  call  to  pcre2_jit_compile()  does
4262        pattern is passed to the JIT compiler, which turns it into machine code
4265        is zero on success, or a negative error code.
4267        There  is  a limit to the size of pattern that JIT supports, imposed by
4270        optimizations are introduced.  If a pattern  is  too  big,  a  call  to
4279        pcre2_match()  is  called,  the appropriate code is run if it is avail-
4280        able. Otherwise, the pattern is matched using interpretive code.
4288        ing. If pcre2_jit_compile() is called with no option bits set, it imme-
4289        diately returns zero. This is an alternative way of testing whether JIT
4290        is available.
4292        At present, it is not possible to free JIT compiled  code  except  when
4293        the entire compiled pattern is freed by calling pcre2_code_free().
4306        stack. Such a callback function is called whenever JIT code is about to
4308        the callback function is not obeyed.
4310        If the JIT compiler finds an unsupported item, no JIT  data  is  gener-
4311        ated.  You  can find out if JIT matching is available after compiling a
4314        result of 0 means that JIT support is not available, or the pattern was
4324        PCRE2_ANCHORED option is not supported at match time.
4326        If  the  PCRE2_NO_JIT option is passed to pcre2_match() it disables the
4336        When a pattern is matched using JIT matching, the return values are the
4342        The error code PCRE2_ERROR_MATCHLIMIT is returned by the  JIT  code  if
4343        searching  a  very large pattern tree goes on for too long, as it is in
4344        the same circumstance when JIT is not used, but the details of  exactly
4345        what  is counted are not the same. The PCRE2_ERROR_RECURSIONLIMIT error
4346        code is never returned when JIT matching is used.
4354        PCRE2_ERROR_JIT_STACKLIMIT  is  given  when  there is not enough stack.
4356        JIT  stacks. There is further discussion about the use of JIT stacks in
4363        NULL if there is an error. The pcre2_jit_stack_free() function is  used
4364        to  free a stack that is no longer needed. (For the technically minded:
4365        the address space is allocated by mmap or VirtualAlloc.)
4378        The first argument is a pointer to a match context. When this is subse-
4380        JIT  stack  is  used. There are three cases for the values of the other
4383          (1) If callback is NULL and data is NULL, an internal 32K block
4384              on the machine stack is used. This is the default when a match
4385              context is created.
4387          (2) If callback is NULL and data is not NULL, data must be
4391          (3) If callback is not NULL, it must point to a function that is
4394              function is NULL, the internal 32K stack is used; otherwise the
4398        A callback function is obeyed whenever JIT code is about to be run;  it
4399        is not obeyed when pcre2_match() is called with options that are incom-
4407        up  non-sequential matches in one thread is to use callouts: if a call-
4412        you assign or pass back NULL from  a  callback,  that  is  thread-safe,
4415        each thread so that the application is thread-safe.
4417        Strictly  speaking,  even more is allowed. You can assign the same non-
4418        NULL stack to a match context that is used by any number  of  patterns,
4422        is available for use. However, this is an inefficient solution, and not
4425        This  is a suggestion for how a multithreaded program that needs to set
4437        All the functions described in this section do nothing if  JIT  is  not
4445        PCRE2 (and JIT) is a recursive, depth-first engine, so it needs a stack
4446        where the local data of the current node is pushed before checking  its
4447        child nodes.  Allocating real machine stack on some platforms is diffi-
4449        extend  the  stack  on  PowerPC.  Although it is possible, its updating
4457        moving memory data (this is important because of pointers). Thus we can
4459        4K)  if  that is enough. However, we can still grow up to 1M anytime if
4464        The owner of the stack is the user program, not the JIT studied pattern
4465        or anything else. The user program must ensure that if a stack is being
4466        used by pcre2_match(), (that is, it is assigned to a match context that
4467        is  passed  to  the  pattern currently running), that stack must not be
4469        The best practice for multithreaded programs is to allocate a stack for
4476        a pointer is set. There is no reference counting or  any  other  magic.
4481        also  replace the stack in a context at any time when it is not in use.
4487        No,  because  this  is  too  costly in terms of resources. However, you
4488        could implement some clever idea which release the stack if it  is  not
4492        (6) OK, the stack is for long term memory allocation. But what  happens
4493        if  a pattern causes stack overflow with a stack of 1M? Is that 1M kept
4494        until the stack is freed?
4497        ory  sometimes  without  freeing the stack. There is no API for this at
4502        (7) This is too much of a headache. Isn't there any better solution for
4513        The JIT executable allocator does not free all memory when it is possi-
4517        calling pcre2_jit_free_unused_memory(). Its argument is a general  con-
4524        This is a single-threaded example that specifies a  JIT  stack  without
4553        JIT  is  not  available, it is convenient for programs that are written
4556        for use where JIT is known to be available, and  which  need  the  best
4561        The  fast  path  function  is  called  pcre2_jit_match(),  and it takes
4564        complete) is requested that was not compiled. Unsupported  option  bits
4565        (for  example,  PCRE2_ANCHORED)  are  ignored,  as  is the PCRE2_NO_JIT
4570        ple, if the subject pointer is NULL, an immediate error is given. Also,
4571        unless  PCRE2_NO_UTF_CHECK  is  set, a UTF subject string is tested for
4573        JIT fast path, and if invalid data is passed, the result is undefined.
4607        There are some size limitations in PCRE2 but it is hoped that they will
4610        The maximum size of a compiled pattern is approximately 64K code  units
4611        for  the  8-bit  and  16-bit  libraries  if  PCRE2 is compiled with the
4612        default internal linkage size, which is 2 bytes for these libraries. If
4615        ing  the  16-bit library, 3 is rounded up to 4). See the README file in
4617        In  these  cases the limit is substantially larger.  However, the speed
4618        of execution is slower. In the 32-bit  library,  the  internal  linkage
4619        size is always 4.
4621        The maximum length of a source pattern string is essentially unlimited;
4622        it is the largest number a PCRE2_SIZE variable can hold.  However,  the
4625        The maximum length (in code units) of a subject string is one less than
4626        the largest number a PCRE2_SIZE variable can  hold.  PCRE2_SIZE  is  an
4628        (that is ~(PCRE2_SIZE)0) is reserved as a special indicator  for  zero-
4639        The maximum length of a lookbehind assertion is 65535 characters.
4641        There is no limit to the number of parenthesized subpatterns, but there
4642        can be no more than 65535 capturing subpatterns. There is,  however,  a
4644        kinds. This is imposed in order to limit the  amount  of  system  stack
4645        used  at  compile time. The limit can be specified when PCRE2 is built;
4646        the default is 250.
4648        There is a limit to the number of forward references to subsequent sub-
4650        upper limits, for example, (?2){0,100} when subpattern number 2  is  to
4651        the  right,  are included in the count. There is no limit to the number
4654        The maximum length of name for a named subpattern is 32 code units, and
4655        the maximum number of named subpatterns is 10000.
4658        (*THEN) verb is 255 for the 8-bit library and 65535 for the 16-bit  and
4687        subject  string.  The  "standard"  algorithm is the one provided by the
4690        in-time (JIT) optimization that is described in the pcre2jit documenta-
4691        tion is compatible with this function.
4693        An alternative algorithm is provided by the pcre2_dfa_match() function;
4694        it operates in a different way, and is not Perl-compatible. This alter-
4698        When there is only one possible way in which a given subject string can
4705        is matched against the string
4717        makes the tree of infinite size, but it is still a tree.  Matching  the
4727        sions",  the  standard  algorithm  is an "NFA algorithm". It conducts a
4728        depth-first search of the pattern tree. That is, it  proceeds  along  a
4729        single path through the tree, checking that the subject matches what is
4730        required. When there is a mismatch, the algorithm  tries  any  alterna-
4735        branches  are  tried  is controlled by the greedy or ungreedy nature of
4738        If a leaf node is reached, a matching string has  been  found,  and  at
4739        that  point the algorithm stops. Thus, if there is more than one possi-
4741        this  is the shortest, the longest, or some intermediate length depends
4745        Because  it  ends  up  with a single path through the tree, it is rela-
4757        matches. In Friedl's terminology, this is a kind  of  "DFA  algorithm",
4758        though  it is not implemented as a traditional finite state machine (it
4761        Although the general principle of this matching algorithm  is  that  it
4762        scans  the subject string only once, without backtracking, there is one
4763        exception: when a lookaround assertion is encountered,  the  characters
4767        The scan continues until either the end of the subject is  reached,  or
4770        match  has  failed).   Thus,  if there is more than one possible match,
4772        est.  The  matches are returned in decreasing order of length. There is
4773        an option to stop the algorithm after the first match (which is  neces-
4774        sarily the shortest) is found.
4781        is matched against the string "the caterpillar catchment",  the  result
4782        is  the  three  strings "caterpillar", "cater", and "cat" that start at
4788        ple, the pattern "a\d+" is compiled as if it were "a\d++" because there
4789        is no point even considering the possibility of backtracking  into  the
4791        match is found. If you really do want multiple matches in  such  cases,
4800        ungreedy  nature  of  repetition quantifiers is not relevant (though it
4804        could  also  match  what  is  quantified, for example in a pattern like
4810        a  non-possessive quantifier. Similarly, if an atomic group is present,
4811        it is matched as if it were a standalone pattern at the current  point,
4812        and  the  longest match is then "locked in" for the rest of the overall
4816        is  not  straightforward  to  keep track of captured substrings for the
4830        be  on  some  paths  and not on others), is not supported. It causes an
4833        6. Callouts are supported, but the value of the  capture_top  field  is
4834        always 1, and the value of the capture_last field is always 0.
4837        matches a single code unit, even in a UTF mode,  is  not  supported  in
4843        are not supported. (*FAIL) is supported, and  behaves  like  a  failing
4853        ically  found,  and  in particular, the longest match is found. To find
4858        once, and never needs to backtrack (except for lookbehinds), it is pos-
4860        several pieces, checking for partial matching each time. Although it is
4862        rithm, by retaining partially matched substrings, it  is  more  compli-
4871        1. It is substantially slower than  the  standard  algorithm.  This  is
4872        partly  because  it has to search for all possible matches, but is also
4873        because it is less susceptible to optimization.
4904        In  normal  use  of  PCRE2,  if  the subject string that is passed to a
4905        matching function matches as far as it goes, but is too short to  match
4906        the  entire pattern, PCRE2_ERROR_NOMATCH is returned. There are circum-
4908        cases in which there is no match.
4910        Consider, for example, an application where a human is required to type
4917        that what has been typed so far is potentially valid,  it  is  able  to
4918        raise  an  error  as  soon  as  a  mistake  is made, by beeping and not
4920        ate  feedback is likely to be a better user interface than a check that
4921        is delayed until the entire string has been entered.  Partial  matching
4922        can  also be useful when the subject string is very long and is not all
4927        function.  The difference between the two options is whether or  not  a
4928        partial match is preferred to an alternative complete match, though the
4940        been compiled, interpretive matching code is used.
4944        and abandons matching immediately if it is not present in  the  subject
4948        shorter strings. This optimization is also disabled for partial  match-
4955        the subject string is reached successfully, but  matching  cannot  con-
4965        When a partial match is returned, the first two elements in the ovector
4972        If it is matched against "456abc123xyz" the result is a complete match,
4974        the  "start  of  match" point. However, if a partial match is requested
4975        and the subject string is "456abc12", a partial match is found for  the
4979        What happens when a partial match is identified depends on which of the
4984        If  PCRE2_PARTIAL_SOFT  is  set when pcre2_match() identifies a partial
4985        match, the partial match is remembered, but matching continues as  nor-
4987        match  can  be  found,  PCRE2_ERROR_PARTIAL  is  returned  instead   of
4990        This  option  is "soft" because it prefers a complete match over a par-
4992        the  subject string is potentially complete. For example, \z, \Z, and $
4994        of the subject is treated as a non-alphanumeric.
4996        If  there  is more than one partial match, the first one that was found
4997        provides the data that is returned. Consider this pattern:
5001        If this is matched against the subject string "abc123dog", both  alter-
5002        natives  fail  to  match,  but the end of the subject is reached during
5003        matching, so PCRE2_ERROR_PARTIAL is returned. The offsets are set to  3
5010        If  PCRE2_PARTIAL_HARD is set for pcre2_match(), PCRE2_ERROR_PARTIAL is
5011        returned as soon as a partial match is  found,  without  continuing  to
5012        search  for possible complete matches. This option is "hard" because it
5014        reason,  the  assumption  is  made that the end of the supplied subject
5017        is PCRE2_ERROR_PARTIAL, provided that at least  one  character  in  the
5027        This matches either "dog" or "dogsbody", greedily (that is, it  prefers
5028        the  longer  string  if  possible). If it is matched against the string
5030        However,  if  PCRE2_PARTIAL_HARD is set, the result is PCRE2_ERROR_PAR-
5031        TIAL. On the other hand, if the pattern is made ungreedy the result  is
5036        In  this  case  the  result  is always a complete match because that is
5041          /dog(sbody)?/    is the same as  /dogsbody|dog/
5042          /dog(sbody)??/   is the same as  /dog|dogsbody/
5052        ously.  If the end of the subject is reached before the end of the pat-
5053        tern, there is the possibility of a partial match, again provided  that
5056        When PCRE2_PARTIAL_SOFT is set, PCRE2_ERROR_PARTIAL is returned only if
5058        are  returned.   However, if PCRE2_PARTIAL_HARD is set, a partial match
5060        that was matched when the longest partial match was found is set as the
5064        there  is  no  difference between greedy and ungreedy repetition, their
5065        behaviour is different from  the  standard  functions  when  PCRE2_PAR-
5066        TIAL_HARD  is  set.  Consider  the  string  "dog"  matched  against the
5073        "dogsbody", and so returns that when PCRE2_PARTIAL_HARD is set.
5084        This matches "cat", provided there is a word boundary at either end. If
5085        the subject string is "the cat", the comparison of the final "t" with a
5086        following character cannot take place, so a  partial  match  is  found.
5088        subject when the last character is a letter, so  a  complete  match  is
5089        found.   The  result,  therefore,  is  not  PCRE2_ERROR_PARTIAL.  Using
5096        If  the  partial_soft  (or  ps) modifier is present on a pcre2test data
5097        line, the PCRE2_PARTIAL_SOFT option is used for the match.  Here  is  a
5113        The  first  data  string  is matched completely, so pcre2test shows the
5115        plete pattern, but the first two are partial matches. Similar output is
5116        obtained if DFA matching is used.
5118        If the partial_hard (or ph) modifier is present  on  a  pcre2test  data
5119        line, the PCRE2_PARTIAL_HARD option is set for the match.
5125        is possible to continue the match by providing additional subject  data
5128        same working space as before, because this is where details of the pre-
5129        vious partial match are stored. Here is an example using pcre2test:
5139        (restarted) match.  Notice that when the match is  complete,  only  the
5140        last  part  is  shown;  PCRE2 does not retain the previously partially-
5141        matched string. It is up to the calling program to do that if it  needs
5145        it is not possible to try again at  a  new  starting  point.  All  this
5146        facility  is  capable  of  doing  is continuing with the previous match
5147        attempt. In the previous example, if the second set of data  is  "ug23"
5148        the  result is no match, even though there would be a match for "aug23"
5151        ing again at the next character is to retain the matched  part  of  the
5162        Unlike the DFA function, it is not possible  to  restart  the  previous
5168        It is best to use PCRE2_PARTIAL_HARD in this situation, because it does
5174          data> The date is 23ja\=ph
5181        each call, so more memory and more processing time is needed.
5187        whichever matching function is used.
5191        does start at the beginning of a line. There  is  also  a  PCRE2_NOTEOL
5203        PCRE2_INFO_MAXLOOKBEHIND option. Note that the resulting  count  is  in
5207        retained. In a non-UTF or a 32-bit situation, moving  back  is  just  a
5212        after  the  next segment has been added to what is retained, you should
5216        For  example, if the pattern "(?<=123)abc" is partially matched against
5218        mum  lookbehind  count  is  3, so all characters before offset 2 can be
5241        4.  Matching  a subject string that is split into multiple segments may
5243        long  string,  especially  when PCRE2_PARTIAL_SOFT is used. The section
5247        PCRE2_PARTIAL_SOFT) a partial match result is given only when there are
5249        been  found,  continuation to a new subject segment is no longer possi-
5264        function, setting the PCRE2_PARTIAL_SOFT option. Although the string is
5265        a partial match for "dogsbody", the result is not  PCRE2_ERROR_PARTIAL,
5266        because  the  shorter string "dog" is a complete match. Similarly, when
5267        the subject is presented to a DFA matching function  in  several  parts
5269        been found, and it is not possible to continue.  On the other hand,  if
5270        "dogsbody"  is  presented  as  a single string, a DFA matching function
5273        Because of these problems, it is best to  use  PCRE2_PARTIAL_HARD  when
5287        PCRE2_DFA_RESTART is used. For example, consider this pattern:
5291        If the first part of the subject is "ABC123", a partial  match  of  the
5292        first  alternative  is found at offset 3. There is no partial match for
5298        alternative.  There  is  no  problem with anchored patterns or patterns
5303        where no string can be a partial match for both alternatives.  This  is
5304        not  a  problem  if  a  standard matching function is used, because the
5315        function. Another possibility is to work with two buffers. If a partial
5316        match  at  offset  n in the first buffer is followed by "no match" when
5317        PCRE2_DFA_RESTART is used on the second buffer, you can then try a  new
5345        by PCRE2 are described in detail below. There is a quick-reference syn-
5356        great  detail.  This  description  of  PCRE2's  regular  expressions is
5360        its  main  matching function, pcre2_match(), is used. PCRE2 also has an
5362        different  algorithm  that is not Perl-compatible. Some of the features
5363        discussed below are not available when DFA matching is used. The advan-
5384        strings, PCRE2 must be built to include Unicode support (which  is  the
5387        special  sequence  (*UTF),  which is equivalent to setting the relevant
5388        option. How setting a UTF mode affects pattern matching is mentioned in
5389        several  places  below.  There  is  also  a  summary of features in the
5394        PCRE2_NEVER_UTF option is passed  to  pcre2_compile(),  (*UTF)  is  not
5399        Another  special  sequence that may appear at the start of a pattern is
5406        restrict them for security reasons. If the  PCRE2_NEVER_UCP  option  is
5407        passed to pcre2_compile(), (*UCP) is not allowed, and its appearance in
5414        to whichever matching function is subsequently called to match the pat-
5423        item. For example, by default a+b is treated as a++b. For more details,
5443        If  a  pattern  that starts with (*NO_JIT) is successfully compiled, an
5445        pcre2_jit_compile() is ignored.
5450        internal match() function is called and on the maximum depth of  recur-
5452        are provoked by patterns with huge matching trees (a typical example is
5454        system stack by too  much  recursion.  When  one  of  these  limits  is
5461        where d is any number of decimal digits. However, the value of the set-
5465        If there is more than one setting of one of  these  limits,  the  lower
5466        value is used.
5477        It is also possible to specify a newline convention by starting a  pat-
5487        tion. For example, on a Unix system where LF  is  the  default  newline
5492        changes the convention to CR. That pattern matches "a\nb" because LF is
5493        no longer a newline. If more than one of these settings is present, the
5494        last one is used.
5498        acter  when  PCRE2_DOTALL is not set, and the behaviour of \N. However,
5500        this  is any Unicode newline sequence, for Perl compatibility. However,
5507        It is possible to restrict \R to match only CR, LF, or CRLF (instead of
5511        CODE) is also recognized, corresponding to PCRE2_BSR_UNICODE.
5525        A regular expression is a pattern that is  matched  against  a  subject
5532        matches a portion of a subject string that is identical to itself. When
5533        caseless matching is specified (the PCRE2_CASELESS option), letters are
5562        Part  of  a  pattern  that is in square brackets is called a "character
5577        The backslash character has several uses. Firstly, if it is followed by
5578        a character that is not a number or a letter, it takes away any special
5584        character  would  otherwise be interpreted as a metacharacter, so it is
5593        If a pattern is compiled with the  PCRE2_EXTENDED  option,  most  white
5600        ters,  you can do so by putting them between \Q and \E. This is differ-
5612        The \Q...\E sequence is recognized both inside  and  outside  character
5613        classes.   An  isolated \E that is not preceded by \Q is ignored. If \Q
5614        is not followed by \E later in the pattern, the literal  interpretation
5615        continues  to  the  end  of  the pattern (that is, \E is assumed at the
5616        end). If the isolated \Q is inside a character class,  this  causes  an
5617        error, because the character class is not terminated.
5622        acters in patterns in a visible manner. There is no restriction on  the
5624        is being prepared by text editing, it is often easier to use one of the
5628          \a        alarm, that is, the BEL character (hex 07)
5629          \cx       "control-x", where x is any printable ASCII character
5640          \uhhhh    character with hex code hhhh (when PCRE2_ALT_BSUX is set)
5642        The precise effect of \cx on ASCII characters is as follows: if x is  a
5643        lower  case  letter,  it  is converted to upper case. Then bit 6 of the
5644        character (hex 40) is inverted. Thus \cA to \cZ become hex 01 to hex 1A
5645        (A  is  41, Z is 5A), but \c{ becomes hex 3B ({ is 7B), and \c; becomes
5646        hex 7B (; is 3B). If the code unit following \c has a value  less  than
5650        When PCRE2 is compiled in EBCDIC mode, \a, \e, \f, \n, \r, and \t  gen-
5651        erate the appropriate EBCDIC code values. The \c escape is processed as
5662        which is BEL in ASCII but DEL in EBCDIC.
5665        but  because  127  is  not a control character in EBCDIC, Perl makes it
5668        FF), but in the one Perl calls POSIX-BC its value is 95  (hex  5F).  If
5676        if the pattern character that follows is itself an octal digit.
5679        in  braces.  An  error occurs if this is not the case. This escape is a
5684        For greater clarity and unambiguity, it is best to avoid following \ by
5689        The handling of a backslash followed by a digit other than 0 is compli-
5693        its as a decimal number. If the number is less than 10, begins with the
5695        left  parentheses  in the expression, the entire sequence is taken as a
5696        back reference. A description of how this works is given later, follow-
5706          \040   is another way of writing an ASCII space
5707          \40    is the same, provided there are fewer than 40
5709          \7     is always a back reference
5712          \011   is always a tab
5713          \0113  is a tab followed by the character "3"
5718          \81    is always a back reference
5724        By default, after \x that is not followed by {, from zero to two  hexa-
5728        there is no terminating }, an error occurs.
5730        If the PCRE2_ALT_BSUX option is set, the interpretation  of  \x  is  as
5731        just described only when it is followed by two hexadecimal digits. Oth-
5733        for  code points greater than 256 is provided by \u, which must be fol-
5737        Characters whose value is less than 256 can be defined by either of the
5738        two syntaxes for \x (or by \u in PCRE2_ALT_BSUX mode). There is no dif-
5739        ference  in  the way they are handled. For example, \xdc is exactly the
5761        class, \b is interpreted as the backspace character (hex 08).
5763        \N is not allowed in a character class. \B, \R, and \X are not  special
5773        PCRE2_ALT_BSUX option is set, \U matches a "U" character, and \u can be
5780        ally  enclosed  in braces, is an absolute or relative back reference. A
5787        name or a number enclosed either in angle brackets or single quotes, is
5790        \g<...>  (Oniguruma  syntax)  are  not synonymous. The former is a back
5791        reference; the latter is a subroutine call.
5795        Another use of backslash is for specifying generic character types:
5798          \D     any character that is not a decimal digit
5800          \H     any character that is not a horizontal white space character
5802          \S     any character that is not a white space character
5804          \V     any character that is not a vertical white space character
5808        There is also the single sequence \N, which matches a non-newline char-
5809        acter.   This is the same as the "." metacharacter when PCRE2_DOTALL is
5817        the  appropriate  type.  If the current matching point is at the end of
5818        the subject string, all of them fail, because there is no character  to
5823        locale. This list may vary if locale-specific matching is taking place.
5825        is recognized as white space, and in others the VT character is not.
5827        A  "word"  character is an underscore or any character that is a letter
5828        or digit.  By default, the definition of letters  and  digits  is  con-
5830        specific matching is taking place (see "Locale support" in the pcre2api
5834        use of locales with Unicode is discouraged.
5839        matching  is  happening.   These escape sequences retain their original
5841        ciency  reasons.  If  the  PCRE2_UCP  option  is  set, the behaviour is
5853        Matching these sequences is noticeably slower when PCRE2_UCP is set.
5857        list  of  code  points, whether or not PCRE2_UCP is set. The horizontal
5896        any Unicode newline sequence. In 8-bit non-UTF-8 mode \R is  equivalent
5901        This  is  an  example  of an "atomic group", details of which are given
5905        riage  return,  U+000D), or NEL (next line, U+0085). Because this is an
5906        atomic group, the two-character sequence is treated as  a  single  unit
5911        rator,  U+2029).  Unicode support is not needed for these characters to
5914        It is possible to restrict \R to match only CR, LF, or CRLF (instead of
5916        PCRE2_BSR_ANYCRLF at compile time. (BSR is an  abbrevation  for  "back-
5917        slash R".) This can be made the default when PCRE2 is built; if this is
5919        CODE  option. It is also possible to specify these settings by starting
5928        be  in upper case. If more than one of them is present, the last one is
5935        Inside a character class, \R  is  treated  as  an  unrecognized  escape
5940        When  PCRE2  is  built  with Unicode support (the default), three addi-
5965        "Common". The current list of scripts is:
5991        brace  and  the  property  name.  For  example,  \p{^Lu} is the same as
5994        If only one letter is specified with \p or \P, it includes all the gen-
6048        The  special property L& is also supported: it matches a character that
6049        has the Lu, Ll, or Lt property, in other words, a letter  that  is  not
6059        \p{Letter}) are not supported by PCRE2, nor is it permitted  to  prefix
6060        any of these properties with "Is".
6062        No character that is in the Unicode table has the Cn (unassigned) prop-
6063        erty.  Instead, this property is assumed for any code point that is not
6067        For example, \p{Lu} always matches only upper  case  letters.  This  is
6070        Matching  characters by Unicode property is not fast, because PCRE2 has
6072        erty. That is why the traditional escape sequences such as \d and \w do
6112        non-standard,  non-Perl  properties  internally  when PCRE2_UCP is set.
6123        (separator)  property.   Xsp  is  the  same as Xps; in PCRE1 it used to
6127        There  is another non-standard property, Xuc, which matches any charac-
6133        are  of  the  form \uHHHH or \UHHHHHHHH where H is a hexadecimal digit.
6145        is  similar  to  a lookbehind assertion (described below).  However, in
6153        matches "foobar", the first substring is still set to "foo".
6155        Perl  documents  that  the  use  of  \K  within assertions is "not well
6156        defined". In PCRE2, \K is acted upon when  it  occurs  inside  positive
6157        assertions,  but  is  ignored  in negative assertions. Note that when a
6163        The  final use of backslash is for certain simple assertions. An asser-
6166        use of subpatterns for more complicated assertions is described  below.
6179        character class, an "invalid escape sequence" error is generated.
6181        A  word  boundary is a position in the subject string where the current
6186        PCRE2_UCP option. When this is done, it also affects \b and \B. Neither
6188        quence. However, whatever follows \b normally determines which  it  is.
6197        acters.  However,  if the startoffset argument of pcre2_match() is non-
6198        zero, indicating that matching is to start at a point  other  than  the
6200        \Z and \z is that \Z matches before a newline at the end of the  string
6203        The  \G assertion is true only when the current matching position is at
6205        of  pcre2_match().  It differs from \A when the value of startoffset is
6207        arguments,  you  can  mimic Perl's /g option, and it is in this kind of
6211        current match, is subtly different from Perl's, which defines it as the
6216        If all the alternatives of a pattern begin with \G, the  expression  is
6217        anchored to the starting match position, and the "anchored" flag is set
6224        That  is,  they test for a particular condition being true without con-
6227        line convention is set so that only the two-character sequence CRLF  is
6232        character  is  an  assertion  that is true only if the current matching
6233        point is at the start of the subject string. If the  startoffset  argu-
6234        ment  of  pcre2_match() is non-zero, or if PCRE2_NOTBOL is set, circum-
6235        flex can never match if the PCRE2_MULTILINE option is unset.  Inside  a
6241        alternative in which it appears if the pattern is ever  to  match  that
6242        branch.  If all possible alternatives start with a circumflex, that is,
6243        if the pattern is constrained to match only at the start  of  the  sub-
6244        ject,  it  is  said  to be an "anchored" pattern. (There are also other
6247        The dollar character is an assertion that is true only if  the  current
6248        matching  point  is  at  the  end of the subject string, or immediately
6250        PCRE2_NOTEOL is set. Note, however, that it does not actually match the
6261        the PCRE2_MULTILINE option is set. When this  is  the  case,  a  dollar
6272        match  for  circumflex  is  possible  when  the startoffset argument of
6273        pcre2_match() is non-zero. The PCRE2_DOLLAR_ENDONLY option  is  ignored
6274        if PCRE2_MULTILINE is set.
6277        nizes the two-character sequence CRLF as a newline, this is  preferred,
6279        lines. For example, if the newline convention  is  "any",  a  multiline
6281        than after CR, even though CR on its own is a valid newline.  (It  also
6286        start  with \A it is always anchored, whether or not PCRE2_MULTILINE is
6296        When a line ending is defined as a single character, dot never  matches
6297        that  character; when the two-character sequence CRLF is used, dot does
6298        not match CR if it is immediately followed  by  LF,  but  otherwise  it
6304        PCRE2_DOTALL option is set, a dot matches any  one  character,  without
6305        exception.   If  the two-character sequence CRLF is present in the sub-
6308        The handling of dot is entirely independent of the handling of  circum-
6312        The escape sequence \N behaves like  a  dot,  except  that  it  is  not
6321        unit, whether or not a UTF mode is set. In the 8-bit library, one  code
6322        unit  is  one  byte;  in the 16-bit library it is a 16-bit unit; in the
6323        32-bit library it is a 32-bit unit. Unlike a  dot,  \C  always  matches
6324        line-ending  characters.  The  feature  is provided in Perl in order to
6325        match individual bytes in UTF-8 mode, but it is unclear how it can use-
6331        results, because PCRE2 assumes that it is matching character by charac-
6334        option is used).
6337        PCRE2_NEVER_BACKSLASH_C option when compiling a  pattern.  It  is  also
6345        to optimize and so the match is always run using the interpreter.
6347        In the 32-bit library,  however,  \C  is  always  supported  (when  not
6349        whether or not UTF-32 is specified.
6351        In general, the \C escape sequence is best avoided. However, one way of
6353        ters is to use a lookahead to check the length of the  next  character,
6373        closing square bracket. A closing square bracket on its own is not spe-
6374        cial  by  default.  If a closing square bracket is required as a member
6378        the  PCRE2_ALLOW_EMPTY_CLASS option is set, a closing square bracket at
6383        the first character in the class definition is a circumflex,  in  which
6385        If a circumflex is actually required as a member of the  class,  ensure
6386        it is not the first character, or escape it with a backslash.
6389        while [^aeiou] matches any character that is not a  lower  case  vowel.
6390        Note that a circumflex is just a convenient notation for specifying the
6392        class  that starts with a circumflex is not an assertion; it still con-
6394        the current pointer is at the end of the string.
6396        When  caseless  matching  is set, any letters in a class represent both
6403        sequence is in use,  and  whatever  setting  of  the  PCRE2_DOTALL  and
6404        PCRE2_MULTILINE  options  is  used. A class such as [^a] always matches
6409        between d and m, inclusive. If a  minus  character  is  required  in  a
6416        It is not possible to have the literal character "]" as the end charac-
6417        ter of a range. A pattern such as [W-]46] is interpreted as a class  of
6419        would match "W46]" or "-46]". However, if the "]"  is  escaped  with  a
6420        backslash  it is interpreted as the end of range, so [W-\]46] is inter-
6425        An error is generated if a POSIX character  class  (see  below)  or  an
6427        at a point where a range ending character  is  expected.  For  example,
6428        [z-\xff] is valid, but [A-\d] and [A-[:digit:]] are not.
6435        There is a special case in EBCDIC environments  for  ranges  whose  end
6440        points.  However,  if  the range is specified numerically, for example,
6443        If a range that includes letters is used when caseless matching is set,
6444        it matches the letters in either case. For example, [W-c] is equivalent
6504        CR  (13),  and space (32). If locale-specific matching is taking place,
6508        The  name  "word"  is  a Perl extension, and "blank" is a GNU extension
6509        from Perl 5.8. Another Perl extension is negation, which  is  indicated
6515        POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but
6516        these are not supported, and an error is given if they are encountered.
6520        ters  in  the range 128-255 when locale-specific matching is happening.
6521        However, if the PCRE2_UCP option is passed to pcre2_compile(), some  of
6523        This  is  achieved  by  replacing  certain  POSIX  classes  with  other
6549                  characters  that  are  not controls, that is, characters with
6563        ugly syntax [[:<:]] and [[:>:]] is used for matching  "start  of  word"
6566          [[:<:]]  is converted to  \b(?=\w)
6567          [[:>:]]  is converted to  \b(?<=\w)
6571        support  is not compatible with Perl. It is provided to help migrations
6572        from other environments, and is best not used in any new patterns. Note
6575        character  normally  shows  which  is  wanted, without the need for the
6588        appear,  and  an  empty  alternative  is  permitted (matching the empty
6590        to  right, and the first one that succeeds is used. If the alternatives
6607        For example, (?im) sets caseless, multiline matching. It is also possi-
6611        PCRE2_EXTENDED, is also permitted. If a letter appears both before  and
6612        after  the  hyphen, the option is unset. An empty options setting "(?)"
6613        is allowed. Needless to say, it has no effect.
6619        When one of these option changes occurs at  top  level  (that  is,  not
6621        the pattern that follows. If the change is placed right at the start of
6632        matches  abc  and  aBc and no other strings (assuming PCRE2_CASELESS is
6641        first branch is abandoned before the option setting.  This  is  because
6655        application when the compiling function is called. The pattern can con-
6680        that  matched  the  subpattern is passed back to the caller, separately
6687        string "the red king" is matched against the pattern
6694        The  fact  that  plain  parentheses  fulfil two functions is not always
6695        helpful.  There are often times when a grouping subpattern is  required
6696        without  a capturing requirement. If an opening parenthesis is followed
6698        ing,  and  is  not  counted when computing the number of any subsequent
6699        capturing subpatterns. For example, if the string "the white queen"  is
6705        1 and 2. The maximum number of capturing subpatterns is 65535.
6716        the subpattern is reached, an option setting in one branch does  affect
6725        starts with (?| and is itself a non-capturing subpattern. For  example,
6733        matched. This construct is useful when you want to  capture  part,  but
6735        theses are numbered as usual, but the number is reset at the  start  of
6738        lowing example is taken from the Perl documentation. The numbers under-
6746        that  is  set  for that number by any subpattern. The following pattern
6757        A relative reference such as (?-1) is no different: it is just a conve-
6761        unique number, the test is true if any of the subpatterns of that  num-
6764        An  alternative approach to using this "branch reset" feature is to use
6770        Identifying capturing parentheses by number is simple, but  it  can  be
6772        sions. Furthermore, if an  expression  is  modified,  the  numbers  may
6793        By  default, a name must be unique within a pattern, but it is possible
6809        There  are  five capturing substrings, but only one is ever set after a
6810        match.  (An alternative way of solving this problem is to use a "branch
6821        first one that is set is used for the reference. For example, this pat-
6828        that  corresponds  to  the first occurrence of the name is used. In the
6829        absence of duplicate numbers (see the previous section) this is the one
6835        If the condition is true for any one of them, the overall condition  is
6836        true.  This  is  the  same  behaviour as testing by number. For further
6842        matching. For this reason, an error is given at compile time if differ-
6845        when PCRE2_DUPNAMES is not set.
6850        Repetition is specified by quantifiers, which can  follow  any  of  the
6871        matches "zz", "zzz", or "zzzz". A closing brace on its  own  is  not  a
6872        special  character.  If  the second number is omitted, but the comma is
6873        present, there is no upper limit; if the second number  and  the  comma
6884        position  where a quantifier is not allowed, or one that does not match
6885        the syntax of a quantifier, is taken as a literal character. For  exam-
6886        ple, {,6} is not a quantifier, but a literal string of four characters.
6890        of which is represented by a two-byte sequence in a UTF-8 string. Simi-
6895        The quantifier {0} is permitted, causing the expression to behave as if
6905          *    is equivalent to {0,}
6906          +    is equivalent to {1,}
6907          ?    is equivalent to {0,1}
6909        It is possible to construct infinite loops by  following  a  subpattern
6918        subpattern  does in fact match no characters, the loop is forcibly bro-
6921        By default, the quantifiers are "greedy", that is, they match  as  much
6924        this gives problems is in trying to match comments in C programs. These
6938        If a quantifier is followed by a question mark, it ceases to be greedy,
6945        quantifiers is not otherwise changed,  just  the  preferred  number  of
6952        which matches one digit by preference, but can match two if that is the
6955        If the PCRE2_UNGREEDY option is set (an option that is not available in
6960        When  a  parenthesized  subpattern  is quantified with a minimum repeat
6961        count that is greater than 1 or with a limited maximum, more memory  is
6966        (equivalent  to  Perl's /s) is set, thus allowing the dot to match new-
6967        lines, the pattern is implicitly  anchored,  because  whatever  follows
6969        so there is no point in retrying the  overall  match  at  any  position
6973        In cases where it is known that the subject  string  contains  no  new-
6974        lines,  it  is worth setting PCRE2_DOTALL in order to obtain this opti-
6978        When .*  is inside capturing parentheses that are the subject of a back
6984        If  the subject is "xyz123abc123" the match point is the fourth charac-
6985        ter. For this reason, such a pattern is not implicitly anchored.
6987        Another case where implicit anchoring is not applied is when the  lead-
6988        ing  .* is inside an atomic group. Once again, a match at the start may
6995        there is an option, PCRE2_NO_DOTSTAR_ANCHOR, to do so explicitly.
6997        When a capturing subpattern is repeated, the value captured is the sub-
7003        is "tweedledee". However, if there are  nested  capturing  subpatterns,
7009        matches "aba" the value of the second captured substring is "b".
7017        rest  of  the pattern to match. Sometimes it is useful to prevent this,
7019        than  it otherwise might, when the author of the pattern knows there is
7028        action of the matcher is to try again with only 5 digits  matching  the
7031        the  means for specifying that once a subpattern has matched, it is not
7036        is a kind of special parenthesis, starting with (?> as in this example:
7041        tains  once  it  has matched, and a failure further into the pattern is
7045        An  alternative  description  is that a subpattern of this type matches
7058        atomic group is just a single repeated item, as in the example above, a
7071        PCRE2_UNGREEDY  option  is  ignored. They are a convenient notation for
7072        the simpler forms of atomic group. However, there is no  difference  in
7077        The  possessive  quantifier syntax is an extension to the Perl 5.8 syn-
7084        simple pattern constructs. For example, the sequence A+B is treated  as
7085        A++B  because  there is no point in backtracking into a sequence of A's
7091        atomic  group  is  the  only way to avoid some failing matches taking a
7098        matches, it runs quickly. However, if it is applied to
7102        it takes a long time before reporting  failure.  This  is  because  the
7107        when  a single character is used. They remember the last single charac-
7108        ter that is required for a match, and fail early if it is  not  present
7109        in  the  string.)  If  the pattern is changed so that it uses an atomic
7120        0 (and possibly further digits) is a back reference to a capturing sub-
7121        pattern earlier (that is, to its left) in the pattern,  provided  there
7124        However,  if the decimal number following the backslash is less than 8,
7125        it is always taken as a back reference, and causes  an  error  only  if
7129        reference" of this type can make sense when a  repetition  is  involved
7133        It is not possible to have a numerical "forward back  reference"  to  a
7134        subpattern  whose  number  is  8  or  more  using this syntax because a
7135        sequence such as \50 is interpreted as a character  defined  in  octal.
7137        details of the handling of digits following a backslash.  There  is  no
7139        subpattern is possible using named parentheses (see below).
7142        following  a  backslash  is  to use the \g escape sequence. This escape
7151        ity that is present in the older syntax. It is also useful when literal
7152        digits follow the reference. A negative number is a relative reference.
7157        The sequence \g{-1} is a reference to the most recently started captur-
7158        ing subpattern before \g, that is, is it equivalent to \2 in this exam-
7172        not  "sense and responsibility". If caseful matching is in force at the
7173        time of the back reference, the case of letters is relevant. For  exam-
7179        original capturing subpattern is matched caselessly.
7183        \k'name' are supported, as is the Python syntax (?P=name). Perl  5.10's
7185        and named references, is also supported. We  could  rewrite  the  above
7193        A  subpattern  that  is  referenced  by  name may appear in the pattern
7203        the  PCRE2_MATCH_UNSET_BACKREF  option  is  set at compile time, a back
7210        PCRE2_EXTENDED option is set, this can be white space.  Otherwise,  the
7216        fails when the subpattern is first used, so, for example,  (a\1)  never
7237        An assertion is a test on the characters  following  or  preceding  the
7244        string,  and  those  that  look  behind  it. An assertion subpattern is
7251        tern. However, substring capturing is carried  out  only  for  positive
7262        (1)  If  the  quantifier  is  {0}, the assertion is never obeyed during
7266        (2)  If quantifier is {0,n} where n is greater than zero, it is treated
7267        as if it were {0,1}. At run time, the rest  of  the  pattern  match  is
7271        (3) If the minimum repetition is greater than zero, the  quantifier  is
7272        ignored.   The  assertion  is  obeyed just once when encountered during
7287        matches any occurrence of "foo" that is not  followed  by  "bar".  Note
7292        does  not  find  an  occurrence  of "bar" that is preceded by something
7294        the assertion (?!foo) is always true when the next three characters are
7295        "bar". A lookbehind assertion is needed to achieve the other effect.
7298        most  convenient  way  to  do  it  is with (?!) because an empty string
7301        is a synonym for (?!).
7310        does  find  an  occurrence  of "bar" that is not preceded by "foo". The
7318        is permitted, but
7324        This is an extension compared with Perl, which requires all branches to
7329        is not permitted, because its single top-level  branch  can  match  two
7330        different  lengths,  but  it is acceptable to PCRE2 if rewritten to use
7338        The  implementation  of lookbehind assertions is, for each alternative,
7351        Recursion, however, is not supported.
7362        the pattern is specified as
7367        (because there is no following "a"), it backtracks to match all but the
7370        so we are no better off. However, if the pattern is written as
7387        each of the assertions is applied independently at the  same  point  in
7388        the  subject  string.  First  there  is a check that the previous three
7389        characters are all digits, and then there is  a  check  that  the  same
7393        foo". A pattern to do that is
7405        matches an occurrence of "baz" that is preceded by "bar" which in  turn
7406        is not preceded by "foo", while
7410        is  another pattern that matches "foo" preceded by three digits and any
7416        It is possible to cause the matching process to obey a subpattern  con-
7425        If the condition is satisfied, the yes-pattern is used;  otherwise  the
7426        no-pattern  (if  present)  is used. If there are more than two alterna-
7430        applies only at the level of the condition. This pattern fragment is an
7443        the condition is true if a capturing subpattern of that number has pre-
7444        viously matched. If there is more than one  capturing  subpattern  with
7446        numbers), the condition is true if any of them have matched. An  alter-
7447        native  notation is to precede the digits with a plus or minus sign. In
7448        this case, the subpattern number is relative rather than absolute.  The
7453        is not used; it provokes a compile-time error.)
7462        character is present, sets it as the first captured substring. The sec-
7464        third part is a conditional subpattern that tests whether  or  not  the
7465        first  set  of  parentheses  matched.  If they did, that is, if subject
7466        started with an opening parenthesis, the condition is true, and so  the
7467        yes-pattern  is  executed and a closing parenthesis is required. Other-
7468        wise, since no-pattern is not present, the subpattern matches  nothing.
7484        PCRE1, which had this facility before Perl, the syntax (?(name)...)  is
7491        If  the  name used in a condition of this kind is a duplicate, the test
7492        is applied to all subpatterns of the same name, and is true if any  one
7497        If the condition is the string (R), and there is no subpattern with the
7498        name R, the condition is true if a recursive call to the whole  pattern
7504        the condition is true if the most recent recursion is into a subpattern
7505        whose number or name is given. This condition does not check the entire
7506        recursion stack. If the name used in a condition  of  this  kind  is  a
7507        duplicate, the test is applied to all subpatterns of the same name, and
7508        is true if any one of them is the most recent recursion.
7511        syntax for recursive patterns is described below.
7515        If  the  condition  is  the string (DEFINE), and there is no subpattern
7516        with the name DEFINE, the condition is  always  false.  In  this  case,
7517        there  may  be  only  one  alternative  in the subpattern. It is always
7519        DEFINE  is that it can be used to define subroutines that can be refer-
7520        enced from elsewhere. (The use of subroutines is described below.)  For
7527        The first part of the pattern is a DEFINE group inside which a  another
7528        group  named "byte" is defined. This matches an individual component of
7530        this  part  of  the pattern is skipped because DEFINE acts like a false
7547        This pattern matches "yes" if the PCRE2 version is greater or equal  to
7553        If the condition is not in any of the above  formats,  it  must  be  an
7561        The  condition  is  a  positive  lookahead  assertion  that  matches an
7564        letter is found, the subject is matched against the first  alternative;
7565        otherwise  it  is  matched  against  the  second.  This pattern matches
7580        PCRE2_EXTENDED  option is set, an unescaped # character also introduces
7583        ters are interpreted as newlines is controlled by an option  passed  to
7586        above.  Note  that the end of this type of comment is a literal newline
7589        PCRE2_EXTENDED is set, and the default  newline  convention  (a  single
7590        linefeed character) is in force:
7595        for a newline in the pattern. The sequence \n is still literal at  this
7604        that can be done is to use a pattern that  matches  up  to  some  fixed
7605        depth  of  nesting.  It  is not possible to handle an arbitrary nesting
7626        zero and a closing parenthesis is a recursive subroutine  call  of  the
7628        subpattern. (If not, it is a non-recursive subroutine  call,  which  is
7629        described  in  the  next  section.)  The special item (?R) or (?0) is a
7633        PCRE2_EXTENDED option is set so that white space is ignored):
7639        recursive  match  of the pattern itself (that is, a correctly parenthe-
7640        sized substring).  Finally there is a closing parenthesis. Note the use
7653        tricky.  This is made easier by the use of relative references. Instead
7657        the point at which it is encountered.
7666        group (c) is number 2. When the reference  (?-2)  is  encountered,  the
7667        second most recently opened parentheses has the number 1, but it is the
7673        It  is  also  possible  to refer to subsequently opened parentheses, by
7675        because  the  reference  is  not inside the parentheses that are refer-
7679        An  alternative  approach  is to use named parentheses. The Perl syntax
7680        for this is (?&name); PCRE1's earlier syntax  (?P>name)  is  also  sup-
7685        If  there  is more than one subpattern with the same name, the earliest
7686        one is used.
7690        strings of non-parentheses is important when applying  the  pattern  to
7691        strings that do not match. For example, when this pattern is applied to
7695        it  yields  "no  match" quickly. However, if a possessive quantifier is
7703        tion). If the pattern above is matched against
7707        the  value  for  the  inner capturing parentheses (numbered 2) is "ef",
7708        which is the last value taken on at the top level. If a capturing  sub-
7709        pattern  is  not  matched at the top level, its final captured value is
7721        brackets  (that is, when recursing), whereas any characters are permit-
7726        In this pattern, (?(R) is the start of a conditional  subpattern,  with
7728        The (?R) item is the actual recursive call.
7733        In PCRE2 (like Python, but unlike Perl), a recursive subpattern call is
7734        always treated as an atomic group. That is, once it has matched some of
7735        the subject string, it is never re-entered, even if it contains untried
7736        alternatives and there is a subsequent matching failure.  This  can  be
7743        The idea is that it either matches a single character, or two identical
7745        in  PCRE2  it  does not if the pattern is longer than three characters.
7748        At the top level, the first character is matched, but as it is  not  at
7750        tive is taken and the recursion kicks in. The recursive call to subpat-
7754        Back at the top level, the next character ("c") is compared  with  what
7756        is treated as an atomic group, there are now  no  backtracking  points,
7757        and  so  the  entire  match fails. (Perl is able, at this point, to re-
7759        pattern is written with the alternatives in the other order, things are
7764        This time, the recursing alternative is tried first, and  continues  to
7767        higher  level.  That  is  the  big difference: in the previous case the
7768        remaining alternative is at a deeper recursion level, which PCRE2  can-
7772        just those with an odd number of characters, it is tempting  to  change
7779        entered  again  in  order  to match an empty string. The solution is to
7798        ject string does not start with a palindrome that is shorter  than  the
7799        entire  string.  For example, although "abcba" is correctly matched, if
7800        the subject is "ababa", PCRE2 finds the palindrome "aba" at the  start,
7806        cessing is in the handling of captured values. In Perl, when a  subpat-
7807        tern  is  called recursively or as a subpattern (see the next section),
7825        name) is used outside the parentheses to which it refers,  it  operates
7843        is used, it does match "sense and responsibility" as well as the  other
7844        two  strings.  Another  example  is  given  in the discussion of DEFINE
7848        atomic  groups. That is, once a subroutine has matched some of the sub-
7849        ject string, it is never re-entered, even if it contains untried alter-
7850        natives  and  there  is  a  subsequent  matching failure. Any capturing
7855        tern is defined, so if it is used as a subroutine, such options  cannot
7867        name or a number enclosed either in angle brackets or single quotes, is
7875        PCRE2 supports an extension to Oniguruma: if a number is preceded by  a
7876        plus or a minus sign it is taken as a relative reference. For example:
7881        synonymous. The former is a back reference; the latter is a  subroutine
7890        strings that match the same pair of parentheses when there is a repeti-
7894        trary Perl code. The feature is called "callout". The caller  of  PCRE2
7897        context  to  pcre2_match() or pcre2_dfa_match(). If no match context is
7898        passed, or if the callout entry point is set to NULL, callouts are dis-
7902        external function is to be called. There  are  two  kinds  of  callout:
7904        on its own with no argument is treated as (?C0). A  numerical  argument
7911        tion  is  called.  It is provided with the number or string argument of
7912        the callout, the position in the pattern, and one item of data that  is
7917        time,  and  one  side-effect is that sometimes callouts are skipped. If
7931        If  the PCRE2_AUTO_CALLOUT flag is passed to pcre2_compile(), numerical
7933        They  are all numbered 255. If there is a conditional group in the pat-
7934        tern whose condition is an assertion, an additional callout is inserted
7947        ending delimiter is the same as the start, except for {, where the end-
7948        ing delimiter is }. If  the  ending  delimiter  is  needed  within  the
7953        The  doubling  is  removed  before  the string is passed to the callout
7969        differently depending on whether or not a name is present.
7971        By default, for compatibility with Perl, a  name  is  any  sequence  of
7972        characters that does not include a closing parenthesis. The name is not
7973        processed in any way, and it is  not  possible  to  include  a  closing
7974        parenthesis in the name.  However, if the PCRE2_ALT_VERBNAMES option is
7975        set, normal backslash processing is applied to verb names and  only  an
7978        PCRE2_EXTENDED  option  is  set,  unescaped whitespace in verb names is
7982        The  maximum  length of a name is 255 in the 8-bit library and 65535 in
7983        the 16-bit and 32-bit libraries. If the name is empty, that is, if  the
7984        closing  parenthesis immediately follows the colon, the effect is as if
7989        them can be used only when the pattern is to be matched using the  tra-
7996        subpatterns called as subroutines (whether or not recursively) is docu-
8008        pile(),  or by starting the pattern with (*NO_START_OPT). There is more
8023        of the pattern. However, when it is inside a subpattern that is  called
8024        as  a  subroutine, only that subpattern is ended successfully. Matching
8029        If (*ACCEPT) is inside capturing parentheses, the data so far  is  cap-
8034        This  matches  "AB", "AAD", or "ACD"; when it matches "AB", "B" is cap-
8040        is  equivalent to (?!) but easier to read. The Perl documentation notes
8041        that it is probably useful only when combined  with  (?{})  or  (??{}).
8043        nearest equivalent is the callout feature, as for example in this  pat-
8048        A  match  with the string "aaaa" always fails, but the callout is taken
8053        There is one verb whose main purpose  is  to  track  how  a  match  was
8059        A name is always  required  with  this  verb.  There  may  be  as  many
8064        (*PRUNE:NAME),  or  (*THEN:NAME) on the matching path is passed back to
8066        about  the  match" in the pcre2api documentation. Here is an example of
8078        The (*MARK) name is tagged with "MK:" in this output, and in this exam-
8079        ple it indicates which of the two alternatives matched. This is a  more
8083        If a verb with a name is encountered in a positive  assertion  that  is
8084        true,  the  name  is recorded and passed back if it is the last-encoun-
8089        the entire match process is returned. For example:
8095        Note that in this unanchored example the  mark  is  retained  from  the
8102        ensure that the match is always attempted.
8107        tinues with what follows, but if there is no subsequent match,  causing
8108        a  backtrack  to  the  verb, a failure is forced. That is, backtracking
8110        appears inside an atomic group (which includes any group that is called
8111        as a subroutine) or in an assertion that is true, its  effect  is  con-
8112        fined  to that group, because once the group has been matched, there is
8117        tracking reaches them. The behaviour described below  is  what  happens
8118        when  the  verb is not in a subroutine or an assertion. Subsequent sec-
8124        to fail outright if there is a later matching failure that causes back-
8125        tracking to reach it. Even if the pattern  is  unanchored,  no  further
8127        (*COMMIT) is the only backtracking verb that is  encountered,  once  it
8128        has  been  passed  pcre2_match() is committed to finding a match at the
8135        most recently passed (*MARK) in the path is passed back when  (*COMMIT)
8138        If  there  is more than one backtracking verb in a pattern, a different
8143        Note that (*COMMIT) at the start of a pattern is not  the  same  as  an
8159        character. The pattern is now applied  starting  at  "x",  and  so  the
8166        the subject if there is a later matching failure that causes backtrack-
8167        ing to reach it. If the pattern is unanchored, the  normal  "bumpalong"
8169        occur as usual to the left of (*PRUNE), before it is reached,  or  when
8170        matching  to  the  right  of  (*PRUNE), but if there is no match to the
8172        (*PRUNE)  is just an alternative to an atomic group or possessive quan-
8177        The   behaviour   of   (*PRUNE:NAME)   is   the   not   the   same   as
8178        (*MARK:NAME)(*PRUNE).   It  is  like  (*MARK:NAME)  in that the name is
8185        This verb, when given without a name, is like (*PRUNE), except that  if
8186        the  pattern  is unanchored, the "bumpalong" advance is not to the next
8193        If the subject is "aaaac...",  after  the  first  match  attempt  fails
8203        When (*SKIP) has an associated name, its behaviour is modified. When it
8204        is triggered, the previous path through the pattern is searched for the
8205        most recent (*MARK) that has the  same  name.  If  one  is  found,  the
8206        "bumpalong" advance is to the subject position that corresponds to that
8208        a matching name is found, the (*SKIP) is ignored.
8216        tracking  reaches  it.  That  is,  it  cancels any further backtracking
8222        If  the COND1 pattern matches, FOO is tried (and possibly further items
8225        into COND1. If that succeeds and BAR fails, COND3 is tried.  If  subse-
8226        quently  BAZ fails, there are no more alternatives, so there is a back-
8227        track to whatever came before the  entire  group.  If  (*THEN)  is  not
8230        The    behaviour   of   (*THEN:NAME)   is   the   not   the   same   as
8231        (*MARK:NAME)(*THEN).  It is like  (*MARK:NAME)  in  that  the  name  is
8236        A  subpattern that does not contain a | character is just a part of the
8237        enclosing alternative; it is not a nested  alternation  with  only  one
8245        If A and B are matched, but there is a failure in C, matching does  not
8246        backtrack into A; instead it moves to the next alternative, that is, D.
8247        However, if the subpattern containing (*THEN) is given an  alternative,
8252        The  effect of (*THEN) is now confined to the inner subpattern. After a
8257        Note that a conditional subpattern is  not  considered  as  having  two
8258        alternatives,  because  only  one  is  ever used. In other words, the |
8264        If  the  subject  is  "ba", this pattern does not match. Because .*? is
8266        then  fails,  the  character  "b"  is  matched, but "c" is not. At this
8268        from  the  presence  of  the | character. The conditional subpattern is
8274        when subsequent matching fails. (*THEN) is the weakest, carrying on the
8277        character (for an unanchored pattern). (*SKIP) is similar, except  that
8278        the advance may be more than one character. (*COMMIT) is the strongest,
8283        If more than one backtracking verb is present in  a  pattern,  the  one
8284        that  is  backtracked  onto first acts. For example, consider this pat-
8292        is  consistent,  but is not always the same as Perl's. It means that if
8298        If there is a matching failure to the right, backtracking onto (*PRUNE)
8299        causes it to be triggered, and its action is taken. There can never  be
8309        If the subject is "abac", Perl matches, but  PCRE2  fails  because  the
8324        whether or not this is within the assertion.
8337        These behaviours occur whether or not the subpattern is  called  recur-
8338        sively.  Perl's treatment of subroutines is different in some cases.
8351        within the subpattern that has alternatives. If there is no such  group
8393        there  is  one case where the memory usage of a compiled pattern can be
8396        is repeated in the compiled code. For example, the pattern
8400        is compiled as if it were
8404        (Technical aside: It is done this way so that backtrack  points  within
8408        is not usually a problem. However, if the numbers are large,  and  par-
8414        uses 51K bytes when compiled using the 8-bit  library.  When  PCRE2  is
8416        limit on a compiled pattern is 64K code units in the 8-bit  and  16-bit
8417        libraries, and this is reached with the above pattern if the outer rep-
8418        etition is increased from 3 to 4. PCRE2 can be compiled to  use  larger
8419        internal  pointers  and thus handle larger compiled patterns, but it is
8422        One way of reducing the memory usage for such patterns is to  make  use
8429        is  not  exactly equivalent, because the "subroutine" calls are treated
8430        as atomic groups into which there can be no backtracking if there is  a
8432        rewriting automatically.  Furthermore, there is a  noticeable  loss  of
8434        grouping is not a problem and the loss of  speed  is  acceptable,  this
8441        When pcre2_match() is used for matching, certain kinds of  pattern  can
8443        ments the default process stack is quite small, and if it runs out  the
8444        result  is  often  SIGSEGV.  Rewriting your pattern can often help. The
8451        ciently than others. It is more efficient to use a character class like
8454        required behaviour is usually the most efficient. Jeffrey Friedl's book
8459        Using  Unicode  character  properties  (the  \p, \P, and \X escapes) is
8470        pcre2_match(); the performance loss is less with a DFA  matching  func-
8471        tion, and in both cases there is not much difference for \b.
8475        option  is  set,  the pattern is implicitly anchored by PCRE2, since it
8478        tion can be disabled by  the  PCRE2_NO_DOTSTAR_ANCHOR  option,  and  is
8481        If  PCRE2_DOTALL  is  not  set,  PCRE2  cannot  make this optimization,
8495        tain   newlines,   the   best   performance   is  obtained  by  setting
8510        the pattern is such that the entire match is going to fail,  PCRE2  has
8519        matching  procedure, PCRE2 checks that there is a "b" later in the sub-
8520        ject string, and if there is not, it fails the match immediately.  How-
8521        ever,  when  there  is no following literal this optimization cannot be
8530        In many cases, the solution to this kind of performance issue is to use
8581        pcre2posix.h  header  file,  and  on Unix systems the library itself is
8584        POSIX functions call the native ones,  it  is  also  necessary  to  add
8588        options have been implemented. In addition, the option REG_EXTENDED  is
8598        When PCRE2 is called via these functions, it is only the  API  that  is
8602        that the API approximates to the POSIX  definition;  it  is  not  fully
8603        POSIX-compatible,  and  in  multi-unit  encoding domains it is probably
8606        The header for these functions is supplied as pcre2posix.h to avoid any
8608        renamed or aliased as regex.h, which is the "correct" name. It provides
8617        The function regcomp() is called to compile a pattern into an  internal
8618        form.  The  pattern  is  a C string terminated by a binary zero, and is
8619        passed in the argument pattern. The preg argument is  a  pointer  to  a
8620        regex_t  structure that is used as a base for storing information about
8623        The argument cflags is either zero, or contains one or more of the bits
8628        The  PCRE2_DOTALL  option  is set when the regular expression is passed
8629        for compilation to the native function. Note  that  REG_DOTALL  is  not
8634        The  PCRE2_CASELESS option is set when the regular expression is passed
8639        The PCRE2_MULTILINE option is set when the regular expression is passed
8646        When  a  pattern that is compiled with this flag is passed to regexec()
8654        The  PCRE2_UCP  option is set when the regular expression is passed for
8657        ASCII values. Note that REG_UCP is not part of the POSIX standard.
8661        The PCRE2_UNGREEDY option is set when the regular expression is  passed
8662        for  compilation  to the native function. Note that REG_UNGREEDY is not
8667        The PCRE2_UTF option is set when the regular expression is  passed  for
8670        Note that REG_UTF is not part of the POSIX standard.
8673        function.  This means the the regex  is  compiled  with  PCRE2  default
8675        subject string is the Perl way, not the POSIX way.  Note  that  setting
8680        The  yield of regcomp() is zero on success, and non-zero otherwise. The
8681        preg structure is filled in on success, and one member of the structure
8682        is  public: re_nsub contains the number of capturing subpatterns in the
8685        NOTE: If the yield of regcomp() is non-zero, you must  not  attempt  to
8687        regexec(), the result is undefined and your program is likely to crash.
8692        This area is not simple, because POSIX and Perl take different views of
8693        things.   It  is not possible to get PCRE2 to obey POSIX semantics, but
8706        This is the equivalent table for a POSIX-compatible pattern matcher:
8716        This behaviour is not what happens when PCRE2 is called via  its  POSIX
8717        API.  By  default, PCRE2's behaviour is the same as Perl's, except that
8718        there is no equivalent for PCRE2_DOLLAR_ENDONLY in Perl. In both  PCRE2
8719        and Perl, there is no way to stop newline from matching [^a].
8723        there  is  no  way  to make PCRE2 behave exactly as for the REG_NEWLINE
8726        and REG_DOTALL passes PCRE2_DOTALL. There is no way to pass  PCRE2_DOL-
8732        The  function  regexec()  is  called  to  match a compiled pattern preg
8733        against a given string, which is by default terminated by a  zero  byte
8739        The PCRE2_NOTBOL option is set when calling the underlying PCRE2 match-
8744        The  PCRE2_NOTEMPTY  option  is  set  when calling the underlying PCRE2
8745        matching function. Note that REG_NOTEMPTY is  not  part  of  the  POSIX
8751        The PCRE2_NOTEOL option is set when calling the underlying PCRE2 match-
8756        The  string  is  considered to start at string + pmatch[0].rm_so and to
8759        nmatch. This is a BSD extension, compatible with but not  specified  by
8763        of the string, not how it is matched. Setting REG_STARTEND and  passing
8764        pmatch  as  NULL  are  mutually  exclusive;  the  error  REG_INVARG  is
8768        matched  strings  is  returned.  The  nmatch  and  pmatch  arguments of
8772        (unless  REG_STARTEND  is  set);  in both these cases no data about any
8773        matched strings is returned.
8786        defined  in  the  header  file,  of which REG_NOMATCH is the "expected"
8793        or  regexec()  to  a  printable message. If preg is not NULL, the error
8795        by  a binary zero is placed in errbuf. If the buffer is too short, only
8797        yield  of  the  function is the size of buffer needed to hold the whole
8798        message, including the terminating zero. This  value  is  greater  than
8834        PCRE2 is supplied in the file pcre2demo.c in the src directory  in  the
8835        PCRE2 distribution. A listing of this program is given in the pcre2demo
8839        The  demonstration  program compiles the regular expression that is its
8846        If the -g option is given on the command line, the program then goes on
8848        subject string. The logic is a little bit tricky because of the  possi-
8850        is going on.
8852        The code in pcre2demo.c is an 8-bit program that uses the  PCRE2  8-bit
8859        If  PCRE2  is installed in the standard include and library directories
8865        If PCRE2 is installed elsewhere, you may need to add additional options
8879        Note  that  there  is  a  much  more comprehensive test program, called
8882        though not all three need be installed). The pcre2demo program is  pro-
8885        If you try to run pcre2demo when PCRE2 is not installed in the standard
8892        This is caused by the way shared library support works  on  those  sys-
8935        form  instead  of  having to compile them every time the application is
8937        it is not possible to save and reload the JIT data, because it is posi-
8948        The facility for saving and restoring compiled patterns is intended for
8950        pcre2_serialize_decode()  is expected to be trusted data, not data from
8951        arbitrary external sources.  There  is  only  some  simple  consistency
8952        checking, not complete validation of what is being re-loaded.
8957        Before compiled patterns can be saved they must be serialized, that is,
8960        tables. A single copy of the tables is included in the byte stream (its
8961        size is 1088 bytes). For more details of character tables, see the sec-
8969        respectively.  The  final  argument  is a pointer to a general context,
8971        this  argument  is NULL, malloc() is used to obtain memory for the byte
8972        stream. The yield of the function is the number of serialized patterns,
8975          PCRE2_ERROR_BADDATA      the number of patterns is zero or less
8979          PCRE2_ERROR_NULL         the 1st, 3rd, or 4th argument is NULL
8986        appropriate manner. Here is sample code that compiles two patterns  and
8988        that is open for output. The error checking that should be present in a
9004        Note  that  the  serialized data is binary data that may contain any of
9006        between binary and non-binary data, be sure that the file is opened for
9020        ing from a file). The management of this memory  block  is  up  to  the
9032        final  argument is a pointer to a general context, which can be used to
9034        If this argument is NULL, malloc() and free() are used. After deserial-
9035        ization, the byte stream is no longer needed and can be discarded.
9043        If the vector is not large enough for all  the  patterns  in  the  byte
9044        stream,  it  is  filled  with  those  that  fit,  and the remainder are
9045        ignored. The yield of the function is the number of  decoded  patterns,
9048          PCRE2_ERROR_BADDATA    second argument is zero or less
9053          PCRE2_ERROR_NULL       first or third argument is NULL
9055        PCRE2_ERROR_BADMAGIC  may mean that the data is corrupt, or that it was
9059        freed  by  calling pcre2_code_free(). However, be aware that there is a
9062        single copy of the character tables is used by all the decoded patterns
9063        and a reference count is used to arrange for its memory to be automati-
9064        cally freed when the last pattern is freed, but there is no locking  on
9071        ized,  the  JIT data is discarded and so is no longer available after a
9104        sion depth increases. The match() function is also called in other cir-
9105        cumstances,  for  example,  whenever  a  parenthesized  sub-pattern  is
9112        result of the current call (a "tail recursion"), the function  is  just
9115        Each  time the internal match() function is called recursively, it uses
9118        "tail recursion". Note that if  PCRE2  is  compiled  with  the  -fsani-
9122        The above comments apply when pcre2_match() is run in its normal inter-
9131        pcre2_match(),  and uses recursion only when there is a regular expres-
9135        limit  on  the  complexity  of  pcre2_dfa_match()  is controlled by the
9136        amount of workspace it is given.  However, it is possible to write pat-
9138        pcre2_dfa_match() to run out of stack. At present, there is no  protec-
9147        of  stack  used,  by  modifying the pattern that is being matched. Con-
9153        end  of  the  data,  and is the kind of pattern that might be used when
9155        either  one  character that is not "<" or a "<" that is not followed by
9156        "inet". However, each time a  parenthesis  is  processed,  a  recursion
9158        ter. For a long string, a lot of stack is required. Consider  now  this
9165        sion  happens  only when a "<" character that is not followed by "inet"
9166        is encountered (and we assume this is relatively  rare).  A  possessive
9167        quantifier  is  used  to stop any backtracking into the runs of non-"<"
9168        characters, but that is not related to stack usage.
9171        ing long subject strings is to write repeated parenthesized subpatterns
9176        In environments where stack memory is constrained, you  might  want  to
9178        up points when pcre2_match() is running. This makes it run more slowly,
9182        memory is obtained by calling the system malloc() function, but you can
9186        ment customized a memory handler that is more efficient than the  stan-
9188        and re-used if possible while pcre2_match() is running.  They  are  all
9194        is called, both in total and  recursively.  If  a  limit  is  exceeded,
9198        PCRE2 is built, and they can also be set when pcre2_match() is  called.
9209        that  allow a a pattern to match. This is done by calling pcre2_match()
9214        In Unix-like environments, there is not often a problem with the  stack
9221        Unfortunately,  the  effect  of  running out of stack is often SIGSEGV,
9222        though sometimes a more explicit error message is given. You  can  nor-
9237        is also possible to set a stack size when linking a program. There is a
9272          \x         where x is non-alphanumeric is a literal x
9280          \a         alarm, that is, the BEL character (hex 07)
9281          \cx        "control-x", where x is any ASCII printing character
9290          \U         "U" if PCRE2_ALT_BSUX is set (otherwise is an error)
9291          \uhhhh     character with hex code hhhh (if PCRE2_ALT_BSUX is set)
9295        Note that \0dd is always an octal code. The treatment of backslash fol-
9296        lowed by a non-zero digit is complicated; for details see  the  section
9300        When \x is not followed by {, from zero to two hexadecimal  digits  are
9301        read, but if PCRE2_ALT_BSUX is set, \x must be followed by two hexadec-
9303        matches  a literal "x".  Likewise, if \u (in ALT_BSUX mode) is not fol-
9313          \D         a character that is not a decimal digit
9315          \H         a character that is not a horizontal white space character
9316          \N         a character that is not a newline
9321          \S         a character that is not a white space character
9323          \V         a character that is not a vertical white space character
9328        \C is dangerous because it may leave the current matching point in  the
9330        use of \C by setting the PCRE2_NEVER_BACKSLASH_C  option.  It  is  also
9335        matching  is  happening,  \s and \w may also match characters with code
9336        points in the range 128-255. If the PCRE2_UCP option is set, the behav-
9337        iour of these escape sequences is changed to use Unicode properties and
9450        default,  but  some of them use Unicode properties if PCRE2_UCP is set.
9480                        (after any newline if PCRE2_ALT_CIRCUMFLEX is set)
9495        \K is honoured in positive assertions, but ignored in negative ones.
9648        so only if the pattern is not anchored.
9655                          (*MARK:NAME); if not found, the (*SKIP) is ignored
9701        When PCRE2 is built with Unicode support (which is the default), it has
9704        However, by default, PCRE2 assumes that one code unit is one character.
9708        (*UTF). When either of these is the case, both the pattern and any sub-
9718        When  PCRE2 is built with Unicode support, the escape sequences \p{..},
9725        ter. Its Perl synonym, \p{Letter}, is not supported.   Furthermore,  in
9726        Perl,  many properties may optionally be prefixed by "Is", for compati-
9748        The use of \C is not supported by  the  alternative  matching  function
9749        pcre2_dfa_match() when in UTF-8 or UTF-16 mode, that is, when a charac-
9752        support \C in these modes. If JIT optimization is requested for a UTF-8
9754        pcre2_match() is called, the matching will be carried out by the normal
9761        remains  true  even  when  PCRE2  is  built to include Unicode support,
9767        acter  escapes  work  is changed so that Unicode properties are used to
9772        all low-valued characters, unless the PCRE2_UCP option is set.
9776        acters, whether or not PCRE2_UCP is set.
9785        When the PCRE2_UTF option is set, the strings passed  as  patterns  and
9787        functions.  If an invalid UTF string is passed, an negative error  code
9788        is  returned.  The  code  unit offset to the offending character can be
9790        which is used for this purpose after a UTF error.
9796        A UTF string is checked before any other processing takes place. In the
9798        starting  offset, the check is applied only to that part of the subject
9799        that could be inspected during matching, and there is a check that  the
9808        In  addition  to checking the format of the string, there is a check to
9818        other  words,  the  whole  surrogate  thing is a fudge for UTF-16 which
9823        mance, for example in the case of a long subject string that  is  being
9826        it is given (respectively) contains only valid UTF code unit sequences.
9833        If you pass an invalid UTF string when PCRE2_NO_UTF_CHECK is  set,  the
9834        result is undefined and your program may crash or loop indefinitely.
9849        nally defined by RFC 2279) allows for  up  to  6  bytes,  and  this  is
9859        the character do not have the binary value 0b10 (that  is,  either  the
9860        most significant bit is 0, or the next bit is 1).
9865        A  character that is valid by the RFC 2279 rules is either 5 or 6 bytes
9885        A  2-, 3-, 4-, 5-, or 6-byte character is "overlong", that is, it codes
9886        for a value that can be represented by fewer bytes, which  is  invalid.
9893        binary  value 0b10 (that is, the most significant bit is 1 and the sec-
9894        ond is 0). Such a byte can only validly occur as the second  or  subse-
9918          PCRE2_ERROR_UTF32_ERR2  Code point is greater than 0x10ffff