overview (C wrapper for RE2)

CRE2 is a C language wrapper for the C++ library RE2: a fast, safe, thread–friendly alternative to backtracking regular expression engines like those used in PCRE, Perl, and Python. CRE2 is based on code by Keegan McAllister for the haskell-re2 binding:

For the supported regular expressions syntax we should refer to the original documentation:

The C wrapper is meant to make it easier to interface RE2 with other languages. The exposed API allows searching for substrings of text matching regular expressions and reporting portions of text matching parenthetical subexpressions.

CRE2 installs the single header file cre2.h. All the function names in the API are prefixed with cre2_; all the constant names are prefixed with CRE2_; all the type names are prefixed with cre2_ and suffixed with _t.

It is customary for regular expression engines to provide methods to replace backslash sequences like \1, \2, … in a given string with portions of text that matched the first, second, … parenthetical subexpression; CRE2 does not provide such methods in its public API, because they require interacting with the storage mechanism in the client code. However, it is not difficult to implement such substitutions given the results of a regular expression matching operation.

Some functions and methods from RE2 requiring memory allocation handling are unofficially wrapped by CRE2 with unsafe code (execution will succeed when no memory allocation errors happen). These “problematic” functions are documented in the header file cre2.h and, at present, are not considered part of the public API of CRE2.

It is sometimes useful to try a program in the original C++ to verify if a problem is caused by CRE2 or is in the original RE2 code; we may want to start by customising this program:

/* compile and run with:

   $ g++ -pthread -Wall -o proof proof.cpp -lre2 && ./proof
*/

#include <re2/re2.h>
#include <assert.h>

static void try_match (RE2::Options& opt, const char * text);

int
main (void)
{
  RE2::Options opt;
  opt.set_never_nl(true);
  try_match(opt, "abcdef");
  return 0;
}
void
try_match (RE2::Options& opt, const char * text)
{
  RE2 re("abcdef", opt);
  assert(re.ok());
  assert(RE2::FullMatch(text, re));
  assert(RE2::PartialMatch(text, re));
}

1 Overview of the package