tcl7.6 C API - RegExp






NAME

     Tcl_RegExpMatch,     Tcl_RegExpCompile,      Tcl_RegExpExec,
     Tcl_RegExpRange - Pattern matching with regular expressions


SYNOPSIS

     #include <tcl.h>

     int
     Tcl_RegExpMatch(interp, string, pattern)

     Tcl_RegExp
     Tcl_RegExpCompile(interp, pattern)

     int
     Tcl_RegExpExec(interp, regexp, string, start)

     Tcl_RegExpRange(regexp, index, startPtr, endPtr)


ARGUMENTS

     Tcl_Interp   *interp   (in)      Tcl interpreter to use  for
                                      error reporting.

     char         *string   (in)      String to check for a match
                                      with a regular expression.

     char         *pattern  (in)      String in  the  form  of  a
                                      regular expression pattern.

     Tcl_RegExp   regexp    (in)      Compiled  regular   expres-
                                      sion.    Must   have   been
                                      returned   previously    by
                                      Tcl_RegExpCompile.

     char         *start    (in)      If string is just a portion
                                      of  some other string, this
                                      argument   identifies   the
                                      beginning   of  the  larger
                                      string.  If  it  isn't  the
                                      same  as  string, then no ^
                                      matches will be allowed.

     int          index     (in)      Specifies  which  range  is
                                      desired:  0 means the range
                                      of the entire match,  1  or
                                      greater   means  the  range
                                      that       matched        a
                                      parenthesized          sub-
                                      expression.

     char         **startPtr(out)     The address  of  the  first
                                      character  in  the range is
                                      stored  here,  or  NULL  if
                                      there is no such range.

     char         **endPtr  (out)     The address of the  charac-
                                      ter just after the last one
                                      in  the  range  is   stored
                                      here,  or  NULL if there is
                                      no such range.





DESCRIPTION

     Tcl_RegExpMatch  determines  whether  its  pattern  argument
     matches  regexp,  where  regexp  is interpreted as a regular
     expression using the same rules as for the regexp  Tcl  com-
     mand.   If  there is a match then Tcl_RegExpMatch returns 1.
     If there is no match then Tcl_RegExpMatch returns 0.  If  an
     error  occurs in the matching process (e.g. pattern is not a
     valid regular expression) then Tcl_RegExpMatch  returns  - 1
     and leaves an error message in interp->result.

     Tcl_RegExpCompile, Tcl_RegExpExec, and Tcl_RegExpRange  pro-
     vide  lower-level  access  to the regular expression pattern
     matcher.  Tcl_RegExpCompile compiles  a  regular  expression
     string  into  the  internal  form used for efficient pattern
     matching.  The return value is a  token  for  this  compiled
     form,   which   can   be   used   in   subsequent  calls  to
     Tcl_RegExpExec or Tcl_RegExpRange.  If an error occurs while
     compiling  the  regular  expression  then  Tcl_RegExpCompile
     returns NULL and leaves an error message in  interp->result.
     Note:  the return value from Tcl_RegExpCompile is only valid
     up to the next call to Tcl_RegExpCompile;  it is not safe to
     retain these values for long periods of time.

     Tcl_RegExpExec  executes  the  regular  expression   pattern
     matcher.  It returns 1 if string contains a range of charac-
     ters that match regexp, 0 if no match is found, and -1 if an
     error  occurs.   In  the  case  of  an error, Tcl_RegExpExec
     leaves an error message in interp->result.  When searching a
     string for multiple matches of a pattern, it is important to
     distinguish between the start of the original string and the
     start  of  the  current search.  For example, when searching
     for the second occurrence of a match,  the  string  argument
     might  point  to  the  character just after the first match;
     however, it is important for the  pattern  matcher  to  know
     that  this is not the start of the entire string, so that it
     doesn't allow ^ atoms in the pattern to  match.   The  start
     argument  provides this information by pointing to the start
     of the overall string containing string.  Start will be less
     than  or equal to string;  if it is less than string then no
     ^ matches will be allowed.
     Tcl_RegExpRange may be invoked after Tcl_RegExpExec returns;
     it  provides  detailed  information about what ranges of the
     string matched what parts of the  pattern.   Tcl_RegExpRange
     returns  a  pair  of  pointers in *startPtr and *endPtr that
     identify a range of characters in the source string for  the
     most  recent  call to Tcl_RegExpExec.  Index indicates which
     of several ranges is desired:  if index is 0, information is
     returned  about the overall range of characters that matched
     the entire  pattern;   otherwise,  information  is  returned
     about  the  range  of  characters  that matched the index'th
     parenthesized subexpression within the pattern.  If there is
     no  range  corresponding  to  index  then  NULL is stored in
     *firstPtr and *lastPtr.



KEYWORDS

     match, pattern, regular expression, string, subexpression