6 Other matching functions

The following functions match a buffer of text against a regular expression, allowing the extraction of portions of text matching parenthetical subexpressions. All of them show the following behaviour:

• If the text matches the pattern: the return value is 1; if the text does not match the pattern: the return value is 0.
• If the pattern is invalid: the return value is 0; there is no way to distinguish this case from the case of text not matching other than looking at what RE2 prints to stderr.
• It is impossible to turn off logging of error messages to stderr when the specification of the regular expression is invalid.
• Data about the matching groups is stored in the array match, which must have at least nmatch slots; the referenced substrings are portions of the text buffer.
• The array match can have a number of slots between zero (included) and the number of parenthetical subexpressions in pattern (excluded); if nmatch is greater than the number of parenthetical subexpressions: the return value is 0.
• If we are only interested in verifying if the text matches the pattern or not: we can use NULL as match argument and 0 as nmatch argument.
• The first slot of match (index 0) references the portion of text matching the first parenthetical subexpression; the second slot of match (index 1) references the portion of text matching the second parenthetical subexpression; and so on.

see the documentation of each function for the differences.

The following example is a successful match:

const char *   pattern = "ci.*ut";
const char *   text    = "ciao salut";
cre2_string_t  input   = {
  .data   = text,
  .length = strlen(text)
};
int            result;
result = cre2_full_match(pattern, &input, NULL, 0);

result ⇒ 1

the following example is a successful match in which the parenthetical subexpression is ignored:

const char *   pattern = "(ciao) salut";
const char *   text    = "ciao salut";
cre2_string_t  input   = {
  .data   = text,
  .length = strlen(text)
};
int            result;
result = cre2_full_match(pattern, &input, NULL, 0);

result ⇒ 1

the following example is a successful match in which the portion of text matching the parenthetical subexpression is reported:

const char *   pattern = "(ciao) salut";
const char *   text    = "ciao salut";
cre2_string_t  input   = {
  .data   = text,
  .length = strlen(text)
};
int            nmatch  = 1;
cre2_string_t  match[nmatch];
int            result;
result = cre2_full_match(pattern, &input, match, nmatch);

result ⇒ 1
strncmp(text, input.data, input.length)         ⇒ 0
strncmp("ciao", match[0].data, match[0].length) ⇒ 0

Function: int cre2_full_match (const char * pattern, const cre2_string_t * text, cre2_string_t * match, int nmatch)

Function: int cre2_full_match_re (cre2_regexp_t * rex, const cre2_string_t * text, cre2_string_t * match, int nmatch)

Match the zero–terminated string pattern or the precompiled regular expression rex against the full buffer text.

For example: the text abcdef matches the pattern abcdef according to this function, but neither the pattern abc nor the pattern def will match.

Function: int cre2_partial_match (const char * pattern, const cre2_string_t * text, cre2_string_t * match, int nmatch)

Function: int cre2_partial_match_re (cre2_regexp_t * rex, const cre2_string_t * text, cre2_string_t * match, int nmatch)

Match the zero–terminated string pattern or the precompiled regular expression rex against the buffer text, resulting in success if a substring of text matches; these functions behave like the full match ones, but the matching text does not need to be anchored to the beginning and end.

For example: the text abcDEFghi matches the pattern DEF according to this function.

Function: int cre2_consume (const char * pattern, cre2_string_t * text, cre2_string_t * match, int nmatch)

Function: int cre2_consume_re (cre2_regexp_t * rex, cre2_string_t * text, cre2_string_t * match, int nmatch)

Match the zero–terminated string pattern or the precompiled regular expression rex against the buffer text, resulting in success if the prefix of text matches. The data structure referenced by text is mutated to reference text right after the last byte that matched the pattern.

For example: the text abcDEF matches the pattern abc according to this function; after the call text will reference the text DEF.

Function: int cre2_find_and_consume (const char * pattern, cre2_string_t * text, cre2_string_t * match, int nmatch)

Function: int cre2_find_and_consume_re (cre2_regexp_t * rex, cre2_string_t * text, cre2_string_t * match, int nmatch)

Match the zero–terminated string pattern or the precompiled regular expression rex against the buffer text, resulting in success if, after skipping a non–matching prefix in text, a substring of text matches. The data structure referenced by text is mutated to reference text right after the last byte that matched the pattern.

For example: the text abcDEFghi matches the pattern DEF according to this function; the prefix abc is skipped; after the call text will reference the text ghi.

This document describes version 0.4.0-devel.2 of CRE2.