Tcl_RegExpMatch(3)
_________________________________________________________________
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-expres-
sion.
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 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_RegExpCom-
pile returns NULL and leaves an error message in
interp->result. Note: the return value from Tcl_RegExp-
Compile is only valid up to the next call to Tcl_RegExp-
Compile; 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_RegEx-
pExec 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 orig-
inal 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
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; 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