René Nyffenegger's collection of things on the web
René Nyffenegger on Oracle - Most wanted - Feedback -
 

Functions in PCRE

PCRE has the following functions if pcre.h is included. 
#include <pcre.h>
The functions pcre_compile(), pcre_study() and pcre_exec() are used for compiling and matching regular expressions.
See test 1 for a demonstration of pcre_compile and pcre_exec.

pcre_compile

pcre *pcre_compile (
        const          char  *pattern, 
                       int    options,
        const          char **errptr,  
                       int   *erroffset,
        const unsigned char  *tableptr);
The following options are available:
  • PCRE_ANCHORED
  • PCRE_CASELESS
  • PCRE_DOLLAR_ENDONLY
  • PCRE_DOTALL
  • PCRE_EXTENDED
  • PCRE_EXTRA
  • PCRE_MULTILINE
  • PCRE_NO_AUTO_CAPTURE
  • PCRE_UNGREEDY
  • PCRE_UTF8
  • PCRE_NO_UTF8_CHECK
pcre_maketables creates a character table that is passed through the tableptr parameter.

pcre_study

pcre_extra *pcre_study(
        const pcre  *code, 
              int    options,
        const char **errptr);
A pattern can be studied for better execution time in pcre_exec. This makes sense if the same patterns is used several times.
Currently, there are no options available.
If pcre_study does not find out details to improve execution times, it returns null.
The returned pcre_extra* can be passed as the extra parameter in pcre_exec.

pcre_exec

int pcre_exec(
        const pcre       *code, 
        const pcre_extra *extra,
        const char       *subject, 
              int         length, 
              int         startoffset,
              int         options, 
              int        *ovector, 
              int         ovecsize);
pcre_exec matches a string against a pattern.
The following options can be specified:
  • PCRE_ANCHORED
  • PCRE_NOTBOL
  • PCRE_NOTEMPTY
If the pattern had been studied with pcre_study, the returned findings can be passed in extra.
failure if pcre_exec fails, it returns one of the following negative numbers:
  • PCRE_ERROR_NOMATCH
  • PCRE_ERROR_NULL
  • PCRE_ERROR_BADOPTION
  • PCRE_ERROR_BADMAGIC
  • PCRE_ERROR_UNKNOWN_NODE
  • PCRE_ERROR_NOMEMORY
  • PCRE_ERROR_NOSUBSTRING
  • PCRE_ERROR_MATCHLIMIT
  • PCRE_ERROR_CALLOUT
  • PCRE_ERROR_BADUTF8

pcre_copy_named_substring

int pcre_copy_named_substring(
        const pcre *code,
        const char *subject, 
              int  *ovector,
              int  stringcount, 
        const char *stringname,
              char *buffer, 
              int  buffersize);

pcre_copy_substring

int pcre_copy_substring(
         const char *subject, 
               int  *ovector,
               int   stringcount, 
               int   stringnumber, 
               char *buffer,
               int   buffersize);

pcre_get_named_substring

int pcre_get_named_substring(
          const pcre *code,
          const char *subject, 
                int  *ovector,
                int  stringcount, 
          const char *stringname,
          const char **stringptr);

pcre_get_stringnumber

int pcre_get_stringnumber(
          const pcre *code,
          const char *name);

pcre_get_substring

int pcre_get_substring(
          const char  *subject, 
                int   *ovector,
                int    stringcount, 
                int    stringnumber,
          const char **stringptr);

pcre_get_substring_list

int pcre_get_substring_list(
          const char   *subject,
                int    *ovector, 
                int     stringcount, 
          const char ***listptr);

pcre_free_substring

void pcre_free_substring(const char *stringptr);

pcre_free_substring_list

void pcre_free_substring_list(const char **stringptr);

pcre_maketables

const unsigned char *pcre_maketables(void);
pcre_maketables is (optionally) used to build a set of character tables in the current locale which is then used in pcre_compile. 
setlocale(LC_CTYPE, "fr");
tables = pcre_maketables();
re     = pcre_compile(..., tables);

pcre_fullinfo

int pcre_fullinfo(
          const pcre       *code, 
          const pcre_extra *extra,
                int         what, 
                void       *where);
Returns information about compiled patterns. (pcre_info is obsolete).
The following whats can be specified:
  • PCRE_INFO_BACKREFMAX
  • PCRE_INFO_CAPTURECOUNT
  • PCRE_INFO_FIRSTBYTE
  • PCRE_INFO_FIRSTTABLE
  • PCRE_INFO_LASTLITERAL
  • PCRE_INFO_NAMECOUNT
  • PCRE_INFO_NAMEENTRYSIZE
  • PCRE_INFO_NAMETABLE
  • PCRE_INFO_OPTIONS
  • PCRE_INFO_SIZE
  • PCRE_INFO_STUDYSIZE

pcre_info

int pcre_info(
          const pcre *code, 
                int  *optptr, 
                     *firstcharptr);
pcre_info is obsolete, use pcre_fullinfo instead.

pcre_config

int pcre_config(int what, void *where);
Used to find out which PCRE features are available. These features were determined at compile time of pcre.
The following features can be detected:
  • PCRE_CONFIG_UTF8
  • PCRE_CONFIG_NEWLINE
  • PCRE_CONFIG_LINK_SIZE
  • PCRE_CONFIG_POSIX_MALLOC_THRESHOLD
  • PCRE_CONFIG_MATCH_LIMIT

pcre_version

char *pcre_version(void);

pcre_malloc

void *(*pcre_malloc)(size_t);

pcre_free

void (*pcre_free)(void *);

pcre_callout

int (*pcre_callout)(pcre_callout_block *);

pcre_extra

typedef struct pcre_extra {
  unsigned long int    flags;        /* Bits for which fields are set */
  void                *study_data;   /* Opaque data from pcre_study() */
  unsigned long int    match_limit;  /* Maximum number of calls to match() */
  void                *callout_data; /* Data passed back in callouts */
  const unsigned char *tables;       /* Pointer to character tables */
} pcre_extra;
flags allows to set bits. The following bits are specified:
  • PCRE_EXTRA_STUDY_DATA
  • PCRE_EXTRA_MATCH_LIMIT
  • PCRE_EXTRA_CALLOUT_DATA

Thanks

Thanks to Robby Villegas who notified me of an error on this page.