Tcl_RegExpMatch(3) Tcl Library Procedures 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-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 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_Reg‐
ExpMatch 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_RegExpCom‐
pile 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 mes‐
sage 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 argu‐
ment 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 pro‐
vides 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 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
Tcl 7.4 Tcl_RegExpMatch(3)