NAME

       Tcl_RegExpMatch,     Tcl_RegExpCompile,    Tcl_RegExpExec,
       Tcl_RegExpRange - Pattern matching  with  regular  expres-
       sions

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  pat-
                                        tern.

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

       char         *start    (in)      If  string is just a por-
                                        tion   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-
                                        character in the range is
                                        stored here, or  NULL  if
                                        there is no such range.

       char         **endPtr  (out)     The  address of the char-
                                        acter 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
       provide lower-level access to the regular expression  pat-
       tern   matcher.    Tcl_RegExpCompile  compiles  a  regular
       expression string into the internal form  used  for  effi-
       cient  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 char-
       acters  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 infor-
       mation by pointing to the start of the overall string con-
       taining string.  Start will  be  less  than  or  equal  to

       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;  oth-
       erwise, information is returned about the range of charac-
       ters 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