Tcl_RegExpMatch(3) Tcl (7.4) Tcl_RegExpMatch(3)
_________________________________________________________________
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
expression. 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
Page 1 (printed 2/19/99)
Tcl_RegExpMatch(3) Tcl (7.4) Tcl_RegExpMatch(3)
character in the range is
stored here, or NULL if
there is no such range.
char **endPtr (out) The address of the
character 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
command. 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 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
characters 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.
Page 2 (printed 2/19/99)
Tcl_RegExpMatch(3) Tcl (7.4) Tcl_RegExpMatch(3)
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
Page 3 (printed 2/19/99)
